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

Previous Next

Full log

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.

Previous Next

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