From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp10.migadu.com ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms5.migadu.com with LMTPS id mN/mHjbEumIVIAAAbAwnHQ (envelope-from ) for ; Tue, 28 Jun 2022 11:04:54 +0200 Received: from aspmx1.migadu.com ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp10.migadu.com with LMTPS id 6Gb3HTbEumI4lwAAG6o9tA (envelope-from ) for ; Tue, 28 Jun 2022 11:04:54 +0200 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id 043342CE28 for ; Tue, 28 Jun 2022 11:04:53 +0200 (CEST) Received: from localhost ([::1]:36934 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1o679R-0007jv-1n for larch@yhetil.org; Tue, 28 Jun 2022 05:04:53 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:54676) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1o64gU-0004gv-5H for emacs-orgmode@gnu.org; Tue, 28 Jun 2022 02:26:51 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:53248) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1o64gT-0003hN-T2 for emacs-orgmode@gnu.org; Tue, 28 Jun 2022 02:26:49 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=To:Subject:Date:From:In-Reply-To:References: MIME-Version; bh=QGKJqImJNs6KjQP00izJIZx/RM/R10OYnn6cmMxe+Ic=; b=r89xVA/pHFKJ vAGR8j/UuG0Jf31zE8WdQh5x9hH51WQtEkmvzzx3kQeLwjGlY5Y3XyqSOr86qEaw6TuOpvdWoXHvV 8vh0zGmON+A80G7Lbe0F4leC68x5X6qhTxog3Eq1fCF8yMrxT+ds0yo6KSpm3ZBSnc8k3d6jq/kwp MXwuKnHJXA1e+j9Kyx9/Tvxbn3eNwytj9Xzta2ovK+/UEEnWa6uikkbKV2pTbNEDGlR0/B/XDQAC9 euev8RuXBmvCPnovgOSk9GMHlX2Zg6NjZDpQ01l4VmUJ+ASj2HzCwN4fL/TeXN7C/l/VTzpZhVpiR N5YILGgJ77ms5udMMaTvCg==; Received: from mail-yw1-f182.google.com ([209.85.128.182]:33389) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1o64gT-0002uE-Mh for emacs-orgmode@gnu.org; Tue, 28 Jun 2022 02:26:49 -0400 Received: by mail-yw1-f182.google.com with SMTP id 00721157ae682-317710edb9dso106952387b3.0 for ; Mon, 27 Jun 2022 23:26:49 -0700 (PDT) X-Gm-Message-State: AJIora+yYc7DGAehsiZkY8hF9BiHFoL1KwYMOttXN0YLY7R/kDrYk1nw M4WWmV4BkpdPn6vCyQWieeMAtv+XUxSKWSF+hFA= X-Google-Smtp-Source: AGRyM1sDpw9nY8Xvb+OVqVEem1lQDjwKWeoFiWEjpgsj2qOsf7vk/xrNNHfs9D4PgePeGblk34qxWZswPpl1LSZuhiY= X-Received: by 2002:a81:57d7:0:b0:317:b111:34d5 with SMTP id l206-20020a8157d7000000b00317b11134d5mr19582800ywb.7.1656397608982; Mon, 27 Jun 2022 23:26:48 -0700 (PDT) MIME-Version: 1.0 References: In-Reply-To: From: Robert Weiner Date: Tue, 28 Jun 2022 02:26:23 -0400 X-Gmail-Original-Message-ID: Message-ID: Subject: Re: Org, Hyperbole, and eev To: Eduardo Ochs Cc: Org Mode Content-Type: multipart/alternative; boundary="00000000000017217005e27c1fc0" X-BeenThere: emacs-orgmode@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: rswgnu@gmail.com Errors-To: emacs-orgmode-bounces+larch=yhetil.org@gnu.org Sender: "Emacs-orgmode" X-Migadu-Flow: FLOW_IN X-Migadu-To: larch@yhetil.org X-Migadu-Country: US ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1656407094; h=from:from:sender:sender:reply-to:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type:in-reply-to:in-reply-to: references:references:list-id:list-help:list-unsubscribe: list-subscribe:list-post:dkim-signature; bh=QGKJqImJNs6KjQP00izJIZx/RM/R10OYnn6cmMxe+Ic=; b=mkItsufRKggopgk47+fjpnp1NWx5thUr5PUoeGwA615vimSkPpu6/KY/zPQsFzzJLA3MIt OVjk31bWuh7SHdvF77ljVjdnfrRZFA78L56LXwnjlHNpPzrYtvPUJtwXPS0Uip/1uU1Tc/ A7Qg6DH66Wi8q6/dwEF1wRF+sgb+B6u5LFeq2twc639I4gJ4N3c4CV9bXHCB/eVBTbpvbv pk2s0BQ3/rZf1Ar8eZljpTnfcFY09tGa7aUAap5AOYzlL4HfEsmNMpBYxwuNs20OejoABO 13bCVCELy0GGG7UfX4Bqnj5MtMWHOxGyCVQHvn79AmxeYLLabgqbRRIcU52TnQ== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1656407094; a=rsa-sha256; cv=none; b=rb38DGEPH07/xmNhzJpsUI6R+f0EVozo3tPvRiwB+C2RRT9YjjYeie/4KGZH7t8m55SYA0 SaK/96496rSrCAPX1U9HNYxBQWnauBIQmv5lVrKIhMkYgrrL7rz4MRCEqgNCxCHtGOSPWH dA2YzRe+pKP9dzQJy2iNKDjPDfptsBOuI+YKObrfqd/cpoP3mtCc71ZfpEERqfDxwpiII+ XJ9pBY40932JuMeceUs6zV2i+8eb4uE6vM0CJnWCw4wQXGf7czMjRewaYdXxHMalL6SaK6 qhgu8e7S2OvU8bxVTytt3gppzvUvqmKqtf/VK4lINd0Y08fAvlsFJgtq3Lu93w== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=gnu.org header.s=fencepost-gnu-org header.b="r89xVA/p"; dmarc=pass (policy=none) header.from=gnu.org; spf=pass (aspmx1.migadu.com: domain of "emacs-orgmode-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="emacs-orgmode-bounces+larch=yhetil.org@gnu.org" X-Migadu-Spam-Score: -6.55 Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=gnu.org header.s=fencepost-gnu-org header.b="r89xVA/p"; dmarc=pass (policy=none) header.from=gnu.org; spf=pass (aspmx1.migadu.com: domain of "emacs-orgmode-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="emacs-orgmode-bounces+larch=yhetil.org@gnu.org" X-Migadu-Queue-Id: 043342CE28 X-Spam-Score: -6.55 X-Migadu-Scanner: scn0.migadu.com X-TUID: iALCe90PXQ1u --00000000000017217005e27c1fc0 Content-Type: text/plain; charset="UTF-8" Hi Eduardo: Many programmers refuse to document almost anything and expect the code to speak for itself. Or they throw random comments throughout their code that don't help elucidate things. The nice thing about most Elisp code is that the inputs and outputs of functions are often pretty well documented, since people learn from many good examples. I support you in wanting to document and explain things very clearly for your readers. For most people, Hyperbole is extensively documented down to the function-level. But you want an 'atomic'-level description of the internals of Hyperbole which I think would be useful to only a very small population. Good programming is about producing and layering clean abstractions that sometimes must mask internal complexity and expose only the interfaces necessary for use (could be a UI, an API or a class abstraction). It's not turtles all the way down as the 'physics' of different levels of implementation varies. Hackers do build from lego blocks; they don't spend their time trying to deconstruct everything just to get comfortable with every component they use, in general. If you want to spend years trying to wrap your mind around something a bit complex then read The Art of the Meta-object Protocol many times. Then, if you survive, come back to Hyperbole and its call tree will seem simple to you :-) Seriously though, I get that you learn and document differently than many other people, so just do your own thing, your own way. I am reminded of the Hudsucker Proxy where the 'rube' is derided for his stupid idea until later it turns out to be one of the most profitable inventions in history. Maybe the rest of us just can't see what you see because of the way you express it, though if we could, we would be enthralled. I know a bit what that is like! Best of luck, -- rsw On Tue, Jun 28, 2022 at 12:48 AM Eduardo Ochs wrote: > On Sun, 26 Jun 2022 at 21:50, Robert Weiner wrote: > > > > So here is a simple implementation that is not unlike your own > > though the functions are a bit simpler and more clearly documented > > _without a listing of every possible test case type_ and requires > > neither Hyperbole nor Org until you want to activate things as > > buttons: > > > Hi Robert, > > I think that the part in "_..._"s above deserves a detailed answer. > > I started using GNU/Linux in the mid-90s. Before that my favorite > languages were Icon and Forth. In Forth I could do AMAZING things in > less than 50 lines of code, but my programs would usually become > confusing and unmanageable when they grew bigger than that. > > There is a famous book by Fred Brooks called "The Mythical Man-Month", > and one of its chapters is called "Plan to Throw One Away": > > https://wiki.c2.com/?PlanToThrowOneAway > > I took that slogan seriously. Most of the time when I realized that > something that I was doing by hand could be automated I would write a > first attempt to automate it - _as a prototype_, that I regarded > partly a program and partly as a way to help me think how that task > could be structured, and that would probably be "thrown away" if I > needed a cleaner solution later. > > In Forth it was very easy to implement both strange interfaces and > little languages, in this sense: > > https://wiki.c2.com/?LittleLanguage > > In Emacs less so, but I could still do lots of funny things using > eval-last-sexp to use sexps as buttons. > > When we are writing throwaway code "planning to throw one away" then > using tests in comments is a very good way to document the code. And > when I rewrite my prototypes I usually prefer to document them using > text ***AND*** executable examples rather than just text. One of the > effects of using this style is that the users of eev see that they can > use that style in their notes too - and with that their notes become > much closer to being "executable notes", in this sense, > > http://angg.twu.net/eev-intros/find-here-links-intro.html > > than they would be if they believed that they had to write the docs of > their functions as just text. > > You are sort of saying that having tests in comments is bad style. > Well, it's not. =/ > > [[]], > Eduardo Ochs > http://angg.twu.net/#eev > --00000000000017217005e27c1fc0 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
Hi Eduardo:

Many programmers refuse to document almost = anything and expect the code to speak for itself.=C2=A0 Or they throw rando= m comments throughout their code that don't help elucidate things.=C2= =A0 The nice thing about most Elisp code is that the inputs and outputs of = functions are often pretty well documented, since people learn from many go= od examples.=C2=A0 I support you in wanting to document and explain things = very clearly for your readers.=C2=A0 For most people, Hyperbole is extensiv= ely documented down to the function-level.=C2=A0 But you want an 'atomi= c'-level description of the internals of Hyperbole which I think would = be useful to only a very small population.

Good programming is about= producing and layering clean abstractions that sometimes must mask interna= l complexity and expose only the interfaces necessary for use (could be a U= I, an API or a class abstraction).=C2=A0 It's not turtles all the way d= own as the 'physics' of different levels of implementation varies.= =C2=A0 Hackers do build from lego blocks; they don't spend their time t= rying to deconstruct everything just to get comfortable with every=C2=A0com= ponent they use, in general.=C2=A0 If you want to spend years trying to wra= p your mind around something a bit complex then read The Art of the Meta-ob= ject Protocol many times.=C2=A0 Then, if you survive, come back to Hyperbol= e and its call tree will seem simple to you :-)

