GNU bug report logs - #66067
30.0.50; CONTRIBUTE: Questions about instructions on etc/NEWS file markup

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 66067 in the body.
You can then email your comments to 66067 AT debbugs.gnu.org in the normal way.

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

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

From: Ihor Radchenko <yantar92 <at> posteo.net>
To: bug-gnu-emacs <at> gnu.org
Subject: 30.0.50; CONTRIBUTE: Questions about instructions on etc/NEWS file
 markup
Date: Mon, 18 Sep 2023 08:38:44 +0000

Hi,

When writing the NEWS entry for bug#65469, I was trying to follow the
instructions in CONTRIBUTE file. However, not everything was very clear
and I had to consult the git log, other entries, and do some guess work.

In particular:

1. It is not documented whether new NEWS entries should go in front or
   at the end of the news list under the same category.

2. CONTRIBUTE states: "Think about whether your change requires updating
   the manuals. If you know it does not, mark the NEWS entry with
   "---"."

   However, it is not clear what "mark" means. When looking into NEWS
   file, I saw things like

   * item 1

   ---
   * item 2

   ...

   And it is not clear if "---" refers to item 1 or item 2.

3. "Documenting your changes" section of CONTRIBUTE file refers to
   documentation tips section of Elisp manual. However, NEWS file
   appears to use a slightly different quoting scheme for variable and
   function names. For example,

   ** 'write-region-inhibit-fsync' now defaults to t in interactive mode,

   uses straight quotes '...', not the usual `...' docstring style.

4. I was also confused how to refer to info nodes from NEWS. I found one
   example in

   For more information, see the "(eshell) Built-ins" node in the Eshell
   manual.

   but the convention is not documented anywhere.

   I _guessed_ that the quoting should be similar to docstring style,
   but using "..." quotes instead of `...' and adding space in
   "(manual) Section" instead of `(manual)Section' used in the
   docstrings.

I believe that the above and any other conventions should be explained
better.

In GNU Emacs 30.0.50 (build 3, x86_64-pc-linux-gnu, GTK+ Version
 3.24.38, cairo version 1.17.8) of 2023-09-15 built on localhost
Repository revision: 8a29da91bdcbffe2d7a67f04e235cdf238bd4be8
Repository branch: master
Windowing system distributor 'The X.Org Foundation', version 11.0.12101008
System Description: Gentoo Linux

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Ihor Radchenko <yantar92 <at> posteo.net>
Cc: 66067-done <at> debbugs.gnu.org
Subject: Re: bug#66067: 30.0.50;
 CONTRIBUTE: Questions about instructions on etc/NEWS file markup
Date: Mon, 18 Sep 2023 14:21:54 +0300

> From: Ihor Radchenko <yantar92 <at> posteo.net>
> Date: Mon, 18 Sep 2023 08:38:44 +0000
> 
> 1. It is not documented whether new NEWS entries should go in front or
>    at the end of the news list under the same category.

That's because "it depends": the entries should be arranged in the
order of importance, if possible.  Usually, the importance order is
not very clear, with rare exceptions, so the order is basically
arbitrary.

> 
> 2. CONTRIBUTE states: "Think about whether your change requires updating
>    the manuals. If you know it does not, mark the NEWS entry with
>    "---"."
> 
>    However, it is not clear what "mark" means. When looking into NEWS
>    file, I saw things like
> 
>    * item 1
> 
>    ---
>    * item 2
> 
>    ...
> 
>    And it is not clear if "---" refers to item 1 or item 2.

I'm surprised it wasn't clear, but I added an explicit "before".

> 3. "Documenting your changes" section of CONTRIBUTE file refers to
>    documentation tips section of Elisp manual. However, NEWS file
>    appears to use a slightly different quoting scheme for variable and
>    function names. For example,
> 
>    ** 'write-region-inhibit-fsync' now defaults to t in interactive mode,
> 
>    uses straight quotes '...', not the usual `...' docstring style.

We support both styles, and there are strong feelings in both camps.
'Nough said.

> 4. I was also confused how to refer to info nodes from NEWS. I found one
>    example in
> 
>    For more information, see the "(eshell) Built-ins" node in the Eshell
>    manual.
> 
>    but the convention is not documented anywhere.

