Re: Thoughts on weaving variable documentation

[Aaron Ecay <aaronecay@gmail.com>]

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