Seriously though, I = get that you learn and document differently than many other people, so just= do your own thing, your own way.=C2=A0 I am reminded of the Hudsucker Prox= y where the 'rube' is derided for his stupid idea until later it tu= rns out to be one of the most profitable inventions in history.=C2=A0 Maybe= the rest of us just can't see what you see because of the way you expr= ess it, though if we could, we would be enthralled.=C2=A0 I know a bit what= that is like!

Best of luck,

-- rsw

On Tue, Jun 28, 2022= at 12:48 AM Eduardo Ochs <edua= rdoochs@gmail.com> wrote:
On Sun, 26 Jun 2022 at 21:50, Robert Weiner <rsw@gnu.org> wrote:
>
> So here is a simple implementation that is not unlike your own
> though the functions are a bit simpler and more clearly documented
> _without a listing of every possible test case type_ and requires
> neither Hyperbole nor Org until you want to activate things as
> buttons:


Hi Robert,

I think that the part in "_..._"s above deserves a detailed answe= r.

I started using GNU/Linux in the mid-90s. Before that my favorite
languages were Icon and Forth. In Forth I could do AMAZING things in
less than 50 lines of code, but my programs would usually become
confusing and unmanageable when they grew bigger than that.

There is a famous book by Fred Brooks called "The Mythical Man-Month&q= uot;,
and one of its chapters is called "Plan to Throw One Away":

