* Re: Thoughts on weaving variable documentation
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-24 12:17 ` Fabrice Niessen
2 siblings, 0 replies; 6+ messages in thread
From: Grant Rettke @ 2014-06-20 16:11 UTC (permalink / raw)
To: emacs-orgmode@gnu.org
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
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Thoughts on weaving variable documentation
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
2 siblings, 1 reply; 6+ messages in thread
From: Aaron Ecay @ 2014-06-21 5:58 UTC (permalink / raw)
To: Grant Rettke, emacs-orgmode@gnu.org
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
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Thoughts on weaving variable documentation
2014-06-21 5:58 ` Aaron Ecay
@ 2014-06-21 23:20 ` Grant Rettke
0 siblings, 0 replies; 6+ messages in thread
From: Grant Rettke @ 2014-06-21 23:20 UTC (permalink / raw)
To: Grant Rettke, emacs-orgmode@gnu.org
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
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Thoughts on weaving variable documentation
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-24 12:17 ` Fabrice Niessen
2014-06-24 14:00 ` Grant Rettke
2 siblings, 1 reply; 6+ messages in thread
From: Fabrice Niessen @ 2014-06-24 12:17 UTC (permalink / raw)
To: emacs-orgmode-mXXj517/zsQ
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/
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Thoughts on weaving variable documentation
2014-06-24 12:17 ` Fabrice Niessen
@ 2014-06-24 14:00 ` Grant Rettke
0 siblings, 0 replies; 6+ messages in thread
From: Grant Rettke @ 2014-06-24 14:00 UTC (permalink / raw)
To: Fabrice Niessen; +Cc: emacs-orgmode@gnu.org
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/
>
>
^ permalink raw reply [flat|nested] 6+ messages in thread