GNU bug report logs -
#66067
30.0.50; CONTRIBUTE: Questions about instructions on etc/NEWS file markup
Previous Next
Reported by: Ihor Radchenko <yantar92 <at> posteo.net>
Date: Mon, 18 Sep 2023 08:39:02 UTC
Severity: normal
Found in version 30.0.50
Done: Eli Zaretskii <eliz <at> gnu.org>
Bug is archived. No further changes may be made.
Full log
View this message in rfc822 format
[Message part 1 (text/plain, inline)]
Your bug report
#66067: 30.0.50; CONTRIBUTE: Questions about instructions on etc/NEWS file markup
which was filed against the emacs package, has been closed.
The explanation is attached below, along with your original report.
If you require more details, please reply to 66067 <at> debbugs.gnu.org.
--
66067: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=66067
GNU Bug Tracking System
Contact help-debbugs <at> gnu.org with problems
[Message part 2 (message/rfc822, inline)]
> 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.
[Message part 3 (message/rfc822, inline)]
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>
This bug report was last modified 1 year and 248 days ago.
Previous Next
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.