Sounds good. Moving over to Bugzilla: https://bugs.r-project.org/attachment.cgi?id=3480&action=diff
On Mon, May 12, 2025 at 10:29 AM Kurt Hornik <kurt.hor...@wu.ac.at> wrote: > > >>>>> 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@r-project.org mailing list > > https://stat.ethz.ch/mailman/listinfo/r-devel ______________________________________________ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
