From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Stefan Monnier Newsgroups: gmane.emacs.devel Subject: Re: Modern conventions for structuring Emacs Lisp libraries Date: Sun, 06 Oct 2013 14:13:07 -0400 Message-ID: References: <87hacvn8sm.fsf@gmail.com> <87vc1ae1on.fsf@gmail.com> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: ger.gmane.org 1381083202 22598 80.91.229.3 (6 Oct 2013 18:13:22 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sun, 6 Oct 2013 18:13:22 +0000 (UTC) Cc: emacs-devel@gnu.org To: Thorsten Jolitz Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sun Oct 06 20:13:25 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 1VSspZ-0002HU-EH for ged-emacs-devel@m.gmane.org; Sun, 06 Oct 2013 20:13:25 +0200 Original-Received: from localhost ([::1]:56051 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VSspY-0005x7-QS for ged-emacs-devel@m.gmane.org; Sun, 06 Oct 2013 14:13:24 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:49479) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VSspP-0005ux-Qe for emacs-devel@gnu.org; Sun, 06 Oct 2013 14:13:23 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1VSspI-0005ou-HT for emacs-devel@gnu.org; Sun, 06 Oct 2013 14:13:15 -0400 Original-Received: from ironport2-out.teksavvy.com ([206.248.154.182]:56357) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VSspI-0005oq-Ci for emacs-devel@gnu.org; Sun, 06 Oct 2013 14:13:08 -0400 X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: Av8EABK/CFHO+K8t/2dsb2JhbABEvw4Xc4IeAQEEAVYPFAULCw4mEhQYDSQrAodxBsEtjSCDagOkeoFegxOBSiQ X-IPAS-Result: Av8EABK/CFHO+K8t/2dsb2JhbABEvw4Xc4IeAQEEAVYPFAULCw4mEhQYDSQrAodxBsEtjSCDagOkeoFegxOBSiQ X-IronPort-AV: E=Sophos;i="4.84,565,1355115600"; d="scan'208";a="34876926" Original-Received: from 206-248-175-45.dsl.teksavvy.com (HELO fmsmemgm.homelinux.net) ([206.248.175.45]) by ironport2-out.teksavvy.com with ESMTP/TLS/ADH-AES256-SHA; 06 Oct 2013 14:09:33 -0400 Original-Received: by fmsmemgm.homelinux.net (Postfix, from userid 20848) id CAD60AE4CB; Sun, 6 Oct 2013 14:13:07 -0400 (EDT) In-Reply-To: <87vc1ae1on.fsf@gmail.com> (Thorsten Jolitz's message of "Sun, 06 Oct 2013 19:42:16 +0200") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.3.50 (gnu/linux) X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 206.248.154.182 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:163921 Archived-At: > The first thing when looking at a library is getting an overview about > its structure - with tools like e.g. navi-mode. > For me its a huge difference then if I look at a well balanced and > logical hierachical tree-structure (org-element.el and ox.el are perfect > examples for this) or at something that seems inherently wrong and > illogical at first sight. Then fix navi-mode to show you the structure you want. It's not like the info is missing. > This seems the least important point, but again I ask myself: why > continue recommend the colons, when it turns out they don't look so > good in exports? Because I have much better things to do with my time than have to deal with such nasty decades-long transitions. >> Damn! 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. > If I understand you right, maybe there is good news. Install and load > outshine.el and outorg.el, move point on the "Commentary:" header and do > 'M-x outorg-edit-as-org' (or M-# M-#). > Then you will be offered that headline converted to Org in a temporary > Org-mode edit buffer (*outorg-edit-buffer*). In that buffer, you can use > the power of Org-mode for writing really complex commentary text, even > using Org-Babel for executing code and inserts results, and then export > the commentary section nicely formatted to HTML, LaTeX, ODT, ASCII and > other backends. Exporting to HTML will be useful, but I first and foremost want it to be displayed nicely in an Emacs buffer. The markup should be simple enough that existing Commentary sections mostly follow it already, and that you mostly don't need any extra support to write it. Stefan