GNU bug report logs -
#78253
Elisp manual: D.8 Conventional Headers for Emacs Libraries, re: 'History'
Previous Next
Reported by: Cena Mayo <cenazoic <at> gmail.com>
Date: Mon, 5 May 2025 07:19:02 UTC
Severity: normal
Done: Eli Zaretskii <eliz <at> gnu.org>
Bug is archived. No further changes may be made.
Full log
Message #10 received at 78253-done <at> debbugs.gnu.org (full text, mbox):
> From: Cena Mayo <cenazoic <at> gmail.com>
> 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.
This bug report was last modified 17 days ago.
Previous Next
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.