GNU bug report logs - #78253
Elisp manual: D.8 Conventional Headers for Emacs Libraries, re: 'History'

Previous Next

To reply to this bug, email your comments to 78253 AT debbugs.gnu.org.
There is no need to reopen the bug first.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Cena Mayo <cenazoic <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: Elisp manual: D.8 Conventional Headers for Emacs Libraries,
 re: 'History'
Date: Sun, 4 May 2025 13:14:28 -0500

[Message part 1 (text/plain, inline)]

Hi,

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.

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?

Best,
C. Mayo

[Message part 2 (text/html, inline)]

Message #10 received at 78253-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Cena Mayo <cenazoic <at> gmail.com>
Cc: 78253-done <at> debbugs.gnu.org
Subject: Re: bug#78253: Elisp manual: D.8 Conventional Headers for Emacs
 Libraries, re: 'History'
Date: Mon, 05 May 2025 14:58:09 +0300

> 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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.