Repository navigation
Add a clean-wording goal, and regenerate the wording with specgen 0.41.1 - #117
Open
steve-downey wants to merge 3 commits into
Open
steve-downey wants to merge 3 commits into
steve-downey wants to merge 3 commits into
Conversation
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.
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
make wordingcompares 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 wordingis no way round that:.DEFAULThands every prerequisite that has no rule of its own, the headers and the makefile among them, to cmake as a target.clean-wordingdeletes the fragments,expected.tex, the*.root.texfiles and the depfile, somake clean-wording wordingwrites all of it again. Those files are checked in, so the goal refuses to run whenspecgenis not found, and neithercleannorrealcleandepends on it.papers/wording/README.mddescribes 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:
&,{and}are escaped inside\tcode;itemdescr;error()overloads that share a Returns element are each stated as oneitemdecl.With 0.41.1 the synopses change, and are 607 lines shorter:
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;= delete;, in place ofBEMAN_EXPECTED_DELETE_MSGand its message in the synopses (25) and added to the item declarations (16);unex,valanderror-value-typein authored code spans render as exposition-only names.Apart from those names the prose is unchanged.
Test plan
make clean-wording wordingregenerates everything, and a secondmake wordinghas nothing to domake wording-checkpasses after regenerating; it failed beforemake clean-wording SPECGEN=no-such-specgenfails and deletes nothingitemdescrlines, leaves only rewrapped lines and the mergederror()declarationsexpected.texis the same token for token once\exposid{name}is read asname; the code, with comments dropped, the macro tails read asdeleteandrequires-clauses removed from both, differs only by the 16= deleteadded to item declarationsD4280R0.texdoes not\inputthese fragments