[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Regarding outline headings in emacs-lisp libraries
From: |
Jonas Bernoulli |
Subject: |
Re: Regarding outline headings in emacs-lisp libraries |
Date: |
Sun, 26 Jul 2020 17:32:14 +0200 |
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
- RE: Regarding outline headings in emacs-lisp libraries, (continued)
- Re: Regarding outline headings in emacs-lisp libraries, Jonas Bernoulli, 2020/07/18
- Re: Regarding outline headings in emacs-lisp libraries, Stefan Monnier, 2020/07/18
- Re: Regarding outline headings in emacs-lisp libraries, Eli Zaretskii, 2020/07/19
- Re: Regarding outline headings in emacs-lisp libraries, Jonas Bernoulli, 2020/07/26
- Re: Regarding outline headings in emacs-lisp libraries, Eli Zaretskii, 2020/07/26
- Re: Regarding outline headings in emacs-lisp libraries, Jonas Bernoulli, 2020/07/26
- Re: Regarding outline headings in emacs-lisp libraries, Eli Zaretskii, 2020/07/26
- Re: Regarding outline headings in emacs-lisp libraries, Jonas Bernoulli, 2020/07/26
- Re: Regarding outline headings in emacs-lisp libraries, Stefan Monnier, 2020/07/26
- Re: Regarding outline headings in emacs-lisp libraries,
Jonas Bernoulli <=
- Re: Regarding outline headings in emacs-lisp libraries, Yuan Fu, 2020/07/26
- Re: Regarding outline headings in emacs-lisp libraries, Stefan Monnier, 2020/07/26
- Re: Regarding outline headings in emacs-lisp libraries, Eli Zaretskii, 2020/07/26
- Re: Regarding outline headings in emacs-lisp libraries, Stefan Monnier, 2020/07/26
- Re: Regarding outline headings in emacs-lisp libraries, Jonas Bernoulli, 2020/07/28
- Re: Regarding outline headings in emacs-lisp libraries, Eli Zaretskii, 2020/07/28
- Re: Regarding outline headings in emacs-lisp libraries, Jonas Bernoulli, 2020/07/28
- Re: Regarding outline headings in emacs-lisp libraries, Eli Zaretskii, 2020/07/28
- Re: Regarding outline headings in emacs-lisp libraries, Stefan Monnier, 2020/07/28
- Re: Regarding outline headings in emacs-lisp libraries, Jonas Bernoulli, 2020/07/26