From mboxrd@z Thu Jan 1 00:00:00 1970 From: Grant Rettke Subject: Re: Thoughts on weaving variable documentation Date: Fri, 20 Jun 2014 11:11:18 -0500 Message-ID: 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]:49197) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Wy1PM-0004n3-Lz for emacs-orgmode@gnu.org; Fri, 20 Jun 2014 12:11:21 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Wy1PL-0003VY-8T for emacs-orgmode@gnu.org; Fri, 20 Jun 2014 12:11:20 -0400 Received: from mail-oa0-x231.google.com ([2607:f8b0:4003:c02::231]:44356) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Wy1PL-0003V5-3u for emacs-orgmode@gnu.org; Fri, 20 Jun 2014 12:11:19 -0400 Received: by mail-oa0-f49.google.com with SMTP id i7so7465641oag.36 for ; Fri, 20 Jun 2014 09:11:18 -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: "emacs-orgmode@gnu.org" org-docco is something that comes to mind: http://orgmode.org/worg/org-contrib/index.html 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 Fri, Jun 20, 2014 at 11:10 AM, Grant Rettke wr= ote: > 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 = stop > taking it seriously.=E2=80=9D --Thompson