Subject: Re: bug#78253: Elisp manual: D.8 Conventional Headers for Emacs Libraries, re: 'History'

From: Eli Zaretskii <[email-masked]>
Date: Mon, 05 May 2025 14:58:09 +0300

> From: Cena Mayo <[email-masked]>
> Date: Sun, 4 May 2025 13:14:28 -0500
> 
> On https://www.gnu.org/software/emacs/manual/html_node/elisp/Library-Headers.html, 
> 
> the following statement appears:
> 
> > 
> ‘;;; Change Log:’
> 
>  This begins an optional log of changes to the file over time. Don’t put too much information in this
>  section—it is better to keep the detailed logs in a version control system (as Emacs does) or in a
>  separate ChangeLog file. ‘History’ is an alternative to ‘Change Log’. 
> 
> However, 'History' is first mentioned in the line above this one (";;; Commentary:") so suggest it should be
> defined there, if not on a separate line.

It's just awkward wording.  The text wants to say that the Commentary
comments and with one of those lines.  I've modified the wording to
make that more clear.  There's nothing wrong in general in saying
"these lines, described below, end this section".

> 2)
>  > " Here is a table of the conventional possibilities for header-name:"
> 
> It's not clearly stated (but perhaps implied) that the header-names displayed on this page are (currently) the
> only ones you should use/can be read by builtin Emacs functions.  Can you make up or define your own?

One can add header lines even though the current Emacs tools don't use
them.  The "conventional" part hints that those are our conventions,
so I think the current wording is good enough.

Thanks, the changes are now installed on the emacs-30 release branch.