Modern conventions for structuring Emacs Lisp libraries

Modern conventions for structuring Emacs Lisp libraries

[Thorsten Jolitz]

Hi List,

as a second take on this topic, I would like to make the attached
proposal for improving the conventions for structuring Emacs Lisp
source-code files:



               _________________________________________

                MODERN CONVENTIONS FOR EMACS LISP FILES

                            Thorsten Jolitz
               _________________________________________


                            <2013-10-05 Sa>


Table of Contents
_________________

1 Motivation
2 Critics of oldschool conventions
.. 2.1 General Considerations
.. 2.2 Real-world examples
..... 2.2.1 Last Line Pathology
..... 2.2.2 Wasted First Level Weakness
..... 2.2.3 Trailing Colon Weakness
..... 2.2.4 Comment Character as Headline-Level-Signals Weakness (Pathology?)
..... 2.2.5 Free Text Meta-Data Weakness
3 Summary





1 Motivation
============

  The motivation for this proposal is twofold:

  Org-mode everywhere: I use Org-mode all day long for all kinds of tasks
                       and really appreciate the Org way of structuring
                       files (with easy navigation and visibility
                       cycling). I want that for my (Emacs Lisp) source
                       code files too (maybe I'm not the only one).
  Current Pathologies: of old-school conventions. Looking at Emacs sources
                       and other Elisp libraries from the Org-mode
                       point-of-view, a few pathologies of the oldschool
                       conventions for Emacs Lisp are quite obvious, as
                       well as some misunderstandings that result from the
                       weaknesses of those oldschool conventions

  The idea is to
  1. fix the pathologies of the oldschool conventions
  2. improve some conventions that give bad results in practise
  3. write a library (e.g. modern-conventions.el) that transforms modern
     (org-mode style) elisp files into files in the (fixed) oldschool
     style, so that both styles can be considered equivalent (and are
     accepted for MELPA and other package repos)


2 Critics of oldschool conventions
==================================

2.1 General Considerations
~~~~~~~~~~~~~~~~~~~~~~~~~~

  I would guess that many people either don't really structure their
  elisp files, or they use page breaks in combination with
  outline-minor-mode (folding the function/variable definitions rather
  than folding explicitly defined headlines).

  However, there is this convention that

  ,----
  | ^;;; Text
  `----

  starts a first level headline, and every additional ';' defines one
  higher level (with e.g."^;;;;; Text" defining a third-level headline),
  and its application is somehow enforced by the loose conventions for
  writing the header part of an Elisp library.

  Therefore, when outline-minor-mode with [outshine.el] extensions is
  activated in the Emacs Lisp buffer, it can be viewed and treated (wrt
  navigation and visibility cycling) just like an Org-mode buffer that
  is structured with hierarchical headlines.

  I do this all the time, since I tend to use [navi-mode.el] (based on
  outshine) for buffer navigation. So the pathologies and weaknesses of
  the oldschool conventions stare me in the face every day.


  [outshine.el] https://github.com/tj64/outshine

  [navi-mode.el] https://github.com/tj64/navi


2.2 Real-world examples
~~~~~~~~~~~~~~~~~~~~~~~

  [DISCLAIMER: I have no intention to blame the authors of the cited
  libraries for using "bad style" or so, I just need some real-world
  examples for my critics so I simply use arbitrary Emacs source files]


2.2.1 Last Line Pathology
-------------------------

  Elisp files should (and do) end with a line like this:

  ,----
  | ;;; dired.el ends here
  `----

  Considering that "^;;; Text" defines a first level headline, this is a
  clear pathology: this line is *not* a headline, it is just a comment
  signalling 'end-of-file'.


2.2.2 Wasted First Level Weakness
---------------------------------

  It is customary to start the code section of a library, which begins
  after the header comment section, with this first level headline:

  ,----
  | ;;; Code:
  `----

  This leads to very unbalanced weights of the first level headlines,
  i.e. to bad file structuring.

  ,----
  | 7 matches for "^;;; " in buffer: help.el.gz
  |       1:;;; help.el --- help commands for Emacs
  |      25:;;; Commentary:
  |      30:;;; Code:
  |     280:;;; `User' help functions
  |     967:;;; Automatic resizing of temporary buffers.
  |    1041:;;; Help windows.
  |    1193:;;; help.el ends here
  `----

  The above example, produced by typing '1' in the associated
  *Navi-buffer* of help.el (-> show headlines up-to first-level), shows
  this weakness quite clearly:

  1. in a file with some 1200 lines of code, there are 7 1st-level
     headlines
  2. at most 3 (if not only 2) of 7 headlines should really be 1st-level
     headlines:

  ,----
  | ;;; help.el
  | [;;; Commentary:]
  | ;;; Code:
  `----

  1. Correct structuring would result in a file with two 1st-level
     headlines, the first one containing some 30 lines, the second one
     containing some 1170 lines of code.

  Starting the code section with a ";;; Code:" headline completely
  wastes the first level for further file structuring. Therefore my
  proposal:

  Let the first line in the file be a 1st-level-headline:

  ,----
  | ;;; help.el --- help commands for Emacs
  `----

  all other headlines in the header-comment section are subheadlines of
  this one, i.e. level 2 or higher. The next 1st-level-headline then
  implicitly starts the code-section, but *must not* be named ";;;
  Code:" because it is clear form the context that the code sections
  starts here:

  ,----
  | 8 matches for "^;;; " in buffer: navi-mode.el
  |       1:;;; navi-mode.el --- major-mode for easy buffer-navigation
  |     246:;;; Requires
  |     251:;;; Mode Definitions
  |     282:;;; Variables
  |     862:;;; Defuns
  |    1672:;;; Menus and Keys
  |    1963:;;; Run Hooks and Provide
  |    1970:;;; navi-mode.el ends here
  `----

  [NOTE: I was forced to reconvert the navi-mode.el file to oldschool
  headlines and to include the pathological last line to be able to add
  it to MELPA -> there should only be 7 headlines in this listing
  really!]

  It does not matter if you structure your file by code criteria
  (Variables, Defuns, Keys ...) or by content criteria, or a mix of
  both, like in this example:

  ,----
  | 41 matches for "^;;; " in buffer: org.el
  |       1:;;; org.el --- Outline-based notes management and organizer
  |      26:;;; Commentary:
  |      63:;;; Code:
  |     278:;;; Version
  |     316:;;; Compatibility constants
  |     318:;;; The custom variables
  |    4121:;;; Miscellaneous options
  |    4152:;;; Functions and variables from their packages
  |    4210:;;; Autoload and prepare some org modules
  |    4578:;;; Variables for pre-computed regular expressions,  all buffer local
  |    5216:;;; Some variables used in various places
  |    6486:;;; Cycling
  |    7087:;;; Saving and restoring visibility
  |    7123:;;; Folding of blocks
  |    7213:;;; Org-goto
  |    7416:;;; Indirect buffer display of subtrees
  |    7507:;;; Inserting headlines
  |    7825:;;; Promotion and Demotion ...
  `----

  the important thing is to have a balanced structure with a sufficient
  number of real 1st-level-headlines whose headline-text carries real
  information about the content. You can see above that org.el sticks to
  the

  ,----
  | ;;; Code:
  `----

  convention, but then ignores it immediately - otherwise, all
  subsequent headlines should be 2nd-level really.


2.2.3 Trailing Colon Weakness
-----------------------------

  ,----
  | ;;; help.el
  | [;;; Commentary:]
  | ;;; Code:
  `----

  In oldschool Elisp files, headlines often end in colons. In Org-mode,
  this is not usual, and the Org-mode conventions are better in this
  case. Taking into account that with [outorg.el] (based on outshine)
  every Elisp file can be converted to an Org-mode file with a
  keystroke, and subsequently be exported from Org-mode to HTML, LaTeX,
  and many other backends, it becomes clear why this is a bad
  convention: the colon is not needed to signal a headline, and almost
  always looks bad in the exported output formats.


  [outorg.el] https://github.com/tj64/outorg


2.2.4 Comment Character as Headline-Level-Signals Weakness (Pathology?)
-----------------------------------------------------------------------

  Its a bad idea to use the Elisp comment char ';' to signal that:

  - this is a headline
  - this headline has level X

  The otherwise fantastic library dired.el illustrates why:

  ,----
  | 40 matches for "^;;;;?;?;?;?;?;?;? " in buffer: dired.el.gz
  |       1:;;; dired.el --- directory-browsing commands -*- lexical-binding: t -*-
  |      26:;;; Commentary:
  |      35:;;; Code:
  |      37:;;; Customizable variables
  |     193:;;; Hook variables
  |     433:;;;   ;;
  |     434:;;;   ;; Files that are group or world writable.
  |     435:;;;   (list (concat dired-re-maybe-mark dired-re-inode-size
  |     493:;;; Macros must be defined before they are used,  for the byte compiler.
  |    1282:;;;  Might as well not override the user if the user changed this.
  |    1283:;;;  (setq buffer-read-only t)
  |    2101:;;; Functions for extracting and manipulating file names in Dired buffers.
  |    2233:;;; Functions for finding the file name in a dired buffer line.
  |    2328:;;; COPY NAMES OF MARKED FILES INTO KILL-RING.
  |    2449:;;; utility functions
  |    3199:;;; Commands to mark or flag files based on their characteristics or names.
  |    3477:;;; Sorting
  |    3631:;;;;  Drag and drop support
  |    3734:;;;;  Desktop support
  |    3779:;;; Start of automatically extracted autoloads.
  |    3782:;;;;;;  dired-do-search dired-do-isearch-regexp dired-do-isearch
  |    3783:;;;;;;  dired-isearch-filenames-regexp dired-isearch-filenames dired-isearch-filenames-setup
  |    3784:;;;;;;  dired-hide-all dired-hide-subdir dired-tree-down dired-tree-up
  |    3785:;;;;;;  dired-kill-subdir dired-mark-subdir-files dired-goto-subdir
  |    3786:;;;;;;  dired-prev-subdir dired-insert-subdir dired-maybe-insert-subdir
  |    3787:;;;;;;  dired-downcase dired-upcase dired-do-symlink-regexp dired-do-hardlink-regexp
  |    3788:;;;;;;  dired-do-copy-regexp dired-do-rename-regexp dired-do-rename
  |    3789:;;;;;;  dired-do-hardlink dired-do-symlink dired-do-copy dired-create-directory
  |    3790:;;;;;;  dired-rename-file dired-copy-file dired-relist-file dired-remove-file
  |    3791:;;;;;;  dired-add-file dired-do-redisplay dired-do-load dired-do-byte-compile
  |    3792:;;;;;;  dired-do-compress dired-query dired-compress-file dired-do-kill-lines
  |    3793:;;;;;;  dired-run-shell-command dired-do-shell-command dired-do-async-shell-command
  |    3794:;;;;;;  dired-clean-directory dired-do-print dired-do-touch dired-do-chown
  |    3795:;;;;;;  dired-do-chgrp dired-do-chmod dired-compare-directories dired-backup-diff
  |    3796:;;;;;;  dired-diff) "dired-aux" "dired-aux.el" "066bb17769887a7fbc0490003f59e4b3")
  |    3797:;;; Generated autoloads from dired-aux.el
  |    4299:;;;;;;  "dired-x" "dired-x.el" "ce753ade80ea9f4e64ab3569e3a5421e")
  |    4300:;;; Generated autoloads from dired-x.el
  |    4336:;;; End of automatically extracted autoloads.
  |    4342:;;; dired.el ends here
  `----

  Typing '8' in the associated *Navi-buffer* (show headlines up to level
  8) shows a wild mix of real headlines and comments. This is because it
  is only natural for people to get creative with comment characters
  [1], because they feel free to use them as it pleases them - its just
  about comments in the end.

  But with those oldschool conventions, comments and headline syntax
  clash, and people might forget about it or not be aware about it.

  Therefore I propose Org-style (= Outshine) headlines as modern
  alternative:

  ,----
  | Outshine headlines are outcommented Org-mode headlines
  `----

  for example:

  ,----
  | 18 matches for "^;; \*\*? " in buffer: iorg-scrape.el
  |       1:;; * iorg-scrape.el --- elisp glue code for `picoLisp/lib/scrape.l'
  |       2:;; ** MetaData
  |      17:;; ** Commentary
  |      22:;; ** ChangeLog
  |      24:;; * Requires
  |      31:;; * Mode and Exporter definitions
  |      33:;; ** Mode definitions
  |      84:;; * Variables
  |      85:;; ** Hooks
  |      86:;; ** Vars
  |     111:;; ** Customs
  |     114:;; * Functions
  |     115:;; ** Non-interactive Functions
  |     201:;; ** Commands
  |     855:;; * Menus and Keys
  |     856:;; ** Menus
  |     857:;; ** Keys
  |     946:;; * Run hooks and provide
  `----

  They are more readable (its much easier to spot the headline level),
  the comment-chars do only their core job - outcomment text in code
  buffers -, all the headline related info is contained in the '*'
  chars, and Org-mode users feel right at home in their source-code
  buffers.

  A big plus: this is /major-mode agnostic/. All 3 libraries (outshine,
  outorg and navi-mode) adapt to the specific comment-syntax defined for
  a major-mode, thus the 'outshine-way' of structuring source-code files
  is not restricted to Emacs Lisp files. As an example, here is a
  PicoLisp file (comment-start character # instead of ;):

  ,----
  | 14 matches for "^## \*\*? " in buffer: geometry.l
  |       1:## * geometry.l --- OpenGis Simple Features
  |      15:## ** Commentary
  |      20:## * Spatial Reference System
  |      30:## * Geometry (abstract root class)
  |     113:## * Point
  |     133:## * Curve
  |     184:## ** LineString
  |     230:## * Surface
  |     264:## ** Polygon
  |     310:## * GeometryCollection
  |     336:## ** MultiPoint
  |     356:## ** MultiCurve
  |     402:## ** MultiSurface
  |     472:## * File Local Variables
  `----

  Conversion between oldschool and outshine headlines would be
  exceedingly easy - as long as the oldschool files don't mix comments
  and headlines, i.e don't have "invalid" syntax (in a loose sense).


2.2.5 Free Text Meta-Data Weakness
----------------------------------

  Elisp source files start with a comment-header that gives some
  half-standardized meta-info about the file as well as usage
  instructions for the library. While the usage instructions a very
  library specific and might even be missing, the meta-data is
  obligatory and should as harmonized as possible. Package repos use
  special Elisp parser libraries to read-out the meta-data from these
  sections.

  This is quite ok, but still much weaker than it could be. The problem
  is that the free text format of the meta-data sections makes it just
  too easy to introduce variations and desviations that are completely
  accidental of just a matter of taste and don't add anything to the
  contained information, but rather make it much more difficult to
  extract and set this information programmatically.

  Lets use help.el as an example for a free-text meta-data section
  (please note how old this file is, and that since these old days many
  styles for writing these sections have evolved):

  ,----
  | ;;; help.el --- help commands for Emacs
  |
  | ;; Copyright (C) 1985-1986,  1993-1994,  1998-2013 Free Software
  | ;; Foundation,  Inc.
  |
  | ;; Maintainer: FSF
  | ;; Keywords: help,  internal
  | ;; Package: emacs
  |
  | ;; This file is part of GNU Emacs.
  |
  | ;; GNU Emacs is free software: you can redistribute it and/or modify
  | ;; it under the terms of the GNU General Public License as published by
  | ;; the Free Software Foundation,  either version 3 of the License,  or
  | ;; (at your option) any later version.
  |
  | ;; GNU Emacs is distributed in the hope that it will be useful,
  | ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  | ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  | ;; GNU General Public License for more details.
  |
  | ;; You should have received a copy of the GNU General Public License
  | ;; along with GNU Emacs.  If not,  see <http://www.gnu.org/licenses/>.
  `----

  As mentioned before, with 'outorg.el' every well structured Elisp file
  is an Org-mode file too, because 'M-x outorg-edit-as-org' (org M-#
  M-#) presents the file converted from Elisp to Org in a temporary
  Org-mode edit buffer (while 'M-x outorg-copy-edits-and-exit' or M-# in
  the edit buffer converts the edited Org text back to Elisp and copies
  it to the original source-code buffer).

  Thus, Org-mode's well developed functionality for storing, reading and
  writing meta-data is easily available for the Elisp programmer too:
  *property-drawers* and their *Property API*.

  Therefore I propose to introduce a 2nd-level headline

  ,----
  | ;; ** MetaData
  `----

  directly below the first 1st-level-headline of the source file (i.e.
  its first line) and store the file's meta-data in a property-drawer
  attached to this headline:

  ,----
  | ;; * iorg-scrape.el --- elisp glue code for `picoLisp/lib/scrape.l'
  | ;; ** MetaData
  | ;;   :PROPERTIES:
  | ;;   :copyright: Thorsten_Jolitz
  | ;;   :copyright-since: 2013
  | ;;   :version:  0.9
  | ;;   :licence:  GPL3+
  | ;;   :licence-url: http://www.gnu.org/licenses/
  | ;;   :part-of-emacs: no
  | ;;   :git-repo: https://github.com/tj64/iorg
  | ;;   :git-clone: git@github.com:tj64/iorg.git
  | ;;   :authors: Thorsten_Jolitz
  | ;;   :contact: <tjolitz@gmail.com>
  | ;;   :keywords: emacs org-mode picolisp iorg scrape
  | ;;   :END:
  |
  | ;; ** Commentary ...
  `----


  The advantages would be:

  1. With point on the "** MetaData" headline, a single 'M-# M-#' would
     offer this headline for editing in Org-mode in the
     *outorg-edit-buffer*, and Org-mode's functionality for [editing
     properties] (maybe even in [column view]) would be available to the
     Elisp programmer.

     Since it is easy to define /allowed values/ for Org-mode
     properties, for some properties (like license, licence-url,
     part-of-emacs, keywords) a fixed set of possible values could be
     given, helping to reduce accidental variation even further.

  2. Since a [Property API] for Org-mode's properties exists, reading
     and writing them from an Emacs Lisp program becomes almost trivial.

  3. Recently, ways to export these property drawers were added to the
     new Org-mode exporter, thus the meta-info can easily be exported to
     text-formatting backends like HTML or LaTeX for sharing with
     (presenting to) others. In the *outorg-edit-buffer* full Org-mode
     functionality is available, including Org-mode's export facilities.

  With establishing a few rules for this MetaData section (about how to
  format author names and emails e.g., expecially in the case of
  multiple authors), the relevant parts of the comment-header of Elisp
  files could really be converted into meta-DATA, human and
  machine-readable at the same time [2].


  [editing properties]
  http://orgmode.org/manual/Properties-and-Columns.html

  [column view] http://orgmode.org/manual/Column-view.html#Column-view

  [Property API]
  http://orgmode.org/manual/Using-the-property-API.html#Using-the-property-API


