From mboxrd@z Thu Jan 1 00:00:00 1970 From: Grant Rettke Subject: Re: Thoughts on weaving variable documentation Date: Tue, 24 Jun 2014 09:00:53 -0500 Message-ID: References: <864mzacxi5.fsf@somewhere.org> Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:45999) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WzRHN-0006YJ-Nc for emacs-orgmode@gnu.org; Tue, 24 Jun 2014 10:01:03 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1WzRHK-0006zC-74 for emacs-orgmode@gnu.org; Tue, 24 Jun 2014 10:00:57 -0400 Received: from mail-ob0-x234.google.com ([2607:f8b0:4003:c01::234]:55697) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WzRHK-0006z4-1p for emacs-orgmode@gnu.org; Tue, 24 Jun 2014 10:00:54 -0400 Received: by mail-ob0-f180.google.com with SMTP id vb8so362747obc.11 for ; Tue, 24 Jun 2014 07:00:53 -0700 (PDT) In-Reply-To: <864mzacxi5.fsf@somewhere.org> List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org To: Fabrice Niessen Cc: "emacs-orgmode@gnu.org" Fabrice, Thank you for sharing that kind reminder and true inspiration. Looking forward to your results. Kind regards, gcr Grant Rettke | ACM, ASA, FSF, IEEE, SIAM gcr@wisdomandwonder.com | http://www.wisdomandwonder.com/ =E2=80=9CWisdom begins in wonder.=E2=80=9D --Socrates ((=CE=BB (x) (x x)) (=CE=BB (x) (x x))) =E2=80=9CLife has become immeasurably better since I have been forced to st= op taking it seriously.=E2=80=9D --Thompson On Tue, Jun 24, 2014 at 7:17 AM, Fabrice Niessen w= rote: > Hello Grant, > >> A lot of people are weaving their Emacs init files for the obvious >> reason: it is difficult to remember why >> we configured stuff and other people definitely won't know why we did >> it. There is a common operation >> that occurs though when other people read our Emacs init: >> >> 1. They open it up in Emacs >> 2. Find what looks interesting >> 3. Do a C-h f or C-h v on it and learn about it >> >> Makes total sense. >> >> What I got curious about is for this specific use case, people >> scanning other people's configs, how I could make it easier. > > Remember the following quote of Knuth: > > =E2=95=AD=E2=94=80=E2=94=80=E2=94=80=E2=94=80 > =E2=94=82 Let us change our traditional attitude to the construction of > =E2=94=82 programs: Instead of imagining that our main task is to instr= uct > =E2=94=82 a computer what to do, let us concentrate rather on explainin= g to > =E2=94=82 human beings what we want a computer to do. > =E2=94=82 > =E2=94=82 The practitioner of literate programming can be regarded as a= n > =E2=94=82 essayist, whose main concern is with exposition and excellenc= e of > =E2=94=82 style. Such an author, with thesaurus in hand, chooses the na= mes of > =E2=94=82 variables carefully and explains what each variable means. He= or she > =E2=94=82 strives for a program that is comprehensible because its conc= epts > =E2=94=82 have been introduced in an order that is best for human > =E2=94=82 understanding, using a mixture of formal and informal methods= that > =E2=94=82 reinforce each other. > =E2=95=B0=E2=94=80=E2=94=80=E2=94=80=E2=94=80 > > Hence, for me, people scanning your config should read the document that > you've made therefore (that is, the weaved document), not the file > that's made for a computer (that is, the tangle document). > > If there are parts you don't want others to see, tag them as > ":noexport:" or similar more subtle ways. > > As a guy convinced by LP, I wouldn't invest much time into facilitating > the reading of the tangled file; I would, on the opposite, invest a lot > of time (and I did -- results will be public soon on my Web site and on > GitHub!) on the weaved document, by improving CSS for the HTML version > and LaTeX styles. > >> A thought is to weave the docstrings for variables right into the >> weaved file any time a variable is set. I am thinking something like >> this: >> >> 1. When the weave occurs >> 2. Look at each line of code that starts with a setq >> 3. Look up the docstring for the variable >> 4. TBD: Weave that documentation into the output. >> >> That is the idea, at least. >> >> My question is: >> 1. What are the standard mechanisms to do something like this within >> the ob lifecycle? >> 2. What do you think in general? > > Best regards, > Fabrice > > -- > Fabrice Niessen > Leuven, Belgium > http://www.pirilampo.org/ > >