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 g...@wisdomandwonder.com | http://www.wisdomandwonder.com/ “Wisdom begins in wonder.” --Socrates ((λ (x) (x x)) (λ (x) (x x))) “Life has become immeasurably better since I have been forced to stop taking it seriously.” --Thompson On Tue, Jun 24, 2014 at 7:17 AM, Fabrice Niessen <fni-n...@pirilampo.org> wrote: > 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: > > ╭──── > │ Let us change our traditional attitude to the construction of > │ programs: Instead of imagining that our main task is to instruct > │ a computer what to do, let us concentrate rather on explaining to > │ human beings what we want a computer to do. > │ > │ The practitioner of literate programming can be regarded as an > │ essayist, whose main concern is with exposition and excellence of > │ style. Such an author, with thesaurus in hand, chooses the names of > │ variables carefully and explains what each variable means. He or she > │ strives for a program that is comprehensible because its concepts > │ have been introduced in an order that is best for human > │ understanding, using a mixture of formal and informal methods that > │ reinforce each other. > ╰──── > > 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/ > >
