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

[Rical Jasan <ricaljasan at pacific dot net>]

On 11/30/2016 04:50 AM, Joseph Myers wrote:
> 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.)

I don't think that format will work well because the safety lines are
very long.  In PDF format, the line always wraps.  If we did want to do
that, I think we'd wrap the annotations in @multitable to get what we
want, but I haven't played with it.

A little off-topic, but the "Preliminary" field is completely unused, by
the way.  Compare:

$ grep -c '@prelim{}' manual/*.texi

to

$ grep -c '@prelim{[^}]+}' manual/*.texi

I hack my copy for regular use to get rid of it because "Preliminary: |
MT..." is annoying (specifically, the empty field following the colon
before the pipe separator for every single annotation, or the pipe
separator before anything to bother separating MT from, however you look
at it).  Even then, though, the line still wraps.

Back to the topic, I'm not sure that columns would take up less vertical
space than lines anyway.  If you gave safety half the table width (which
isn't even half the page width since the annotation is nested under the
function description), and it always takes two lines, it'd probably
require at least 3, maybe 4 lines, and I can't imagine it'd look very good.

If we're going to pay the 3-4 line price regardless, it'd probably be
easier to just give each thing its own line.  For example (getcwd):

Safety: MT-Safe | AS-Unsafe heap | AC-Unsafe mem fd | See Section
1.2.2.1 [POSIX Safety Concepts], page 2.
Standards: POSIX.1 (unistd.h), See Section 1.3.4 [Feature Test Macros],
page 15.
Added in: 2.0

As a general documentation standard, perhaps we'd use:

@(def|item)...
[@safety{...}] # required for @def*
@standards{...}
[@standards{...}]
@addedin{...}

We could also make @addedin{} an empty macro whose arguments were used
by an external script (like summary.awk) to add the information into the
entry in the Summary of Library Facilities, but not the full description
in the manual.  If people really want that info, though, it's probably
better to put it there (or in both places).

I can't say much about automated validation of Added In versions, as I'm
not familiar with the Versions files at all.

Rical