There is no such convention.  The r_is_ a convention for this in Lisp
doc strings, and it is described in the ELisp manual.

Closing.

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

From: Michael Albinus <michael.albinus <at> gmx.de>
To: 66067 <at> debbugs.gnu.org
Cc: eliz <at> gnu.org, yantar92 <at> posteo.net
Subject: Re: bug#66067: 30.0.50; CONTRIBUTE: Questions about instructions on
 etc/NEWS file markup
Date: Mon, 18 Sep 2023 17:13:43 +0200

Eli Zaretskii <eliz <at> gnu.org> writes:

Hi,

>> 3. "Documenting your changes" section of CONTRIBUTE file refers to
>>    documentation tips section of Elisp manual. However, NEWS file
>>    appears to use a slightly different quoting scheme for variable and
>>    function names. For example,
>>
>>    ** 'write-region-inhibit-fsync' now defaults to t in interactive mode,
>>
>>    uses straight quotes '...', not the usual `...' docstring style.
>
> We support both styles, and there are strong feelings in both camps.
> 'Nough said.

Quoting 'this style' results in clickable symbol buttons, when viewed with
`emacs-news-view-mode'. See regexp "'\\([^-][^ \t\n]+\\)'".

>> 4. I was also confused how to refer to info nodes from NEWS. I found one
>>    example in
>>
>>    For more information, see the "(eshell) Built-ins" node in the Eshell
>>    manual.
>>
>>    but the convention is not documented anywhere.
>
> There is no such convention.  The r_is_ a convention for this in Lisp
> doc strings, and it is described in the ELisp manual.

In the NEWS file, we prefer such a convention. In
`emacs-news-view-mode', all text matching "\"\\(([a-z0-9-]+)[
\n][^\"]\\{1,80\\}\\)\"" is regarded as info manual reference, and it is
buttonized accordingly.

Both conventions are implemented in `emacs-news--buttonize'. Other NEWS
files, like ERC-NEWS, follow these conventions.

Best regards, Michael.

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

From: Ihor Radchenko <yantar92 <at> posteo.net>
To: Michael Albinus <michael.albinus <at> gmx.de>
Cc: eliz <at> gnu.org, 66067 <at> debbugs.gnu.org
Subject: Re: bug#66067: 30.0.50; CONTRIBUTE: Questions about instructions on
 etc/NEWS file markup
Date: Tue, 19 Sep 2023 10:12:25 +0000

Michael Albinus <michael.albinus <at> gmx.de> writes:

> Both conventions are implemented in `emacs-news--buttonize'. Other NEWS
> files, like ERC-NEWS, follow these conventions.

Following more strict conventions can also add an extra benefit,
allowing to export NEWS to html more easily.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

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

From: Ihor Radchenko <yantar92 <at> posteo.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 66067-done <at> debbugs.gnu.org
Subject: Re: bug#66067: 30.0.50; CONTRIBUTE: Questions about instructions on
 etc/NEWS file markup
Date: Tue, 19 Sep 2023 10:58:42 +0000

Eli Zaretskii <eliz <at> gnu.org> writes:

>>    And it is not clear if "---" refers to item 1 or item 2.
>
> I'm surprised it wasn't clear, but I added an explicit "before".

Did you push a commit? I am not seeing anything on master and emacs-29
branches.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Ihor Radchenko <yantar92 <at> posteo.net>
Cc: 66067-done <at> debbugs.gnu.org
Subject: Re: bug#66067: 30.0.50; CONTRIBUTE: Questions about instructions on
 etc/NEWS file markup
Date: Tue, 19 Sep 2023 15:11:21 +0300

> From: Ihor Radchenko <yantar92 <at> posteo.net>
> Cc: 66067-done <at> debbugs.gnu.org
> Date: Tue, 19 Sep 2023 10:58:42 +0000
> 
> Eli Zaretskii <eliz <at> gnu.org> writes:
> 
> >>    And it is not clear if "---" refers to item 1 or item 2.
> >
> > I'm surprised it wasn't clear, but I added an explicit "before".
> 
> Did you push a commit? I am not seeing anything on master and emacs-29
> branches.

Oops.  Pushed now.

Previous Next

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