From mboxrd@z Thu Jan 1 00:00:00 1970 From: Fabrice Niessen Subject: Re: Thoughts on weaving variable documentation Date: Tue, 24 Jun 2014 14:17:38 +0200 Message-ID: <864mzacxi5.fsf@somewhere.org> References: Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Return-path: 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-mXXj517/zsQ@public.gmane.org Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org-mXXj517/zsQ@public.gmane.org To: emacs-orgmode-mXXj517/zsQ@public.gmane.org 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 instruct =E2=94=82 a computer what to do, let us concentrate rather on explaining = to =E2=94=82 human beings what we want a computer to do. =E2=94=82=20 =E2=94=82 The practitioner of literate programming can be regarded as an =E2=94=82 essayist, whose main concern is with exposition and excellence = of =E2=94=82 style. Such an author, with thesaurus in hand, chooses the name= s of =E2=94=82 variables carefully and explains what each variable means. He o= r she =E2=94=82 strives for a program that is comprehensible because its concep= ts =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 t= hat =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 --=20 Fabrice Niessen Leuven, Belgium http://www.pirilampo.org/