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

[Joseph Myers <joseph at codesourcery dot com>]

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.)

-- 
Joseph S. Myers
joseph@codesourcery.com