--- Begin Message ---
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>
--- End Message ---
--- Begin Message ---
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@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.
--- End Message ---