Thoughts on weaving variable documentation

Thoughts on weaving variable documentation

[Grant Rettke]

Good morning,

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. 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?

Kind regards,

Grant Rettke | ACM, ASA, FSF, IEEE, SIAM
gcr@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

Re: Thoughts on weaving variable documentation

[Grant Rettke]

org-docco is something that comes to mind:

http://orgmode.org/worg/org-contrib/index.html
Grant Rettke | ACM, ASA, FSF, IEEE, SIAM
gcr@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 Fri, Jun 20, 2014 at 11:10 AM, Grant Rettke <gcr@wisdomandwonder.com> wrote:
> Good morning,
>
> 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. 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?
>
> Kind regards,
>
> Grant Rettke | ACM, ASA, FSF, IEEE, SIAM
> gcr@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

Re: Thoughts on weaving variable documentation

[Aaron Ecay]

Hi Grant,

2014ko ekainak 20an, Grant Rettke-ek idatzi zuen:
> 
> Good morning,
> 
> 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. 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?

I don’t really see the use case.  One of the best parts of developing
elisp in emacs is the level of interactive documentation:
describe-function, find-function, interactive info manuals, etc.  It’s
there when you need it, but not in the way when you don’t.  I almost
never read elisp code in a non-emacs environment (except for short
snippets in blog posts, I suppose).

FWIW, my wishlist for literate programming in org/elisp is something
like (in approximately increasing order of estimated difficulty):

- allow find-function/variable to jump to the location in an org file
  where something is defined, rather than the tangled elisp file.
  
- allow org-mode text “near” a function definition to be used as the
  function’s docstring (for describe-function et al.):

,----
| docstring docstring docstring
| #+begin_src elisp
|   (defun foo ()
|     ...)
| #+end_src
`----

rather than:

,----
| #+begin_src elisp
|   (defun foo ()
|     "docstring docstring docstring"
|     ...)
| #+end_src
`----

- allow more features of underlying source code editing modes to be used
  in org buffers directly (no org-edit-special context switch needed).
  For me, this would include:
  - eval-defun (C-M-x)
  - paredit
  - eldoc
  - auto-complete (company etc.)
  For your use case, a mode which shows the docstring for a fn/var in a
  tooltip on mouseover/keystroke could be added (I couldn’t find
  anything like this already existing for emacs-lisp-mode, which is
  kind of surprising to me – but I did not look very hard)

- make it easier to develop parts of org using these LP features.

Cheers,

-- 
Aaron Ecay

Re: Thoughts on weaving variable documentation

[Grant Rettke]

Understood. Thanks for sharing and elaborating.

The use case on my mind was for people scouring the Internet for
interesting things
inside of other people's configuration files.

That is what I did for a while, but now I just load stuff and use
Emacs to read the documentation.

Grant Rettke | ACM, ASA, FSF, IEEE, SIAM
gcr@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 Sat, Jun 21, 2014 at 12:58 AM, Aaron Ecay <aaronecay@gmail.com> wrote:
> Hi Grant,
>
> 2014ko ekainak 20an, Grant Rettke-ek idatzi zuen:
>>
>> Good morning,
>>
>> 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. 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?
>
> I don’t really see the use case.  One of the best parts of developing
> elisp in emacs is the level of interactive documentation:
> describe-function, find-function, interactive info manuals, etc.  It’s
> there when you need it, but not in the way when you don’t.  I almost
> never read elisp code in a non-emacs environment (except for short
> snippets in blog posts, I suppose).
>
> FWIW, my wishlist for literate programming in org/elisp is something
> like (in approximately increasing order of estimated difficulty):
>
> - allow find-function/variable to jump to the location in an org file
>   where something is defined, rather than the tangled elisp file.
>
> - allow org-mode text “near” a function definition to be used as the
>   function’s docstring (for describe-function et al.):
>
> ,----
> | docstring docstring docstring
> | #+begin_src elisp
> |   (defun foo ()
> |     ...)
> | #+end_src
> `----
>
> rather than:
>
> ,----
> | #+begin_src elisp
> |   (defun foo ()
> |     "docstring docstring docstring"
> |     ...)
> | #+end_src
> `----
>
> - allow more features of underlying source code editing modes to be used
>   in org buffers directly (no org-edit-special context switch needed).
>   For me, this would include:
>   - eval-defun (C-M-x)
>   - paredit
>   - eldoc
>   - auto-complete (company etc.)
>   For your use case, a mode which shows the docstring for a fn/var in a
>   tooltip on mouseover/keystroke could be added (I couldn’t find
>   anything like this already existing for emacs-lisp-mode, which is
>   kind of surprising to me – but I did not look very hard)
>
> - make it easier to develop parts of org using these LP features.
>
> Cheers,
>
> --
> Aaron Ecay

Re: Thoughts on weaving variable documentation

[Fabrice Niessen]

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/

Re: Thoughts on weaving variable documentation

[Grant Rettke]

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
gcr@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-news@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/
>
>