Skip to content

Add a clean-wording goal, and regenerate the wording with specgen 0.41.1 - #117

Open
steve-downey wants to merge 3 commits into
bemanproject:mainfrom
steve-downey:clean-wording-goal
Open

steve-downey wants to merge 3 commits into
bemanproject:mainfrom
steve-downey:clean-wording-goal

Conversation

@steve-downey

@steve-downey steve-downey commented Nov 16, 2026 •

Copy link
Copy Markdown
Member

Summary

  • make wording compares the generated fragments with the annotated headers. A new specgen renders the same headers differently without touching one, so make finds nothing to do and the checked-in wording stays as the old specgen wrote it. make -B wording is no way round that: .DEFAULT hands every prerequisite that has no rule of its own, the headers and the makefile among them, to cmake as a target.

  • clean-wording deletes the fragments, expected.tex, the *.root.tex files and the depfile, so make clean-wording wording writes all of it again. Those files are checked in, so the goal refuses to run when specgen is not found, and neither clean nor realclean depends on it. papers/wording/README.md describes it.

  • The second and third commits are the output of that command, with specgen 0.23.0 and then with 0.41.1. No header changed in either. They are separate because they differ in kind.

  • With 0.23.0 only the form changed. With whitespace ignored, the old and new fragments differ only in these ways:

    • a declaration following its template-head is indented, and long declarations, comments and string literals wrap at different points;
    • &, { and } are escaped inside \tcode;
    • class-level remarks and mandates are no longer wrapped in an itemdescr;
    • in [expected.un.obs], the two pairs of error() overloads that share a Returns element are each stated as one itemdecl.
  • With 0.41.1 the synopses change, and are 607 lines shorter:

    • a plain comment in a class body is no longer carried into the synopsis (194 comment lines, the banner comments among them);
    • a requires-clause that the item declaration states as Constraints is dropped from the synopsis too, and stays only on a deleted member that has no item of its own;
    • a deleted member reads = delete;, in place of BEMAN_EXPECTED_DELETE_MSG and its message in the synopses (25) and added to the item declarations (16);
    • unex, val and error-value-type in authored code spans render as exposition-only names.

    Apart from those names the prose is unchanged.

Test plan

  • make clean-wording wording regenerates everything, and a second make wording has nothing to do
  • make wording-check passes after regenerating; it failed before
  • make clean-wording SPECGEN=no-such-specgen fails and deletes nothing
  • 0.23.0: token-level comparison of each old and new fragment, after undoing the escapes and dropping the itemdescr lines, leaves only rewrapped lines and the merged error() declarations
  • 0.41.1: the prose of the old and new expected.tex is the same token for token once \exposid{name} is read as name; the code, with comments dropped, the macro tails read as delete and requires-clauses removed from both, differs only by the 16 = delete added to item declarations
  • The paper PDF was not rebuilt; D4280R0.tex does not \input these fragments

The wording rules compare the fragments with the annotated headers. A new
specgen renders the same headers differently without touching one, so make
finds nothing to do and the checked-in wording stays as the old specgen
wrote it. `make -B wording` does not help: .DEFAULT then hands every
prerequisite that has no rule of its own, the headers and the makefile
among them, to cmake as a target.

clean-wording deletes the fragments, expected.tex, the *.root.tex files and
the depfile, so that `make clean-wording wording` writes all of it again.
The fragments and expected.tex are checked in, so the goal refuses to run
when specgen is not found, and neither clean nor realclean depends on it.
The output of `make clean-wording wording`. No header changed, and no
wording changed either: with whitespace ignored, the old and new fragments
differ only in the ways listed here, all of them in how specgen renders
the same headers.

- A declaration following its template-head is indented, and long
  declarations, comments and string literals wrap at different points.
- `&`, `{` and `}` are escaped inside \tcode.
- Class-level remarks and mandates are no longer wrapped in an itemdescr.
- In [expected.un.obs], the two pairs of error() overloads that share a
  Returns element are each stated as one itemdecl.
No header changed. specgen 0.41.1 (9d1689d) renders the same docblocks
differently from 0.23.0 in four ways:

- A plain comment in a class body is no longer carried into the
  synopsis. 194 comment lines go, the banner comments among them, since
  none is written as a `// \ref{...}` group header.
- A requires-clause that the item declaration states as Constraints is
  dropped from the synopsis too. It stays on a deleted member that has
  no item of its own.
- A deleted member reads `= delete;`. In the synopses that replaces
  BEMAN_EXPECTED_DELETE_MSG and its message, 25 times; in the item
  declarations, which showed no tail, it is added 16 times.
- An exposition-only name in an authored code span renders as one:
  `unex`, `val` and `error-value-type` are \exposid where they were
  plain code.

Apart from those names the prose is the same, token for token.
@steve-downey steve-downey changed the title Add a clean-wording goal, and regenerate the wording with specgen 0.23.0 Add a clean-wording goal, and regenerate the wording with specgen 0.41.1 Nov 17, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant