[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#66067: 30.0.50; CONTRIBUTE: Questions about instructions on etc/NEWS
From: |
Eli Zaretskii |
Subject: |
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@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.