From mboxrd@z Thu Jan 1 00:00:00 1970 From: Grant Rettke Subject: Re: Thoughts on weaving variable documentation Date: Sat, 21 Jun 2014 18:20:45 -0500 Message-ID: References: <87k38a248u.fsf@gmail.com> 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]:56784) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WyUaV-0006T5-TA for emacs-orgmode@gnu.org; Sat, 21 Jun 2014 19:20:49 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1WyUaU-0006jj-HX for emacs-orgmode@gnu.org; Sat, 21 Jun 2014 19:20:47 -0400 Received: from mail-oa0-x22c.google.com ([2607:f8b0:4003:c02::22c]:46041) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WyUaU-0006jf-Di for emacs-orgmode@gnu.org; Sat, 21 Jun 2014 19:20:46 -0400 Received: by mail-oa0-f44.google.com with SMTP id i7so8980128oag.31 for ; Sat, 21 Jun 2014 16:20:45 -0700 (PDT) In-Reply-To: <87k38a248u.fsf@gmail.com> 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" 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 gcr@wisdomandwonder.com | http://www.wisdomandwonder.com/ =E2=80=9CWisdom begins in wonder.=E2=80=9D --Socrates ((=CE=BB (x) (x x)) (=CE=BB (x) (x x))) =E2=80=9CLife has become immeasurably better since I have been forced to st= op taking it seriously.=E2=80=9D --Thompson On Sat, Jun 21, 2014 at 12:58 AM, Aaron Ecay 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=E2=80=99t really see the use case. One of the best parts of develo= ping > 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 alm= ost > 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 =E2=80=9Cnear=E2=80=9D a function definition to be = used 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, > > -- > Aaron Ecay