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 g...@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 <aarone...@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
