From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Thorsten Jolitz Newsgroups: gmane.emacs.devel Subject: Re: Modern conventions for structuring Emacs Lisp libraries Date: Sun, 06 Oct 2013 18:40:35 +0200 Message-ID: <874n8ufj3w.fsf@gmail.com> References: <87hacvn8sm.fsf@gmail.com> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: ger.gmane.org 1381077666 32099 80.91.229.3 (6 Oct 2013 16:41:06 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sun, 6 Oct 2013 16:41:06 +0000 (UTC) To: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sun Oct 06 18:41:10 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 1VSrOH-0004oM-0s for ged-emacs-devel@m.gmane.org; Sun, 06 Oct 2013 18:41:09 +0200 Original-Received: from localhost ([::1]:55821 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VSrOG-0005hS-L3 for ged-emacs-devel@m.gmane.org; Sun, 06 Oct 2013 12:41:08 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:33776) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VSrO7-0005ad-Fz for emacs-devel@gnu.org; Sun, 06 Oct 2013 12:41:04 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1VSrO2-0002dM-1Z for emacs-devel@gnu.org; Sun, 06 Oct 2013 12:40:59 -0400 Original-Received: from plane.gmane.org ([80.91.229.3]:38781) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VSrO1-0002d5-Oy for emacs-devel@gnu.org; Sun, 06 Oct 2013 12:40:53 -0400 Original-Received: from list by plane.gmane.org with local (Exim 4.69) (envelope-from ) id 1VSrNy-0004eL-Lz for emacs-devel@gnu.org; Sun, 06 Oct 2013 18:40:50 +0200 Original-Received: from g231227116.adsl.alicedsl.de ([92.231.227.116]) by main.gmane.org with esmtp (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Sun, 06 Oct 2013 18:40:50 +0200 Original-Received: from tjolitz by g231227116.adsl.alicedsl.de with local (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Sun, 06 Oct 2013 18:40:50 +0200 X-Injected-Via-Gmane: http://gmane.org/ Original-Lines: 98 Original-X-Complaints-To: usenet@ger.gmane.org X-Gmane-NNTP-Posting-Host: g231227116.adsl.alicedsl.de User-Agent: Gnus/5.130002 (Ma Gnus v0.2) Emacs/24.3 (gnu/linux) Cancel-Lock: sha1:Q6IzoFqjr4Cvc+3NVFXtLkGBTnQ= X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 80.91.229.3 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:163911 Archived-At: Richard Stallman writes: > [ To any NSA and FBI agents reading my email: please consider > [ whether defending the US Constitution against all enemies, > [ foreign or domestic, requires you to follow Snowden's example. > > Our conventions for headings in Lisp code are not sacred. We can > change them if that is a good thing to do. However, the transient of > such a change is likely to cause some work and trouble for a lot of > people. > > Your proposal for handling the conventional ;;; separator lines makes > sense, and I see nothing inherently wrong with it. But this seems to > assume our code should wag our conventions. It might be far less work > to change Outline mode and Org mode to understand our existing > conventions, than to change hundreds of Lisp files (including files we > don't maintain). I did already adapt my own library outshine.el to work with 'special case' ,------- | ^;;;+ `------- headlines sometimes ago, because I understand very well that nobody wants to change a huge code base only to please a new program tool (or a new idea about file structuring conventions). But its exactly the fact that I can use outshine.el/navi-mode.el with oldschool Emacs Lisp libraries now, i.e. look at them like Org files, that made me think there is room for improvement. What I'm looking for is probably official recommendations that naturally lead to sane file structuring and allow me (and others) to add their sanely structured libraries to the package repos. Assuming that [[http://www.emacswiki.org/emacs/ElispAreaConventions][this page]] reflects the official recommendations, they look like this: ,------------------------------------------------------------ | The major section headings are, in order: | | ;;; .el --- | ;;; Commentary: | ;;; Change Log: (optional) | ;;; Code: | ;;; .el ends here `------------------------------------------------------------ I would, as described in my proposal, critisize that 1. that last line is no headline 2. the 1st-level ";;; Code:" headline enforces one of two bad decisions: - accept that all following headlines must be level 2 or higher, since they are all subtrees of the libraries Code: section. - ignore the logic of the file structuring and continue with other 1st-level headlines that should really be subheadlines of "Code:" 3. the trailing colons are no good when exporting to html, latex etc... I would rather see recommendations like this: ,-------------------------------------------------------- | ;;; .el --- | ;;;; Commentary | ;;;; Change Log (optional) | ;;; Requieres (optional) | ;;; Variables (optional) | [...] (other 1st-level code-section headlines) | ;; .el ends here `-------------------------------------------------------- 1. assume an elisp library is naturally divided into two parts: the header-comment section and the code-section, but realize that it might be 30 lines of header-comments vs 2000 lines of code (or even much more) 2. therefore, drop the split into just two parts and define the header-comment as the first 1st-level headline in a file that can contain many more 1st-level headlines (that all belong to the implicitly defined code-section). 3. use the file's first line as top-headline of the header-comment section, and make all other headlines in this comment-section subheaders of this line (level 2 or higher) 4. thus, the second 1st-level headline of the file starts the code-section (without saying so explicitly) 5. make the last line a simple comment 6. drop the trailing colons That would lead IMO to better structured Elisp files, and since its so easy to convert from ";;; " to ";; * ", one could always use the favorite syntax and convert to the other. Wouldn't it be possible to leave the existing libraries untouched, update the conventions (for a better future), and somehow allow for both versions to co-exist? -- cheers, Thorsten