* bug#66067: 30.0.50; CONTRIBUTE: Questions about instructions on etc/NEWS file markup
@ 2023-09-18 8:38 Ihor Radchenko
2023-09-18 11:21 ` Eli Zaretskii
0 siblings, 1 reply; 6+ messages in thread
From: Ihor Radchenko @ 2023-09-18 8:38 UTC (permalink / raw)
To: 66067
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>
^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#66067: 30.0.50; CONTRIBUTE: Questions about instructions on etc/NEWS file markup
2023-09-18 8:38 bug#66067: 30.0.50; CONTRIBUTE: Questions about instructions on etc/NEWS file markup Ihor Radchenko
@ 2023-09-18 11:21 ` Eli Zaretskii
2023-09-18 15:13 ` Michael Albinus
2023-09-19 10:58 ` Ihor Radchenko
0 siblings, 2 replies; 6+ messages in thread
From: Eli Zaretskii @ 2023-09-18 11:21 UTC (permalink / raw)
To: Ihor Radchenko; +Cc: 66067-done
> 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.
^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#66067: 30.0.50; CONTRIBUTE: Questions about instructions on etc/NEWS file markup
2023-09-18 11:21 ` Eli Zaretskii
@ 2023-09-18 15:13 ` Michael Albinus
2023-09-19 10:12 ` Ihor Radchenko
2023-09-19 10:58 ` Ihor Radchenko
1 sibling, 1 reply; 6+ messages in thread
From: Michael Albinus @ 2023-09-18 15:13 UTC (permalink / raw)
To: 66067; +Cc: eliz, yantar92
Eli Zaretskii <eliz@gnu.org> writes:
Hi,
>> 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.
Quoting 'this style' results in clickable symbol buttons, when viewed with
`emacs-news-view-mode'. See regexp "'\\([^-][^ \t\n]+\\)'".
>> 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.
In the NEWS file, we prefer such a convention. In
`emacs-news-view-mode', all text matching "\"\\(([a-z0-9-]+)[
\n][^\"]\\{1,80\\}\\)\"" is regarded as info manual reference, and it is
buttonized accordingly.
Both conventions are implemented in `emacs-news--buttonize'. Other NEWS
files, like ERC-NEWS, follow these conventions.
Best regards, Michael.
^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#66067: 30.0.50; CONTRIBUTE: Questions about instructions on etc/NEWS file markup
2023-09-18 15:13 ` Michael Albinus
@ 2023-09-19 10:12 ` Ihor Radchenko
0 siblings, 0 replies; 6+ messages in thread
From: Ihor Radchenko @ 2023-09-19 10:12 UTC (permalink / raw)
To: Michael Albinus; +Cc: eliz, 66067
Michael Albinus <michael.albinus@gmx.de> writes:
> Both conventions are implemented in `emacs-news--buttonize'. Other NEWS
> files, like ERC-NEWS, follow these conventions.
Following more strict conventions can also add an extra benefit,
allowing to export NEWS to html more easily.
--
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>
^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#66067: 30.0.50; CONTRIBUTE: Questions about instructions on etc/NEWS file markup
2023-09-18 11:21 ` Eli Zaretskii
2023-09-18 15:13 ` Michael Albinus
@ 2023-09-19 10:58 ` Ihor Radchenko
2023-09-19 12:11 ` Eli Zaretskii
1 sibling, 1 reply; 6+ messages in thread
From: Ihor Radchenko @ 2023-09-19 10:58 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: 66067-done
Eli Zaretskii <eliz@gnu.org> writes:
>> 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".
Did you push a commit? I am not seeing anything on master and emacs-29
branches.
--
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>
^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#66067: 30.0.50; CONTRIBUTE: Questions about instructions on etc/NEWS file markup
2023-09-19 10:58 ` Ihor Radchenko
@ 2023-09-19 12:11 ` Eli Zaretskii
0 siblings, 0 replies; 6+ messages in thread
From: Eli Zaretskii @ 2023-09-19 12:11 UTC (permalink / raw)
To: Ihor Radchenko; +Cc: 66067-done
> From: Ihor Radchenko <yantar92@posteo.net>
> Cc: 66067-done@debbugs.gnu.org
> Date: Tue, 19 Sep 2023 10:58:42 +0000
>
> Eli Zaretskii <eliz@gnu.org> writes:
>
> >> 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".
>
> Did you push a commit? I am not seeing anything on master and emacs-29
> branches.
Oops. Pushed now.
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2023-09-19 12:11 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2023-09-18 8:38 bug#66067: 30.0.50; CONTRIBUTE: Questions about instructions on etc/NEWS file markup Ihor Radchenko
2023-09-18 11:21 ` Eli Zaretskii
2023-09-18 15:13 ` Michael Albinus
2023-09-19 10:12 ` Ihor Radchenko
2023-09-19 10:58 ` Ihor Radchenko
2023-09-19 12:11 ` Eli Zaretskii
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).