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

[Joseph Myers <joseph@codesourcery.com>]

On Wed, 30 Nov 2016, Florian Weimer wrote:

> Many programmers would also find annotations which glibc version introduced a
> particular functionality *extremely* useful, especially for functions that
> were added after glibc 2.5 or so.  It's not a standard as such (but LSB would
> be), but I think it serves a similar purpose.
> 
> Can we reconsider adding this kind of information to the manual?

That seems reasonable (given appropriate automatic checks - that the 
version documented for a function is the same as the oldest symbol version 
with that function in any Versions file, I suppose, which would also be a 
way of populating such annotations for functions though not for 
non-function interfaces, as long as you don't care about distinguishing 
versions before 2.1).

In HTML and PDF manuals it might be nice (and more compact) if things 
looked like:

----------------------------- ---------------------- -----------
|Safety (preliminary):      | |Standards:          | |Added in:|
|MT-Safe | AS-Safe | AC-Safe| |POSIX.1 (unistd.h)  | |2.4      |
----------------------------- ---------------------- -----------

with a series of boxes that can go next to each other rather than taking a 
lot of vertical space (and with "Safety" and "Standards" being links to 
the relevant manual sections).  I don't know if this can be achieved with 
different macro definitions for different output formats (and it's not 
something to require for the first version of standards annotations, 
anyway).  (There are also issues of what it should look like when you have 
long standard descriptions, etc.)

-- 
Joseph S. Myers
joseph@codesourcery.com