=C2=A0 https://wiki.c2.com/?PlanToThrowOneAway

I took that slogan seriously. Most of the time when I realized that
something that I was doing by hand could be automated I would write a
first attempt to automate it - _as a prototype_, that I regarded
partly a program and partly as a way to help me think how that task
could be structured, and that would probably be "thrown away" if = I
needed a cleaner solution later.

In Forth it was very easy to implement both strange interfaces and
little languages, in this sense:

=C2=A0 https://wiki.c2.com/?LittleLanguage

In Emacs less so, but I could still do lots of funny things using
eval-last-sexp to use sexps as buttons.

When we are writing throwaway code "planning to throw one away" t= hen
using tests in comments is a very good way to document the code. And
when I rewrite my prototypes I usually prefer to document them using
text ***AND*** executable examples rather than just text. One of the
effects of using this style is that the users of eev see that they can
use that style in their notes too - and with that their notes become
much closer to being "executable notes", in this sense,

=C2=A0 http://angg.twu.net/eev-intros/find-= here-links-intro.html

than they would be if they believed that they had to write the docs of
their functions as just text.

You are sort of saying that having tests in comments is bad style.
Well, it's not. =3D/

=C2=A0 [[]],
=C2=A0 =C2=A0 Eduardo Ochs
=C2=A0 =C2=A0 http://angg.twu.net/#eev
--00000000000017217005e27c1fc0--