Simon Josefsson [2025-11-28 08:46 +0100] wrote:
> "Basil L. Contovounesios" <[email protected]> writes:
> I'm not sure what markup we should recommend between the '#
> Noteworthy...' section headings, I think there is some room for
> improvements here? Suggestions?
I like to format each individual piece of news as an unordered list
item, which affords decent flexibility in formatting. Assuming
CommonMark[0], for example:
- sublists are nested with indentation (and optionally a different
bullet point style), which I find easier to parse visually;
- lists can be rendered either tightly or loosely depending on the
presence of inter-item spacing in the Markdown source (as in this
list); and
- changing bullet point style (between -/+/*) or leaving a line empty at
the same level of indentation starts a new grouping of items (with
loose packing between groups).
Subheadings can further group news items under a descriptive name,
e.g. new features vs breaking changes vs fixes:
# My NEWS
...
## Changes in ...
### Deprecations
- Calling `foo` with two arguments is diagnosed with a warning
### New
- Convenience function `bar`
- Configuration option `baz`
+ Support for building with:
* X (`--with-libx`, on by default)
* Y (`--with-liby`, recommended)
+ Support for running self-tests under Valgrind
### Fixes
- Fixed a regression from v0.1.2 that replaced a random NEWS file
under HOME with NEWS.md on every 1000th keystroke
[0]: https://spec.commonmark.org/current/
> 2) I realized that 'make dist' will not add the symlink NEWS and README
> into the tarball but will instead add the target of those symlinks into
> the tarball. This means the tarball does not have a NEWS.md or
> README.md (unless those are added to EXTRA_DIST, but then we get two
> copies of the same file in the tarball). Which further means we now
> have markdown markup used in a non-*.md file. I haven't had any problem
> with README vs README.md due to this, but it seems sub-optimal.
>
> What is a good improvement here? I suppose symlinks in tarballs aren't
> portable?
Can this limitation be worked around in dist-hook?
> I think my preference is to only have a NEWS.md and README.md
> file in the 'make dist' tarball.
Mine too.
> But there is an awful amount of legacy
> the refers to NEWS and README files. Could we re-interpret them as not
> refering to those files explicitly, but the concept of those files?
> Which is provided via NEWS.md and README.md.
That's what I'm doing, FWIW. It's made easier by the fact that the
traditional names are generic and without file extension. As long as
documentation is phrased like 'the NEWS file' and not 'the file named
NEWS', I have no difficulty in treating NEWS.md as an instance of a NEWS
file. Same way I interpret 'the README file' as variably applying to
one of README, README.md, readme.txt, ..., or even README-hacking
depending on context.
--
Basil
