From mboxrd@z Thu Jan 1 00:00:00 1970 From: Aaron Ecay Subject: Re: Thoughts on weaving variable documentation Date: Sat, 21 Jun 2014 01:58:25 -0400 Message-ID: <87k38a248u.fsf@gmail.com> References: Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:32936) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WyEJx-0008Tq-2f for emacs-orgmode@gnu.org; Sat, 21 Jun 2014 01:58:46 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1WyEJn-0006PX-Ve for emacs-orgmode@gnu.org; Sat, 21 Jun 2014 01:58:36 -0400 Received: from mail-qg0-x22d.google.com ([2607:f8b0:400d:c04::22d]:55157) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WyEJn-0006Ob-RP for emacs-orgmode@gnu.org; Sat, 21 Jun 2014 01:58:27 -0400 Received: by mail-qg0-f45.google.com with SMTP id 63so4226170qgz.32 for ; Fri, 20 Jun 2014 22:58:27 -0700 (PDT) In-Reply-To: List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org To: Grant Rettke , "emacs-orgmode@gnu.org" Hi Grant, 2014ko ekainak 20an, Grant Rettke-ek idatzi zuen: >=20 > Good morning, >=20 > 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: >=20 > 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 >=20 > Makes total sense. >=20 > 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: >=20 > 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. >=20 > That is the idea, at least. >=20 > 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=E2=80=99t really see the use case. One of the best parts of developi= ng elisp in emacs is the level of interactive documentation: describe-function, find-function, interactive info manuals, etc. It=E2=80= =99s there when you need it, but not in the way when you don=E2=80=99t. 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. =20=20 - allow org-mode text =E2=80=9Cnear=E2=80=9D a function definition to be us= ed as the function=E2=80=99s 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=E2=80=99t find anything like this already existing for emacs-lisp-mode, which is kind of surprising to me =E2=80=93 but I did not look very hard) - make it easier to develop parts of org using these LP features. Cheers, --=20 Aaron Ecay