Re: Comment conventions, adding an explicit Header.

[Thorsten Jolitz <tjolitz@gmail.com>]

phillip.lord@newcastle.ac.uk (Phillip Lord) writes:

Hallo, 

> Currently, emacs uses comments of the form ";;; Commentary;" to
> effectively indicate section headers in the buffer.

I once did a pretty exhaustive analysis of the 'pathologies' of current
emacs lisp conventions for file structuring:

,----
| https://lists.gnu.org/archive/html/emacs-devel/2013-10/msg00112.html
`----

and while maintainers did acknowledge the weaknesses I described, the
probability of introducing 'modern conventions' seems to tend towards
zero.

But for myself (always using outshine and navi-mode) I developed a
default file structure and a new way to store library meta-data, see
e.g. navi-mode.el:

,----
| 20 matches for "^;;;;? " in buffer: navi-mode.el
|       1:;;; navi-mode.el --- major-mode for easy buffer-navigation
|       7:;;;; MetaData
|      23:;;;; Commentary
|     270:;;;; ChangeLog
|     278:;;; Requires
|     283:;;; Mode Definitions
|     314:;;; Variables
|     315:;;;; Consts
|     316:;;;; Vars
|     335:;;;; Hooks
|     340:;;;; Fonts
|     341:;;;; Customs
|     960:;;; Defuns
|     961:;;;; Functions
|    1471:;;;; Commands
|    2156:;;; Menus and Keys
|    2157:;;;; Menus
|    2368:;;;; Keys
|    2516:;;; Run Hooks and Provide
|    2523:;;; navi-mode.el ends here
`----

with several subtrees under these headlines, e.g.

,----
|       1:;;; navi-mode.el --- major-mode for easy buffer-navigation
|       7:;;;; MetaData
|      23:;;;; Commentary
|      25:;;;;; About navi-mode
|      65:;;;;; Usage
|     245:;;;;; Installation
|     264:;;;;; Emacs Version
|     270:;;;; ChangeLog
|     278:;;; Requires [...]
`----

and this MetaData section, easily editable in Org-mode via outorg:

,----
| ;;;; MetaData
| ;;   :PROPERTIES:
| ;;   :copyright: Thorsten Jolitz
| ;;   :copyright-years: 2013+
| ;;   :version:  2.0
| ;;   :licence:  GPL 2 or later (free software)
| ;;   :licence-url: http://www.gnu.org/licenses/
| ;;   :part-of-emacs: no
| ;;   :author: Thorsten Jolitz
| ;;   :author_email: tjolitz AT gmail DOT com
| ;;   :git-repo: https://github.com/tj64/navi.git
| ;;   :git-clone: git://github.com/tj64/navi.git
| ;;   :inspiration:  occur-mode org-mode 
| ;;   :keywords: emacs navigation remote-buffer-control
| ;;   :END:
`----

[Note that I had to use oldschool instead of outshine headers and to
include the pathological last line ";;; navi-mode.el ends here", which
is not a headline at all, to please MELPA]

-- 
cheers,
Thorsten