R devel - May 2025 - Recommend/clarify in ?utils::news that h2/h3 markdown hierarchy is preferable to h1/h2

The current wording in ?utils::news reads to me as implying we should
use `#` and `##` for the respective version, category headings [1]:
> File NEWS.md should contain the news in Markdown..., with the
> primary heading level giving the version number... Where available,
> secondary headings are taken to indicate categories.
This style is quite common in R packages, but it trips the alarms of
basically every markdown linter/style guide -- advice against using
multiple <h1> tags in HTML abounds (e.g. [2], [3], [4]). There is some
nuance, but I haven't seen anything suggesting those exceptions
definitely apply for R package NEWS files.

Anyway, utils::news _is_ perfectly happy with NEWS files using `##`
and `###` instead [5]; this is documented in an internal comment [6].

Is there an argument against (1) directly advocating h2/h3 usage in
?utils::news; or, more softly, (2) documenting that any (L,L+1) pair,
1<=L<=5, where 'L' gives version numbers as described, will be
accepted when producing the news database? Note that doing so is
perfectly back-compatible -- we needn't change the code at all, only
its documentation.

Mike C

[1]
https://github.com/r-devel/r-svn/blob/72d8171a54532ffe0fd44306caa0ee953cecc91e/src/library/utils/man/news.Rd#L95-L100
[2]
https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/Heading_Elements
[3] https://yoast.com/one-h1-heading-per-post/
[4] https://www.youtube.com/watch?v=GIn5qJKU8VM
[5] https://gist.github.com/MichaelChirico/49f51edeecc288d7aabf6bc53cb1aa89
[6]
https://github.com/r-devel/r-svn/blob/72d8171a54532ffe0fd44306caa0ee953cecc91e/src/library/tools/R/news.R#L790-L807

>>>>> Michael Chirico writes:
Thanks.  Should be ok to change the wording (provided this can be done
without confusing maintainers).  

Perhaps you could make a suggestion? :-)

Best
-k
> The current wording in ?utils::news reads to me as implying we should
> use `#` and `##` for the respective version, category headings [1]:
>> File NEWS.md should contain the news in Markdown..., with the
>> primary heading level giving the version number... Where available,
>> secondary headings are taken to indicate categories.
> This style is quite common in R packages, but it trips the alarms of
> basically every markdown linter/style guide -- advice against using
> multiple <h1> tags in HTML abounds (e.g. [2], [3], [4]). There is
some
> nuance, but I haven't seen anything suggesting those exceptions
> definitely apply for R package NEWS files.
> Anyway, utils::news _is_ perfectly happy with NEWS files using `##`
> and `###` instead [5]; this is documented in an internal comment [6].
> Is there an argument against (1) directly advocating h2/h3 usage in
> ?utils::news; or, more softly, (2) documenting that any (L,L+1) pair,
> 1<=L<=5, where 'L' gives version numbers as described, will
be
> accepted when producing the news database? Note that doing so is
> perfectly back-compatible -- we needn't change the code at all, only
> its documentation.
> Mike C
> [1]
https://github.com/r-devel/r-svn/blob/72d8171a54532ffe0fd44306caa0ee953cecc91e/src/library/utils/man/news.Rd#L95-L100
> [2]
https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/Heading_Elements
> [3] https://yoast.com/one-h1-heading-per-post/
> [4] https://www.youtube.com/watch?v=GIn5qJKU8VM
> [5] https://gist.github.com/MichaelChirico/49f51edeecc288d7aabf6bc53cb1aa89
> [6]
https://github.com/r-devel/r-svn/blob/72d8171a54532ffe0fd44306caa0ee953cecc91e/src/library/tools/R/news.R#L790-L807
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel