Subject: bug#66067: 30.0.50; CONTRIBUTE: Questions about instructions on etc/NEWS file markup

From: Michael Albinus <[email-masked]>
Date: Mon, 18 Sep 2023 17:13:43 +0200

Eli Zaretskii <[email-masked]> 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.