Re: Regarding outline headings in emacs-lisp libraries

[Jonas Bernoulli <jonas@bernoul.li>]

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

>> Personally I would also recommend that people use a "back matter"
>> section similar to the "front matter" section that is ";;; Code:", but
>> I fear my preferred heading for that, ";;; _", might not find too many
>> fans.  But then again, I might be wrong, what do you think about ending
>> with this instead:
>
> Indeed, I don't much like `;;; _` simply because it is non-descriptive.
>
> Could we try and find a good name for those sections?
> What do you put in those things (other than file-local vars)?

There's actually two sections that we might want to find better names
for.  Let's use "front matter" and "back matter" as working titles at
least.

- Currently we use "Code:" as the name of that "front matter" section.

  It usually contains a bunch of `require' forms and maybe some function
  and variable declaration when we want to avoid loading the respective
  libraries up front.

  We could therefore name it "Dependencies".  But that does not always
  match the content perfectly.  This section may also contain other
  things that "have to happen early on" and/or "don't fit anywhere
  else".  For example the definition of `PACKAGE-version' or internal
  variables and macros that are used early on.

  Sticking to "Code:" has the advantage that we can justify that by
  "that's what it used to be called and since we cannot think of
  anything better we might as well stick to it.  Of course if we
  actually could think of something better...

- We currently don't put the `provide' form, the local variable
  definitions and other "stuff that goes at the end" into a dedicated
  "back matter" section.  Instead we put these things at the end
  whatever other completely unrelated section happens to come last in
  the file.

  In my own libraries I name that section "_" and (beside the things
  just mentioned that have to go there because they have to be placed
  near the end of the file) I also use it for "administrative things",
  like adding functions to third-party hooks, test definitions,
  font-lock keyword definitions for forms defined across the file.

  Some of these things may define separate sections or in same cases
  they should be placed elsewhere further up in the file along-side
  related stuff.  But sometimes/often that doesn't work / is overkill
  and it is nice to have a "All the crap that remains" section, that
  has a non-descriptive name such as "_".

  I tend to think of the non-descriptiveness as a feature.

The best I can come up right now is "Front matter" and "Back matter".
Or else "Code:" and "_" as suggested before.  But hopefully someone else
can think of something better.

     Jonas