This is the mail archive of the
libc-alpha@sourceware.org
mailing list for the glibc project.
Re: [PATCH v2 3/5] manual: Add new header and standards annotations.
- From: Joseph Myers <joseph at codesourcery dot com>
- To: Rical Jasan <ricaljasan at pacific dot net>
- Cc: <libc-alpha at sourceware dot org>, <mtk dot manpages at gmail dot com>, <carlos at redhat dot com>
- Date: Wed, 8 Feb 2017 13:51:53 +0000
- Subject: Re: [PATCH v2 3/5] manual: Add new header and standards annotations.
- Authentication-results: sourceware.org; auth=none
- References: <20161206105525.21117-1-ricaljasan@pacific.net> <20161206105525.21117-4-ricaljasan@pacific.net> <alpine.DEB.2.20.1612071624470.23761@digraph.polyomino.org.uk> <665e49d4-dfa0-e14d-a793-d4acdca8e617@pacific.net> <alpine.DEB.2.20.1612081401130.3473@digraph.polyomino.org.uk> <7dd6da88-601f-e6f2-1f16-c24d7fdf84e2@pacific.net> <alpine.DEB.2.20.1612141818020.32751@digraph.polyomino.org.uk> <8c01ffc4-fcee-d584-bfab-d74a0b552b77@pacific.net> <8e8b0d56-b001-1870-1b5c-9895a1301c07@pacific.net> <alpine.DEB.2.20.1612151300180.15350@digraph.polyomino.org.uk> <0d5758f3-52bb-31cb-21e2-d218ace98065@pacific.net> <alpine.DEB.2.20.1702071639480.4464@digraph.polyomino.org.uk> <c0d3e284-cdae-26bf-bf91-3d9ff5d07289@pacific.net>
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