[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [O] Thoughts on weaving variable documentation
From: |
Grant Rettke |
Subject: |
Re: [O] Thoughts on weaving variable documentation |
Date: |
Tue, 24 Jun 2014 09:00:53 -0500 |
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
address@hidden | 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 <address@hidden> 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/
>
>