Re: [PATCH v2 3/5] manual: Add new header and standards annotations.

[Joseph Myers <joseph@codesourcery.com>]

On Wed, 8 Feb 2017, Rical Jasan wrote:

> I'd envision a v3 containing patches for:
> 
>   1. Introducing the @standards and related macros.
>   2. Script(s) to generate the Summary and check annotations.
>   3. Adding and converting annotations.

I think any conversion to @standards should have the following property: 
there is a patch that changes all existing comment-based annotations to 
@standards-based annotations, leaving the generated summary and the whole 
of the formatted manuals unchanged after the patch.  That patch should 
contain a small manually written patch (adapting the summary-generation 
script to read @standards instead of comments, adding dummy definitions of 
@standards macros), a script that does the conversion (which of course 
wouldn't be committed, just the results of running it would be), and a 
large purely automatically generated set of changes made by the conversion 
script.

That is, there must not be an "Adding and converting annotations." patch; 
the automated conversion must be clearly separated from any patch that 
actually changes or adds any annotations to the manual.  (This does not 
assert whether such changes and additions happen before or after the 
conversion.)

-- 
Joseph S. Myers
joseph@codesourcery.com