From: Fabrice Niessen <fni-news-TA4HMoP+1wHrZ44/DZwexQ@public.gmane.org>
To: emacs-orgmode-mXXj517/zsQ@public.gmane.org
Subject: Re: Thoughts on weaving variable documentation
Date: Tue, 24 Jun 2014 14:17:38 +0200 [thread overview]
Message-ID: <864mzacxi5.fsf@somewhere.org> (raw)
In-Reply-To: CAAjq1mcOv-o48DT3pShkySpSDaL_6NgLFeTGwJyi81Ag0QaYSw@mail.gmail.com
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/
next prev parent reply other threads:[~2014-06-24 12:17 UTC|newest]
Thread overview: 6+ messages / expand[flat|nested] mbox.gz Atom feed top
2014-06-20 16:10 Thoughts on weaving variable documentation Grant Rettke
2014-06-20 16:11 ` Grant Rettke
2014-06-21 5:58 ` Aaron Ecay
2014-06-21 23:20 ` Grant Rettke
2014-06-24 12:17 ` Fabrice Niessen [this message]
2014-06-24 14:00 ` Grant Rettke
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=864mzacxi5.fsf@somewhere.org \
--to=fni-news-ta4hmop+1whrz44/dzwexq@public.gmane.org \
--cc=emacs-orgmode-mXXj517/zsQ@public.gmane.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).