all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* 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

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 external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.