[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: |
Sat, 21 Jun 2014 18:20:45 -0500 |
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
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 Sat, Jun 21, 2014 at 12:58 AM, Aaron Ecay <address@hidden> 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