3 Summary
=========

  Being an Org-mode user and looking at Elisp libraries from the
  Org-mode users perspective every day (via /outshine/ and /navi-mode/),
  I recognized quite of few weaknesses of the oldschool conventions for
  structuring Emacs Lisp files. Therefore I propose to partially fix
  these weaknesses for the oldschool libraries and, at the same time,
  introduce alternative modern conventions (the /outshine/ way) for
  structuring Elisp libraries. Once the fixes and modern conventions
  have been agreed upon, an Elisp library (modern-convention.el) could
  be written that converts one style into the other, making them
  equivalent and thus both acceptable for official and unofficial
  package repos.



Footnotes
_________

[1] especially the very personal .emacs files show a great level of
sometimes almost artistic creativity with comment chars.

[2] in Org-mode there is the :ARCHIVE: tag that, among other things,
keeps headlines folded during global visibility cycling. It is planned
to implement this for outshine.el too, such that comment- and
meta-data sections can be tagged and stay completely out of the way of
the programmer's view on the source-buffer, except they are explicitly
unfolded.


--
cheers,
Thorsten

Re: Modern conventions for structuring Emacs Lisp libraries

[Richard Stallman]

        [ 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).


-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: Modern conventions for structuring Emacs Lisp libraries

[Richard Stallman]

        [ 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.

Regarding the file keywords, the change you've proposed has some fatal
flaws.

  | ;; ** MetaData
  | ;;   :PROPERTIES:
  | ;;   :copyright: Thorsten_Jolitz
  | ;;   :copyright-since: 2013
  | ;;   :version:  0.9
  | ;;   :licence:  GPL3+
  | ;;   :licence-url: http://www.gnu.org/licenses/

It is legally inadequate, since it doesn't have a standard copyright
notice.  A standard copyright notice looks like

    Copyright YEARS NAME

It is inadequate for informing users about their rights, and the lack
of warranty, and about our philosophy, because it lacks the explicit
license notice which states those things.  It may also be legally
insufficient for making the license clear.

We want people to see these words in the source file:

      | ;; This file is part of GNU Emacs.
      |
      | ;; GNU Emacs is free software: you can redistribute it and/or modify
      | ;; it under the terms of the GNU General Public License as published by
      | ;; the Free Software Foundation,  either version 3 of the License,  or
      | ;; (at your option) any later version.
      |
      | ;; GNU Emacs is distributed in the hope that it will be useful,
      | ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
      | ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
      | ;; GNU General Public License for more details.
      |
      | ;; You should have received a copy of the GNU General Public License
      | ;; along with GNU Emacs.  If not,  see <http://www.gnu.org/licenses/>.

This part has to be kept as it is.

Those issues don't apply to the library header lines:

  | ;; Maintainer: FSF
  | ;; Keywords: help,  internal
  | ;; Package: emacs

We could change them if it is an improvement.  However, I think your
format is worse for humans.  We should not make it worse for humans
just to cater to programs that some people use.  You can change the
programs instead.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: Modern conventions for structuring Emacs Lisp libraries

[Daniel Colascione]

[-- Attachment #1: Type: text/plain, Size: 619 bytes --]

On 10/5/13 9:52 AM, Richard Stallman wrote:
>       | ;; GNU Emacs is distributed in the hope that it will be useful,
>       | ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
>       | ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
>       | ;; GNU General Public License for more details.

Is this shouty bit really necessary? Has there been a case in recorded
history of a distributor or developer of a program being held liable
because he omitted similar language? The SQLite people haven't been
sued, after all, and they release their software in the public domain.


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Modern conventions for structuring Emacs Lisp libraries

[Stefan Monnier]

> as a second take on this topic, I would like to make the attached
> proposal for improving the conventions for structuring Emacs Lisp
> source-code files:

Thanks.  I think it'd be good to improve the current situation, but
I don't think anything more than refinement is an option.  IOW changing
the convention is not really an option for various reasons, such as the
fact that several tools rely on it, and there are so many files using
it, many of which we can't fix, that we'd be stuck with two different
conventions for the next many years.

> 2.2.1 Last Line Pathology
> -------------------------

This is a very minor issue, I think.  It's trivil to fix it by simply
ignoring any "trailing header".

> 2.2.2 Wasted First Level Weakness
> ---------------------------------
>   | 7 matches for "^;;; " in buffer: help.el.gz
>   |       1:;;; help.el --- help commands for Emacs
>   |      25:;;; Commentary:
>   |      30:;;; Code:
>   |     280:;;; `User' help functions
>   |     967:;;; Automatic resizing of temporary buffers.
>   |    1041:;;; Help windows.
>   |    1193:;;; help.el ends here
>   `----
>   The above example, produced by typing '1' in the associated
>   *Navi-buffer* of help.el (-> show headlines up-to first-level), shows
>   this weakness quite clearly:
>   1. in a file with some 1200 lines of code, there are 7 1st-level
>      headlines
>   2. at most 3 (if not only 2) of 7 headlines should really be 1st-level
>      headlines:

Again, this seems like a rather minor issue.  Furthermore, ";;; Code:"
is a well-known header, so if needed, we can special case it in code
such as navi.

>   all other headlines in the header-comment section are subheadlines of
>   this one, i.e. level 2 or higher.

You can get that without any modification to existing files by
considering that any header that comes before ";;; Code:" is really one
deeper than what its semi-colons say.

>   In oldschool Elisp files, headlines often end in colons. In Org-mode,
>   this is not usual, and the Org-mode conventions are better in this
>   case.

Again, trivial to "fix" in any tool like navi: just change a trailing
colon into a full stop.

>   The otherwise fantastic library dired.el illustrates why:

All those non-headers are bugs.

>   8) shows a wild mix of real headlines and comments. This is because it
>   is only natural for people to get creative with comment characters

Maybe it was a bad idea to choose this convention, but it's easier to
fix the few cases where people's use of comments ends up accidentally
colliding with your convention.

>   |       1:;; * iorg-scrape.el --- elisp glue code for `picoLisp/lib/scrape.l'

Note that ";; *" is already in common use for other purposes (basically
the * is used as a bullet point there), so your convention would also
bump into other problems.

>   A big plus: this is /major-mode agnostic/. All 3 libraries (outshine,

I'm pretty sure there are many other languages that define their own
notion of comment structure, and I'd be surprise if any of them happens
to choose your convention.  IOW your convention is "major-mode agnostic"
at the cost of not following the "normal" conventions.  Just as is the
case with allout.el.

This is a trade-off with its benefit and its downsides.

The other option is to make your tools's structuring convention
sufficiently customizable that it can make adapt to the
"normal" convention (this is the path taken by outline.el).  It's not
perfect either, of course, but I think that given the obstacles it's
either to adapt the tools than to change the conventions.

>   Conversion between oldschool and outshine headlines would be
>   exceedingly easy - as long as the oldschool files don't mix comments
>   and headlines, i.e don't have "invalid" syntax (in a loose sense).

Exactly: if they're correct, then the conversion is easy.  So easy that
you can do it on the fly, without touching the file! ;-)

>   | ;; * iorg-scrape.el --- elisp glue code for `picoLisp/lib/scrape.l'
>   | ;; ** MetaData
>   | ;;   :PROPERTIES:
>   | ;;   :copyright: Thorsten_Jolitz
>   | ;;   :copyright-since: 2013

IIUC the syntax of the "copyright" line is legally significant
(e.g. whether years can be abbreviated, whether year ranges can be used,
etc...), and I don't think I want to get into discussions about what
other syntax we can use.  So I'm not interested in changing the
copyright line.

>   | ;;   :version:  0.9

The ";; Version:" format is used in ELPA, so changing it would require
changes in too many places.  Not gonna happen.

>   | ;;   :licence:  GPL3+
>   | ;;   :licence-url: http://www.gnu.org/licenses/

Here again, the many-lines blurb about the license has legal
significance (otherwise we'd have switched to ";; License: GPLv3+" by
now).

>   2. Since a [Property API] for Org-mode's properties exists, reading
>      and writing them from an Emacs Lisp program becomes almost trivial.

Reading them is already trivial (via the lisp-mnt.el library).
Writing is usually very easy already; the only exception could the
"Keywords:" header which is just a big problem in itself anyway (we
don't really know which categories should be available).

> 3 Summary
> =========

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.


        Stefan

Re: Modern conventions for structuring Emacs Lisp libraries

[Xue Fuqiao]

On Sun, Oct 6, 2013 at 8:42 AM, Stefan Monnier <monnier@iro.umontreal.ca> wrote:
> 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.

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.

-- 
Best regards, Xue Fuqiao.
http://www.gnu.org/software/emacs/

RE: Modern conventions for structuring Emacs Lisp libraries

[Drew Adams]

> > 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.
> 
> 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.

legalese haters club

[Stephen J. Turnbull]

Executive summary:

But why do you care?  The solution (for Emacs users -- does anybody
develop Emacs with vi?) has been available since the Cretaceous Period
(more exactly, January 19, 1991) as "hide-copyleft.el".

Please leave the boilerplate alone, or you'll break the software!

P.S. I don't use it myself.

Daniel Colascione writes:
 > On 10/5/13 9:52 AM, Richard Stallman wrote:

 > >       | ;; GNU Emacs is distributed in the hope that it will be useful,
 > >       | ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
 > >       | ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 > >       | ;; GNU General Public License for more details.
 > 
 > Is this shouty bit really necessary?

Depends on which lawyer you ask.  Evidently the FSF's think it's a
good idea.  It's actually not shouty; the usage of all caps here
precedes the Internet.  I wouldn't be surprised if it precedes the
telegraph.

 > Has there been a case in recorded history of a distributor or
 > developer of a program being held liable because he omitted similar
 > language? The SQLite people haven't been sued, after all, and they
 > release their software in the public domain.

Public domain materials don't have an owner, so there's nobody to
provide a warrantee.  You'd have to prove criminal negligence or
malicious intent to have a chance of recovering anything in that case.
You'd also have to prove a particular person was responsible for a
particular fault, and then find their money.[1]

None of the above applies to FSF-owned software.  Let the lawyers be
lawyers, so we don't have to.


Footnotes: 
[1]  Well, actually the typical ambulance-chasing-type lawyer would
check the checking account balance, and only then go looking for proof.

Re: Modern conventions for structuring Emacs Lisp libraries

[Thorsten Jolitz]

Richard Stallman <rms@gnu.org> 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:
| 
|     ;;; <name>.el --- <one-line description of the library>
|     ;;; Commentary:
|     ;;; Change Log: (optional)
|     ;;; Code:
|     ;;; <name>.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:

,--------------------------------------------------------
| ;;; <name>.el --- <one-line description of the library>
| ;;;; Commentary
| ;;;; Change Log (optional)
| ;;; Requieres (optional)
| ;;; Variables (optional)
| [...] (other 1st-level code-section headlines)
| ;; <name>.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

Re: Modern conventions for structuring Emacs Lisp libraries

[Thorsten Jolitz]

Richard Stallman <rms@gnu.org> 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.
>
> Regarding the file keywords, the change you've proposed has some fatal
> flaws.
>
>   | ;; ** MetaData
>   | ;;   :PROPERTIES:
>   | ;;   :copyright: Thorsten_Jolitz
>   | ;;   :copyright-since: 2013
>   | ;;   :version:  0.9
>   | ;;   :licence:  GPL3+
>   | ;;   :licence-url: http://www.gnu.org/licenses/
>
> It is legally inadequate, since it doesn't have a standard copyright
> notice.  A standard copyright notice looks like
>
>     Copyright YEARS NAME
>
> It is inadequate for informing users about their rights, and the lack
> of warranty, and about our philosophy, because it lacks the explicit
> license notice which states those things.  It may also be legally
> insufficient for making the license clear.
>
> We want people to see these words in the source file:
>
>       | ;; This file is part of GNU Emacs.
>       |
>       | ;; GNU Emacs is free software: you can redistribute it and/or modify
>       | ;; it under the terms of the GNU General Public License as published by
>       | ;; the Free Software Foundation,  either version 3 of the License,  or
>       | ;; (at your option) any later version.
>       |
>       | ;; GNU Emacs is distributed in the hope that it will be useful,
>       | ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
>       | ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
>       | ;; GNU General Public License for more details.
>       |
>       | ;; You should have received a copy of the GNU General Public License
>       | ;; along with GNU Emacs.  If not,  see <http://www.gnu.org/licenses/>.
>
> This part has to be kept as it is.
>
> Those issues don't apply to the library header lines:
>
>   | ;; Maintainer: FSF
>   | ;; Keywords: help,  internal
>   | ;; Package: emacs
>
> We could change them if it is an improvement.  However, I think your
> format is worse for humans.  We should not make it worse for humans
> just to cater to programs that some people use.  You can change the
> programs instead.

Indeed, until now I did not get much positive feedback about the looks
of these property drawers in Elisp libraries, not even from Org-mode
users - although they seem to be more suited for meta-data than just
free text from a conceptual point of view.

What would be really helpful, besides saner official recommendations for
file structuring, would be an up-to-date official template for this
meta-data section (maybe there is one out there but I missed it?).

(Private) tools could then convert this template into (e.g.) easy to
handle Org-mode syntax like above, and convert them back to more human
readable traditional syntax before a library is added to some repo.

-- 
cheers,
Thorsten

Re: Modern conventions for structuring Emacs Lisp libraries

[Thorsten Jolitz]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> as a second take on this topic, I would like to make the attached
>> proposal for improving the conventions for structuring Emacs Lisp
>> source-code files:
>
> Thanks.  I think it'd be good to improve the current situation, but
> I don't think anything more than refinement is an option.  IOW changing
> the convention is not really an option for various reasons, such as the
> fact that several tools rely on it, and there are so many files using
> it, many of which we can't fix, that we'd be stuck with two different
> conventions for the next many years.

I followed your advice after the 'first take' on this topic and adapted
my tools (outshine.el, outorg.el and navi-mode.el) to the conventions.

I still wonder if saner more modern conventions cannot co-exist with the
older ones without the necessity to touch the existing libraries, just
by modifying the existing tools a bit.

>> 2.2.1 Last Line Pathology
>> -------------------------
>
> This is a very minor issue, I think.  It's trivil to fix it by simply
> ignoring any "trailing header".

Can't the existing tools be modified to accept both, a trailing header
or a trailing comment? It might seem like a very minor issue, but its a
symptom for a not so minor issue - incorrect headline tree-structure.

>> 2.2.2 Wasted First Level Weakness
>> ---------------------------------
>>   | 7 matches for "^;;; " in buffer: help.el.gz
>>   |       1:;;; help.el --- help commands for Emacs
>>   |      25:;;; Commentary:
>>   |      30:;;; Code:
>>   |     280:;;; `User' help functions
>>   |     967:;;; Automatic resizing of temporary buffers.
>>   |    1041:;;; Help windows.
>>   |    1193:;;; help.el ends here
>>   `----
>>   The above example, produced by typing '1' in the associated
>>   *Navi-buffer* of help.el (-> show headlines up-to first-level), shows
>>   this weakness quite clearly:
>>   1. in a file with some 1200 lines of code, there are 7 1st-level
>>      headlines
>>   2. at most 3 (if not only 2) of 7 headlines should really be 1st-level
>>      headlines:
>
> Again, this seems like a rather minor issue.  Furthermore, ";;; Code:"
> is a well-known header, so if needed, we can special case it in code
> such as navi.

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. And the sad thing is that sticking to the
conventions forces library authors to do things like putting headers on
the same level that should be subheaders really, and define headers that
are not headers at all.

>>   all other headlines in the header-comment section are subheadlines of
>>   this one, i.e. level 2 or higher.
>
> You can get that without any modification to existing files by
> considering that any header that comes before ";;; Code:" is really one
> deeper than what its semi-colons say.

When leaving existing libraries untouched - wouldn't it be possible to
allow for saner structuring in new libraries?

>>   In oldschool Elisp files, headlines often end in colons. In Org-mode,
>>   this is not usual, and the Org-mode conventions are better in this
>>   case.
>
> Again, trivial to "fix" in any tool like navi: just change a trailing
> colon into a full stop.

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?

>>   The otherwise fantastic library dired.el illustrates why:
>
> All those non-headers are bugs.

ok

>>   8) shows a wild mix of real headlines and comments. This is because it
>>   is only natural for people to get creative with comment characters
>
> Maybe it was a bad idea to choose this convention, but it's easier to
> fix the few cases where people's use of comments ends up accidentally
> colliding with your convention.
>
>>   |       1:;; * iorg-scrape.el --- elisp glue code for `picoLisp/lib/scrape.l'
>
> Note that ";; *" is already in common use for other purposes (basically
> the * is used as a bullet point there), so your convention would also
> bump into other problems.
>
>>   A big plus: this is /major-mode agnostic/. All 3 libraries (outshine,
>
> I'm pretty sure there are many other languages that define their own
> notion of comment structure, and I'd be surprise if any of them happens
> to choose your convention.  IOW your convention is "major-mode agnostic"
> at the cost of not following the "normal" conventions.  Just as is the
> case with allout.el.
>
> This is a trade-off with its benefit and its downsides.
>
> The other option is to make your tools's structuring convention
> sufficiently customizable that it can make adapt to the
> "normal" convention (this is the path taken by outline.el).  It's not
> perfect either, of course, but I think that given the obstacles it's
> either to adapt the tools than to change the conventions.
>
>>   Conversion between oldschool and outshine headlines would be
>>   exceedingly easy - as long as the oldschool files don't mix comments
>>   and headlines, i.e don't have "invalid" syntax (in a loose sense).
>
> Exactly: if they're correct, then the conversion is easy.  So easy that
> you can do it on the fly, without touching the file! ;-)

I agree, if the conventions would allow for sane file structuring,
conversion between headline styles would be so easy that I could use my
favorite style (Org-style) and convert back to oldschool whenever
possible.

>>   | ;; * iorg-scrape.el --- elisp glue code for `picoLisp/lib/scrape.l'
>>   | ;; ** MetaData
>>   | ;;   :PROPERTIES:
>>   | ;;   :copyright: Thorsten_Jolitz
>>   | ;;   :copyright-since: 2013
>
> IIUC the syntax of the "copyright" line is legally significant
> (e.g. whether years can be abbreviated, whether year ranges can be used,
> etc...), and I don't think I want to get into discussions about what
> other syntax we can use.  So I'm not interested in changing the
> copyright line.
>
>>   | ;;   :version:  0.9
>
> The ";; Version:" format is used in ELPA, so changing it would require
> changes in too many places.  Not gonna happen.
>
>>   | ;;   :licence:  GPL3+
>>   | ;;   :licence-url: http://www.gnu.org/licenses/
>
> Here again, the many-lines blurb about the license has legal
> significance (otherwise we'd have switched to ";; License: GPLv3+" by
> now).

ok, I'm not into this legal stuff, I just wanted to demonstrate a syntax
that seemed more suited for meta-data IMO.

>>   2. Since a [Property API] for Org-mode's properties exists, reading
>>      and writing them from an Emacs Lisp program becomes almost trivial.
>
> Reading them is already trivial (via the lisp-mnt.el library).
> Writing is usually very easy already; the only exception could the
> "Keywords:" header which is just a big problem in itself anyway (we
> don't really know which categories should be available).
>
>> 3 Summary
>> =========
>
> 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.

The docstring of `outorg-edit-as-org' shows several ways to include
export options when transforming the whole source-code buffer to Org
(without ARG, this function only acts on the headline at point). With
narrowing the source-code buffer to the commentary headline before
calling this function, you can make use of these options too when
exporting only a single headline.

,---------------------------------------------------------------------------
| outorg-edit-as-org is an interactive Lisp function in `outorg.el'.
|
| It is bound to M-# #, M-# ', M-# M-#, <menu-bar> <Outshine> <Edit As Org>.
|
| (outorg-edit-as-org &optional ARG)
|
| Convert and copy to temporary Org buffer
|
| With ARG, act conditional on the raw value of ARG:
|
| | prefix | raw | action 1          | action 2                         |
| |--------+-----+-------------------+----------------------------------|
| | C-u    | (4) | edit-whole-buffer | ---                              |
| | C-1    |   1 | edit-whole-buffer | insert default export-template   |
| | C-2    |   2 | edit-whole-buffer | ask user for template-file       |
| | C-3    |   3 | edit-whole-buffer | insert and keep default template |
| | C-4    |   4 | edit-whole-buffer | insert and keep template-file    |
|
`---------------------------------------------------------------------------


--
cheers,
Thorsten

Re: Modern conventions for structuring Emacs Lisp libraries

[Stefan Monnier]

> Assuming that
> [[http://www.emacswiki.org/emacs/ElispAreaConventions][this page]]
> reflects the official recommendations, they look like this:
[...]
> I would, as described in my proposal, critisize that

Whatever their defects, those conventions are what we have to work with.

> 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?

Of course it's possible.  But it's much easier to write tools that
reinterpret the current conventions to give you a better structure than
to change the actual files.  This has the advantage that you don't need
to deal with coexistence of two different conventions, and the fact that
some tools will only work with one of the two conventions (or may even
mishandle files using the other).


        Stefan

Re: Modern conventions for structuring Emacs Lisp libraries

[Stefan Monnier]

>> | ;; Maintainer: FSF
>> | ;; Keywords: help,  internal
>> | ;; Package: emacs

This is not "free format".  We have tools to parse this, including
conventions for how to extend one of the above headers onto multiple
lines, when needed.


        Stefan

Re: Modern conventions for structuring Emacs Lisp libraries

[Stefan Monnier]

> 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

Re: Modern conventions for structuring Emacs Lisp libraries

[Richard Stallman]

        [ 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.

    >       | ;; GNU Emacs is distributed in the hope that it will be useful,
    >       | ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
    >       | ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    >       | ;; GNU General Public License for more details.

    Is this shouty bit really necessary?

Our lawyers advised us to use this text.
On legal matters, we follow their advice.


-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: Modern conventions for structuring Emacs Lisp libraries

[Josh]

[-- Attachment #1: Type: text/plain, Size: 1715 bytes --]

On Sun, Oct 6, 2013 at 10:42 AM, Thorsten Jolitz <tjolitz@gmail.com> wrote:
> Stefan Monnier <monnier@iro.umontreal.ca> writes:
>
> >> as a second take on this topic, I would like to make the attached
> >> proposal for improving the conventions for structuring Emacs Lisp
> >> source-code files:

When picking up discussions like this one that have been dormant for
many months it is helpful to follow up to the original thread or provide a
link to the earlier discussion to make it easier for people to refresh
their memories or acquaint themselves with where the discussion left
off: http://lists.gnu.org/archive/html/emacs-devel/2013-04/msg00263.html

> >> 2.2.1 Last Line Pathology
> >> -------------------------
> >
> > This is a very minor issue, I think.  It's trivil to fix it by simply
> > ignoring any "trailing header".
> Can't the existing tools be modified to accept both, a trailing header
> or a trailing comment? It might seem like a very minor issue, but its a
> symptom for a not so minor issue - incorrect headline tree-structure.

Most of your arguments seem to be predicated on the incorrect assumption
that "^;;; Text" can /only/ indicate a first-level headline.  The manual
page at (info "(elisp) Comment Tips") begins with the text "We recommend
these conventions for comments:" and goes on to describe several uses
for comments of the above form, of which headlines are but one.  Using
such comments in any of these ways is perfectly legitimate, not an
indication of "pathology" or even incorrect.  That same manual page also
describes how to cause outline-minor-mode to refrain from considering
certain of these comments as headings, namely to follow the semicolons
by two or more spaces.

[-- Attachment #2: Type: text/html, Size: 2188 bytes --]

Re: Modern conventions for structuring Emacs Lisp libraries

[Pascal J. Bourguignon]

Josh <josh@foxtail.org> writes:

> Most of your arguments seem to be predicated on the incorrect
> assumption that "^;;; Text" can /only/ indicate a first-level
> headline. 

I use ;;;; for the header comments in my files.

Indeed ;;; are used for section headlines.

-- 
__Pascal Bourguignon__
http://www.informatimago.com/

Re: Modern conventions for structuring Emacs Lisp libraries

[Xue Fuqiao]

On Mon, Oct 7, 2013 at 12:40 AM, Thorsten Jolitz <tjolitz@gmail.com> wrote:
> Assuming that
> [[http://www.emacswiki.org/emacs/ElispAreaConventions][this page]]
> reflects the official recommendations

FYI the "official recommendation" is in:
    [[info:elisp#Comment%20Tips][info:elisp#Comment Tips]]
      and
    [[info:elisp#Library%20Headers][info:elisp#Library Headers]]

-- 
Best regards, Xue Fuqiao.
http://www.gnu.org/software/emacs/