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

[Eli Zaretskii <eliz@gnu.org>]

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