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

Previous Next

Full log

View this message in rfc822 format

From: help-debbugs <at> gnu.org (GNU bug Tracking System)
To: Cena Mayo <cenazoic <at> gmail.com>
Subject: bug#78253: closed (Re: bug#78253: Elisp manual: D.8 Conventional
 Headers for Emacs Libraries, re: 'History')
Date: Mon, 05 May 2025 11:59:01 +0000

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

Your bug report

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

which was filed against the emacs package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to 78253 <at> debbugs.gnu.org.

-- 
78253: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=78253
GNU Bug Tracking System
Contact help-debbugs <at> gnu.org with problems

[Message part 2 (message/rfc822, inline)]

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.

[Message part 3 (message/rfc822, inline)]

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 4 (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 5 (text/html, inline)]

Previous Next

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