From: Aaron Ecay <aaronecay@gmail.com>
To: Grant Rettke <gcr@wisdomandwonder.com>,
"emacs-orgmode@gnu.org" <emacs-orgmode@gnu.org>
Subject: Re: Thoughts on weaving variable documentation
Date: Sat, 21 Jun 2014 01:58:25 -0400 [thread overview]
Message-ID: <87k38a248u.fsf@gmail.com> (raw)
In-Reply-To: <CAAjq1mcOv-o48DT3pShkySpSDaL_6NgLFeTGwJyi81Ag0QaYSw@mail.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
next prev parent reply other threads:[~2014-06-21 5:58 UTC|newest]
Thread overview: 6+ messages / expand[flat|nested] mbox.gz Atom feed top
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 [this message]
2014-06-21 23:20 ` Grant Rettke
2014-06-24 12:17 ` Fabrice Niessen
2014-06-24 14:00 ` Grant Rettke
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87k38a248u.fsf@gmail.com \
--to=aaronecay@gmail.com \
--cc=emacs-orgmode@gnu.org \
--cc=gcr@wisdomandwonder.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).