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

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

[Ihor Radchenko]

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>

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

[Eli Zaretskii]

> From: Ihor Radchenko <yantar92@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.

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

[Michael Albinus]

Eli Zaretskii <eliz@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.

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

[Ihor Radchenko]

Michael Albinus <michael.albinus@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>

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

[Ihor Radchenko]

Eli Zaretskii <eliz@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>

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

[Eli Zaretskii]

> From: Ihor Radchenko <yantar92@posteo.net>
> Cc: 66067-done@debbugs.gnu.org
> Date: Tue, 19 Sep 2023 10:58:42 +0000
> 
> Eli Zaretskii <eliz@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.