]> git.eshelyaron.com Git - emacs.git/commit
Update section heading conventions for libraries
authorJonas Bernoulli <jonas@bernoul.li>
Sun, 9 Aug 2020 21:02:34 +0000 (23:02 +0200)
committerJonas Bernoulli <jonas@bernoul.li>
Thu, 13 Aug 2020 09:34:49 +0000 (11:34 +0200)
commit838a1a313caf9695a518c69b553abc1389b22495
tree68fd4a6f80fbac3b2d5ef6a098caa3c5a21250a1
parent7cb029d4d32b0f43c37e6129420db8ea8ed5e900
Update section heading conventions for libraries

* doc/lispref/tips.texi (Comment Tips): Update information on section
  headings to reflect common usage.

Previously the tips stated that if the code is split up into multiple
sections, then that should be done by splitting up the ";;; Code:"
section into multiple sub-sections.

However about half the libraries in Emacs instead use multiple
top-level sections.  We update the tips (aka conventions) to allow
this common usage, but because it is awkward if there is a section
named "Code", which contains only some of the code instead of all of
it, we now recommend that that section should be empty in this case.

We cannot just give up on the "Code:" section/heading because that is
an old convention that is followed be nearly every library and because
it is likely that there are some utilities out there that depend on
its presence.

This was discussed in
https://lists.gnu.org/archive/html/emacs-devel/2020-07/msg00444.html
https://lists.gnu.org/archive/html/emacs-devel/2020-08/msg00001.html
doc/lispref/tips.texi