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/
