From mboxrd@z Thu Jan 1 00:00:00 1970 From: Grant Rettke Subject: Thoughts on weaving variable documentation Date: Fri, 20 Jun 2014 11:10:39 -0500 Message-ID: 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]:48883) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Wy1Oj-0004B6-AD for emacs-orgmode@gnu.org; Fri, 20 Jun 2014 12:10:46 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Wy1Oh-0003K6-TE for emacs-orgmode@gnu.org; Fri, 20 Jun 2014 12:10:40 -0400 Received: from mail-ob0-x22d.google.com ([2607:f8b0:4003:c01::22d]:32935) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Wy1Oh-0003Jg-M5 for emacs-orgmode@gnu.org; Fri, 20 Jun 2014 12:10:39 -0400 Received: by mail-ob0-f173.google.com with SMTP id va2so1326318obc.32 for ; Fri, 20 Jun 2014 09:10:39 -0700 (PDT) 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: "emacs-orgmode@gnu.org" 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? Kind regards, 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