Re: [PATCH 1/3] manual: Refactor header and standards annotations.

[Rical Jasan <ricaljasan at pacific dot net>]

On 11/23/2016 09:30 AM, Joseph Myers wrote:
> On Tue, 22 Nov 2016, Rical Jasan wrote:
> 
>> 	Multiple headers may be defined as long as they are all on the
>> 	second-to-last line, and not separated by commas.  Standards
>> 	are rendered free-form, so there is no need to refactor them
>> 	as long as they are present.
>>
>> 	Deviating from summary.awk, the header and standards
>> 	annotations must occur on the two lines immediately preceding
>> 	the item to be annotated (this simplifies future work and
>> 	doesn't change summary.awk's output).  Additionally, @comments
>> 	immediately preceding header and standards @comments are
>> 	disallowed (note that @c-comments are still valid).  The
>> 	latter requirement may not be essential once all annotations
>> 	are otherwise conforming, but it was useful as a heuristic for
>> 	finding ill-formatted annotations in the meantime, enforcing a
>> 	stricter syntax that is still summary.awk-compatible.
> 
> I think you should expand the comment in summary.awk that describes the 
> syntax to detail these more precise rules, and to say explicitly how to 
> indicate multiple headers or standards (or cases where the headers depend 
> on the standard?).  (Ideally of course summary.awk or some other script 
> run during the build would exit with error status if the more precise 
> rules aren't met, to ensure that new deviations don't creep in.)

This was going to be the topic of my question to the list, so I'm glad
you brought this up.  I realize it would be ideal to provide a script
(or rework summary.awk) to enforce syntax along with the changes, but I
withheld that work for several reasons.

First, I was going to ask if there was a preference for whether
summary.awk should be modified or if a new script was acceptable, and if
so which language.  To help make sense of things while working this out
I used a Perl script for a scratchpad, which I could clean up for
submission.  I could also write it in AWK.  If a new script was used for
syntax-checking, would you prefer it to take over the generation of
summary.texi?  The two functions are intrinsically related.

Second, I expect we'll move away from @comment-based annotations to
something more explicit/obvious, so I was avoiding enforcing a syntax
until we settle on one.  (Not that it's an argument against enforcing
now.)  For example, I'm already using new @vitem and @titem macros to
handle a couple corner cases (which a syntax-checker at this stage
wouldn't catch anyway), and am leaning towards empty macros to replace
the header and standards @comments.  There is also the issue of what
standards annotations will eventually look like (for which I'm grateful
for your comments on the other patch).

Third, the changes in this patchset merely take advantage of
summary.awk's behaviour.  The result is a more complete manual,
operating under the exact same paradigm it was before.  My idea was that
it improves the manual in its current state, so that if (worst case)
nothing else were to happen with this, that's OK, and things are better.
 Having nearly complete annotations, even using the current, unenforced
syntax, will also make future work on a real framework for headers and
standards easier, resulting in a strategic win-win.

Ultimately, though, I just really wanted to get the bulk of the new
material submitted sooner rather than later.  :)  This patchset
introduces a lot of new material to be reviewed (all new content being
in 3/3).  If you'd rather wait until there's a more comprehensive
proposal, I don't mind doing it that way either.

Rical