From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.devel Subject: RE: Modern conventions for structuring Emacs Lisp libraries Date: Sat, 5 Oct 2013 21:47:56 -0700 (PDT) Message-ID: <705f3517-b092-4418-b71a-fb7272cf0826@default> References: <87hacvn8sm.fsf@gmail.com> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Trace: ger.gmane.org 1381034895 32660 80.91.229.3 (6 Oct 2013 04:48:15 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sun, 6 Oct 2013 04:48:15 +0000 (UTC) Cc: Thorsten Jolitz , emacs-devel To: Xue Fuqiao , Stefan Monnier Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sun Oct 06 06:48:18 2013 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1VSgGQ-0006gM-0u for ged-emacs-devel@m.gmane.org; Sun, 06 Oct 2013 06:48:18 +0200 Original-Received: from localhost ([::1]:53822 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VSgGP-0002tu-NW for ged-emacs-devel@m.gmane.org; Sun, 06 Oct 2013 00:48:17 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:47855) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VSgGH-0002tk-43 for emacs-devel@gnu.org; Sun, 06 Oct 2013 00:48:15 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1VSgGA-00047y-Ja for emacs-devel@gnu.org; Sun, 06 Oct 2013 00:48:09 -0400 Original-Received: from userp1040.oracle.com ([156.151.31.81]:37406) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VSgGA-00047n-CR for emacs-devel@gnu.org; Sun, 06 Oct 2013 00:48:02 -0400 Original-Received: from ucsinet21.oracle.com (ucsinet21.oracle.com [156.151.31.93]) by userp1040.oracle.com (Sentrion-MTA-4.3.1/Sentrion-MTA-4.3.1) with ESMTP id r964lxc5023811 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Sun, 6 Oct 2013 04:48:00 GMT Original-Received: from userz7021.oracle.com (userz7021.oracle.com [156.151.31.85]) by ucsinet21.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id r964lxYh004034 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Sun, 6 Oct 2013 04:47:59 GMT Original-Received: from abhmt106.oracle.com (abhmt106.oracle.com [141.146.116.58]) by userz7021.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id r964lwlT004030; Sun, 6 Oct 2013 04:47:58 GMT In-Reply-To: X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.8 (707110) [OL 12.0.6680.5000 (x86)] X-Source-IP: ucsinet21.oracle.com [156.151.31.93] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.4.x-2.6.x [generic] X-Received-From: 156.151.31.81 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:163904 Archived-At: > > You skipped the part I was looking for: the "Commentary:" > > section. I do want this part to be refined. More specifically, I'd > > like someone to come up with a description of a markup format to use > > there (99% compatible with what we already have), together with code > > that can turn such a Commentary section into nicely rendered text in an > > Emacs buffer. >=20 > Agreed. It can also be rendered as HTML in the packages description on > elpa.gnu.org (and other package archives, maybe), along with the README. FWIW, I use something simple: `finder-commentary' plus `linkd-mode' (from `linkd.el'). Finder renders the Commentary in a simple way (strips comment chars, hyperlinks file names, etc.). Linkd provides hyperlinked text. I also usually provide a linkd-linked index to the Commentary sections (if large) and other file sections. Linkd is here: http://www.emacswiki.org/emacs/download/linkd.el.