diff mbox

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

Message ID 20161123063807.14845-4-ricaljasan@pacific.net
State Superseded
Headers show

Commit Message

Rical Jasan Nov. 23, 2016, 6:38 a.m. UTC 
manual: Add new header and standards annotations.

	This commit completes header and standard annotations for all
	@def*-commands and @vtable @items.

	The header annotations are believed to all be correct, as the
	various definitions/declarations had to found in a header.

	The standards annotations are a best-effort.  They are roughly
	derived from the following strategy:

    	  1) Use the feature test macro if wrapped in a #if.
    	  2) Obvious context, including:
    	   a) top of file says, e.g., "ISO C99 ..."
    	   b) manual annotates other nearby, related entries
    	   c) manual describes section as per a given standard

	The "???" placeholder is used for anything not obvious from a
	cursory survey of the glibc sources.

	The choice of standards nomenclature is not meant to establish
	any sort of convention.

	In the Summary of Library Facilities, this commit adds roughly
	380 new entries, and fixes a few others.

	* manual/argp.texi: Complete header and standards annotations.
	* manual/arith.texi: Likewise.
	* manual/creature.texi: Likewise.
	* manual/filesys.texi: Likewise.
	* manual/ipc.texi: Likewise.
	* manual/lang.texi: Likewise.
	* manual/llio.texi: Likewise.
	* manual/locale.texi: Likewise.
	* manual/math.texi: Likewise.
	* manual/memory.texi: Likewise.
	* manual/message.texi: Likewise.
	* manual/nss.texi: Likewise.
	* manual/pattern.texi: Likewise.
	* manual/platform.texi: Likewise.
	* manual/process.texi: Likewise.
	* manual/resource.texi: Likewise.
	* manual/search.texi: Likewise.
	* manual/signal.texi: Likewise.
	* manual/socket.texi: Likewise.
	* manual/stdio.texi: Likewise.
	* manual/sysinfo.texi: Likewise.
	* manual/syslog.texi: Likewise.
	* manual/terminal.texi: Likewise.
	* manual/time.texi: Likewise.
	* manual/users.texi: Likewise.
---
 manual/argp.texi     |  28 +++++++++
 manual/arith.texi    |  28 +++++++++
 manual/creature.texi |   2 +
 manual/filesys.texi  |  44 ++++++++++++++
 manual/ipc.texi      |  28 +++++++++
 manual/lang.texi     |  20 +++++++
 manual/llio.texi     |  82 +++++++++++++++++++++++++
 manual/locale.texi   | 166 +++++++++++++++++++++++++++++++++++++++++++++++++++
 manual/math.texi     |  26 ++++++++
 manual/memory.texi   |  25 ++++++++
 manual/message.texi  |   4 ++
 manual/nss.texi      |   8 +++
 manual/pattern.texi  |  36 +++++++++++
 manual/platform.texi |  20 +++++++
 manual/process.texi  |   8 +++
 manual/resource.texi |  27 +++++++++
 manual/search.texi   |  12 ++++
 manual/signal.texi   |  12 ++++
 manual/socket.texi   |   3 +
 manual/startup.texi  |   2 +
 manual/stdio.texi    |  52 ++++++++++++++++
 manual/string.texi   |   2 +
 manual/sysinfo.texi  |  50 ++++++++++++++++
 manual/syslog.texi   |  64 ++++++++++++++++++++
 manual/terminal.texi |  14 +++++
 manual/time.texi     |   6 ++
 manual/users.texi    |   8 +++
 27 files changed, 777 insertions(+)

Comments

Joseph Myers Nov. 23, 2016, 5:42 p.m. UTC | #1 
On Tue, 22 Nov 2016, Rical Jasan wrote:

> 	The "???" placeholder is used for anything not obvious from a

> 	cursory survey of the glibc sources.


All argp facilities should be documented as GNU.  Likewise mcheck.h 
features.  Likewise getauxval.

The correct standard for posix_fallocate64 is LFS (well, really the 
combination of both LFS and POSIX.1-2001 enabled, however you denote 
POSIX.1-2001 && LFS).

XOPEN2K is generically an unhelpful name.  In the headers it actually 
means POSIX.1-2001; the X/Open version is __USE_XOPEN2KXSI.  Likewise 
__USE_XOPEN2K8 means POSIX.1-2008 and the X/Open version is 
__USE_XOPEN2K8XSI.  So anywhere you say XOPEN2K because the headers use 
__USE_XOPEN2K, say POSIX.1-2001 in the manual instead; likewise 
POSIX.1-2008 for XOPEN2K8.

strncpy is in ISO C90, one of several standards all commonly shown as 
"ISO" (though I think "C90", "C99", "C11", "TS 18661-1:2014" etc. might be 
better names to use - as always, only listing the oldest standard 
relevant, not later ones that are generally supersets of it).  In stdio.h, 
SEEK_SET, SEEK_CUR, SEEK_END are all likewise C90.

-- 
Joseph S. Myers
joseph@codesourcery.com
Rical Jasan Nov. 24, 2016, 10:22 a.m. UTC | #2 
On 11/23/2016 09:42 AM, Joseph Myers wrote:
> On Tue, 22 Nov 2016, Rical Jasan wrote:

> 

>> 	The "???" placeholder is used for anything not obvious from a

>> 	cursory survey of the glibc sources.

> 

> All argp facilities should be documented as GNU.  Likewise mcheck.h 

> features.  Likewise getauxval.


Thank you!

> The correct standard for posix_fallocate64 is LFS (well, really the 

> combination of both LFS and POSIX.1-2001 enabled, however you denote 

> POSIX.1-2001 && LFS).


OK.

> XOPEN2K is generically an unhelpful name.  In the headers it actually 

> means POSIX.1-2001; the X/Open version is __USE_XOPEN2KXSI.  Likewise 

> __USE_XOPEN2K8 means POSIX.1-2008 and the X/Open version is 

> __USE_XOPEN2K8XSI.  So anywhere you say XOPEN2K because the headers use 

> __USE_XOPEN2K, say POSIX.1-2001 in the manual instead; likewise 

> POSIX.1-2008 for XOPEN2K8.


I'm glad you mention this.  Have you seen the related discussion on
libc-help? [1]  I'm interested in your thoughts on converting standards
to feature test macros (or vice versa).

Also, if we want long-form standards in the manual, where would we put
the feature test macros?  It seems more appropriate to document the
feature test macros in the Summary, and the current framework uses the
standard @comment verbatim there.  (There is also the issue that, e.g.,
XOPEN2K or _USE_XOPEN2K aren't the actual feature test macros one would
even use...)

> strncpy is in ISO C90, one of several standards all commonly shown as 

> "ISO" (though I think "C90", "C99", "C11", "TS 18661-1:2014" etc. might be 

> better names to use - as always, only listing the oldest standard 

> relevant, not later ones that are generally supersets of it).  In stdio.h, 

> SEEK_SET, SEEK_CUR, SEEK_END are all likewise C90.


OK, thank you.

I'll fix these up and wait for other comments.

Rical

[1] https://sourceware.org/ml/libc-help/2016-10/msg00014.html
Joseph Myers Nov. 24, 2016, 1:37 p.m. UTC | #3 
On Thu, 24 Nov 2016, Rical Jasan wrote:

> > XOPEN2K is generically an unhelpful name.  In the headers it actually 

> > means POSIX.1-2001; the X/Open version is __USE_XOPEN2KXSI.  Likewise 

> > __USE_XOPEN2K8 means POSIX.1-2008 and the X/Open version is 

> > __USE_XOPEN2K8XSI.  So anywhere you say XOPEN2K because the headers use 

> > __USE_XOPEN2K, say POSIX.1-2001 in the manual instead; likewise 

> > POSIX.1-2008 for XOPEN2K8.

> 

> I'm glad you mention this.  Have you seen the related discussion on

> libc-help? [1]  I'm interested in your thoughts on converting standards

> to feature test macros (or vice versa).


I'm not on libc-help.  libc-help is for user questions.  It's not an 
appropriate place for development discussions and is not relevant to 
establishing consensus on development directions.

> Also, if we want long-form standards in the manual, where would we put

> the feature test macros?  It seems more appropriate to document the

> feature test macros in the Summary, and the current framework uses the

> standard @comment verbatim there.  (There is also the issue that, e.g.,

> XOPEN2K or _USE_XOPEN2K aren't the actual feature test macros one would

> even use...)


My assumption is that creature.texi (which is very out of date regarding 
what's enabled by default, values of _POSIX_C_SOURCE, etc.) would, where 
it describes support for a standard and any associated feature test 
macros, say something like: "Functions enabled with this feature test 
macro / from this standard are listed as POSIX.1-2008 in <summary>.".  
Where <summary> could be a link to the existing summary.  Or it could say 
"in the Standards information in the individual function description", if 
we use macros to generate explicit Standards information in each function 
description alongside the Safety information.  Or both.

That is, creature.texi would explain the notation just like intro.texi has 
an explanation of the safety annotations.  The summary currently says "the 
standard or other source from which each facility is derived", not "the 
feature test macro".

There's an open question of whether we wish to continue to document BSD / 
SVID / ... sources not corresponding to feature test macros, or just make 
the annotations say MISC or DEFAULT and leave information about BSD etc. 
origins to free-text descriptions.

As for names corresponding to standards / feature test macros, I suggest 
one possibility:

C90 (everything is a superset of this apart from gets obsoletion)
C95
C99
C11
  (note that these four are normally selected with -std, not with feature 
   test macros, though glibc has _ISOC99_SOURCE and _ISOC11_SOURCE)
TR 27431-2:2010
TS 18661-1:2014
TS 18661-4:2015
POSIX.1 (= 1990 edition)
POSIX.2
POSIX.1-1993
POSIX.1-1995
POSIX.1-2001
XSI POSIX.1-2001
POSIX.1-2008
XSI POSIX.1-2008
DEFAULT
GNU
XOPEN (= __USE_XOPEN; listed as XPG3 in conform/ tests; corresponds to 
       functions in C435 that are not UX-shaded)
XPG4 (= __USE_XOPEN_EXTENDED; corresponds to everything in C435)
UNIX98
LFS (= __USE_LARGEFILE64, i.e. *64 functions)

(which doesn't cover _LARGEFILE_SOURCE / _ATFILE_SOURCE / _REENTRANT, but 
should be enough anyway to provide a sufficient indication of where 
functions come from, at least if you can handle "standard 1 || standard 
2", "standard 1 && ! standard 2", or similar).

-- 
Joseph S. Myers
joseph@codesourcery.com
Rical Jasan Nov. 25, 2016, 5:59 a.m. UTC | #4 
On 11/24/2016 05:37 AM, Joseph Myers wrote:
> On Thu, 24 Nov 2016, Rical Jasan wrote:

> 

>>> XOPEN2K is generically an unhelpful name.  In the headers it actually 

>>> means POSIX.1-2001; the X/Open version is __USE_XOPEN2KXSI.  Likewise 

>>> __USE_XOPEN2K8 means POSIX.1-2008 and the X/Open version is 

>>> __USE_XOPEN2K8XSI.  So anywhere you say XOPEN2K because the headers use 

>>> __USE_XOPEN2K, say POSIX.1-2001 in the manual instead; likewise 

>>> POSIX.1-2008 for XOPEN2K8.

>>

>> I'm glad you mention this.  Have you seen the related discussion on

>> libc-help? [1]  I'm interested in your thoughts on converting standards

>> to feature test macros (or vice versa).

> 

> I'm not on libc-help.  libc-help is for user questions.  It's not an 

> appropriate place for development discussions and is not relevant to 

> establishing consensus on development directions.


Duly noted.

>> Also, if we want long-form standards in the manual, where would we put

>> the feature test macros?  It seems more appropriate to document the

>> feature test macros in the Summary, and the current framework uses the

>> standard @comment verbatim there.  (There is also the issue that, e.g.,

>> XOPEN2K or _USE_XOPEN2K aren't the actual feature test macros one would

>> even use...)

> 

> My assumption is that creature.texi (which is very out of date regarding 

> what's enabled by default, values of _POSIX_C_SOURCE, etc.) would, where 

> it describes support for a standard and any associated feature test 

> macros, say something like: "Functions enabled with this feature test 

> macro / from this standard are listed as POSIX.1-2008 in <summary>.".  

> Where <summary> could be a link to the existing summary.  Or it could say 

> "in the Standards information in the individual function description", if 

> we use macros to generate explicit Standards information in each function 

> description alongside the Safety information.  Or both.

> 

> That is, creature.texi would explain the notation just like intro.texi has 

> an explanation of the safety annotations.  The summary currently says "the 

> standard or other source from which each facility is derived", not "the 

> feature test macro".


I'd like to see the Summary (of Library Facilities) have the header and
feature test macros, since it's something of a quick reference.  For
functions, you get to see the API, and for everything, which header it
comes from and what FTM you need (and what it should be defined to is
also a worthy goal, I think).  So we would have entries like:

int foo (struct bar *bp, size_t len)
  fubar.h (_POSIX_C_SOURCE >= 200809L): <reference/link>

or:

char *program_invocation_short_name
  errno.h (_GNU_SOURCE): <reference/link>

creature.texi could just be updated, but I don't think it needs to link
anywhere, otherwise it would be referencing everything that used it,
wouldn't it?  I may be misunderstanding what you meant by "<summary>"
above.  Generally, I would expect anything talking about feature test
macros to link back there, for detailed information.

One question I have is how are standards annotations embedded in the
manual going to look?  Currently, where I showed the FTMs in the
Summary, the standard @comment is used verbatim.

The evolution I see the annotations taking is moving from @comments to
something like @headers{} and @standards{}.  If we use "POSIX.1-2008",
we could assume "_POSIX_C_SOURCE >= 200809L", but expressions become
difficult.  I've considered having both @ftms{} and @standards{}, but
I'm also hoping for a solution that can benefit the manpages as well,
which would involve some kind of translation between the two (standards
and FTMs).

Consider:

@comment fnmatch.h
@comment GNU
@item FNM_CASEFOLD

which results in:

FNM_CASEFOLD
  fnmatch.h (GNU): <reference/link>

This could be:

@headers{fnmatch.h}
@standards{GNU}
@item FNM_CASEFOLD

but here is the conditional in fnmatch.h:

#if !defined _POSIX_C_SOURCE || _POSIX_C_SOURCE < 2 || defined _GNU_SOURCE

I'm not sure we can translate "GNU" to that, which means accurate
documentation of FTMs from standards names isn't possible.
Acknowledging the fact there is no way to automatically keep this
information up-to-date, we could document both:

@headers{fnmatch.h}
@standards{GNU}
@ftms{!_POSIX_C_SOURCE || _POSIX_C_SOURCE < 2 || _GNU_SOURCE}
@item FNM_CASEFOLD

Then there is also the question of whether we would like to move any of
those annotations into the textual description below.

> There's an open question of whether we wish to continue to document BSD / 

> SVID / ... sources not corresponding to feature test macros, or just make 

> the annotations say MISC or DEFAULT and leave information about BSD etc. 

> origins to free-text descriptions.


I had a question of header context I think is related to this.
Sometimes a function is annotated as being per a given standard, but
doesn't appear conditional on anything in the header.  I would have
assumed MISC or DEFAULT were implied, but sometimes things check
explicitly for MISC.  If MISC is still something to test for, what do we
assume is defined when there are no tests within a header?

> As for names corresponding to standards / feature test macros, I suggest 

> one possibility:

> 

> C90 (everything is a superset of this apart from gets obsoletion)

> C95

> C99

> C11

>   (note that these four are normally selected with -std, not with feature 

>    test macros, though glibc has _ISOC99_SOURCE and _ISOC11_SOURCE)


So if we were to document FTMs, would these look like "-std=c99",
instead of "_ISOC99_SOURCE"?  And how to document "C95", which doesn't
have an "_ISOC95_SOURCE" or "-std=c95" (in my gcc(1))?

> TR 27431-2:2010

> TS 18661-1:2014

> TS 18661-4:2015

> POSIX.1 (= 1990 edition)

> POSIX.2

> POSIX.1-1993

> POSIX.1-1995

> POSIX.1-2001

> XSI POSIX.1-2001

> POSIX.1-2008

> XSI POSIX.1-2008

> DEFAULT

> GNU

> XOPEN (= __USE_XOPEN; listed as XPG3 in conform/ tests; corresponds to 

>        functions in C435 that are not UX-shaded)

> XPG4 (= __USE_XOPEN_EXTENDED; corresponds to everything in C435)

> UNIX98

> LFS (= __USE_LARGEFILE64, i.e. *64 functions)

> 

> (which doesn't cover _LARGEFILE_SOURCE / _ATFILE_SOURCE / _REENTRANT, but 

> should be enough anyway to provide a sufficient indication of where 

> functions come from, at least if you can handle "standard 1 || standard 

> 2", "standard 1 && ! standard 2", or similar).


Even if we were to accept textual standards, the combining expressions
are wont to get ugly, and we would have to parse the logic into a nicely
formatted sentence, which is the main reason I considered @ftm{} in
addition to @standards{}.

I would like to know how everybody feels about adding automated snippets
to the documentation.  The header and standards @comments aren't
currently rendered in the manual in any way, aside from inclusion in the
Summary of Library Facilities.  Would we like to see a standardized
layout, by mimicking the @safety{} framework?

Rical
Rical Jasan Nov. 25, 2016, 7:36 a.m. UTC | #5 
On 11/23/2016 09:42 AM, Joseph Myers wrote:
> In stdio.h, 

> SEEK_SET, SEEK_CUR, SEEK_END are all likewise C90.


What about the other 2 headers?  I had:

@comment stdio.h unistd.h fcntl.h
@comment ISOC99, POSIX, XOPEN || XOPEN2K8

Do you want:

@comment stdio.h unistd.h fcntl.h
@comment C90, POSIX, XOPEN || POSIX.1-2008

Rical
Joseph Myers Nov. 25, 2016, 2:53 p.m. UTC | #6 
On Fri, 25 Nov 2016, Rical Jasan wrote:

> creature.texi could just be updated, but I don't think it needs to link

> anywhere, otherwise it would be referencing everything that used it,

> wouldn't it?  I may be misunderstanding what you meant by "<summary>"

> above.  Generally, I would expect anything talking about feature test

> macros to link back there, for detailed information.


What I mean is e.g. in creature.texi:

Functions from this standard are listed as POSIX.1-2008 in @ref{Summary of 
Library Facilities}.

Or:

Functions from this standard are listed as POSIX.1-2008 in @ref{Summary of
Library Facilities}, and in the Standards information in the individual 
function description.

(Or maybe use quotes, ``POSIX.1-2008'', in this text.)

Where the function description would then have:

Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety 
Concepts::.

Standards: POSIX.1-2008 (unistd.h). *Note Feature Test Macros::.

> One question I have is how are standards annotations embedded in the

> manual going to look?  Currently, where I showed the FTMs in the

> Summary, the standard @comment is used verbatim.

> 

> The evolution I see the annotations taking is moving from @comments to

> something like @headers{} and @standards{}.  If we use "POSIX.1-2008",


I'd imagine a macro taking both header and standard arguments, so multiple 
instances of it can be used in the case where there are different headers, 
with different standards associated.

I'd also imagine that the macro goes inside the body of the definition of 
the relevant functions etc., so that only one instance is needed where you 
have

@deffoo fun
@deffoox fun2
@deffoox fun3
@standards{POSIX.1-2008, unistd.h}

for all functions in the same standard / header.  And a macro variant that 
also takes the name / names of functions, for cases where there is a group 
documented together, some in different standards from others (e.g.

@deftypefun double log (double @var{x})
@deftypefunx float logf (float @var{x})
@deftypefunx {long double} logl (long double @var{x})
@fstandards{log, C90, math.h}
@fstandards{logf logl, C99, math.h}

which might expand to:

Standards (log): C90 (math.h). *Note Feature Test Macros::.
Standards (logf logl): C99 (math.h). *Note Feature Test Macros::.

This is illustrative of the sort of thing I'd hope to see in the manual, 
not a precise recipe for what the macros should look like.

> but here is the conditional in fnmatch.h:

> 

> #if !defined _POSIX_C_SOURCE || _POSIX_C_SOURCE < 2 || defined _GNU_SOURCE


This conditional is fundamentally broken in glibc terms.  It would have 
the effect that if you include this header first (with no feature test 
macros defined) then the declaration is present, but if you include other 
headers first then it isn't (because features.h defines _POSIX_C_SOURCE to 
200809L by default).

Any such fundamentally broken conditionals should not be used as a basis 
for designing documentation infrastructure.  Rather, the header should be 
fixed so that in glibc it includes <features.h> and has glibc-appropriate 
conditionals.  That may require coordination with gnulib.

The intent seems to be to define GNU extensions unless a standard based on 
POSIX.2 is explicitly selected.  That's not in conformance with glibc 
conventions either.  What would be similar and in conformance is a 
conditional on __USE_MISC, however (i.e. an extension enabled by default, 
as it is if you include this header first).  Or just __USE_GNU (the 
approximate effect if this header is not included first).

> I had a question of header context I think is related to this.

> Sometimes a function is annotated as being per a given standard, but

> doesn't appear conditional on anything in the header.  I would have

> assumed MISC or DEFAULT were implied, but sometimes things check

> explicitly for MISC.  If MISC is still something to test for, what do we

> assume is defined when there are no tests within a header?


Standard names are strictly more expressive than feature test macros 
because they cover the case where a function was present in the first 
standard that defined a given header.

For example, unistd.h comes from POSIX.1-1990.  So any function that is 
declared in unistd.h unconditionally should be listed as POSIX.1-1990.  
That is completely separate from MISC, which is for *nonstandard* 
functions that are declared in the absence of feature test macros (or for 
XSI functions declared in the absence of feature test macros, since the 
default standards don't include XSI; MISC tests should never be combined 
with tests for non-XSI POSIX, as they are redundant in that case).

As another example: error and signal numbers are defined unconditionally 
in the headers, but are mostly not in C90.  You can document the standards 
individual numbers are defined in, which gives portability information 
beyond what "no feature test macro needed with glibc" would give.

> So if we were to document FTMs, would these look like "-std=c99",

> instead of "_ISOC99_SOURCE"?  And how to document "C95", which doesn't

> have an "_ISOC95_SOURCE" or "-std=c95" (in my gcc(1))?


I don't think you should document feature test macros (certainly not 
without a very careful review that the conditionals actually make sense).  
As noted, these standards don't have feature test macros.  I don't think 
listing compiler options for individual functions is appropriate either.  
Most people reading the manual don't want to use feature test macros at 
all for functions declared by default, and if they want to use feature 
test macros for other functions _GNU_SOURCE will probably suffice.  
Documenting the standards provides sufficient information for people 
concerned about portability or about when the functions are declared.

You use -std=iso9899:199409 for C95 (it was published 1995-04-01; 199409 
is the version from __STDC_VERSION__).

Note that each POSIX version is based on some ISO C version.  So for 
POSIX.1-2008 appropriate options are actually -std=c99 
-D_POSIX_C_SOURCE=200809L.

> Even if we were to accept textual standards, the combining expressions

> are wont to get ugly, and we would have to parse the logic into a nicely

> formatted sentence, which is the main reason I considered @ftm{} in

> addition to @standards{}.


I wouldn't anticipate sentences, just Standards: whatever as above.

-- 
Joseph S. Myers
joseph@codesourcery.com
Joseph Myers Nov. 25, 2016, 3:09 p.m. UTC | #7 
On Fri, 25 Nov 2016, Joseph Myers wrote:

> I don't think you should document feature test macros (certainly not 

> without a very careful review that the conditionals actually make sense).  


To give more rationale here:

Documentation should be for stable interfaces, not for implementation 
details.  The fact that something is part of a given standard is a stable 
interface.  The fact that something is declared under certain conditions 
may not be a stable interface, if for example it's an implementation 
detail that header X includes header Y (where the standards permit but 
don't require this) or defines type foo_t rather than using __foo_t.  
Effectively, the API to document for a header is a subset of what it 
actually exposes at any given time.  (Every public symbol should be 
documented somewhere in the manual, but not necessarily for every header 
or feature test macro that actually exposes that symbol.)

-- 
Joseph S. Myers
joseph@codesourcery.com
Joseph Myers Nov. 25, 2016, 4:16 p.m. UTC | #8 
On Fri, 25 Nov 2016, Rical Jasan wrote:

> On 11/23/2016 09:42 AM, Joseph Myers wrote:

> > In stdio.h, 

> > SEEK_SET, SEEK_CUR, SEEK_END are all likewise C90.

> 

> What about the other 2 headers?  I had:

> 

> @comment stdio.h unistd.h fcntl.h

> @comment ISOC99, POSIX, XOPEN || XOPEN2K8

> 

> Do you want:

> 

> @comment stdio.h unistd.h fcntl.h

> @comment C90, POSIX, XOPEN || POSIX.1-2008


Well, I'd like that comment in summary.awk saying what the intended syntax 
actually is in the case of multiple headers (how the standards are to be 
matched to the headers).  But:

For stdio.h it's C90.

For unistd.h it's POSIX.1 (i.e. 1990 edition, in the list I gave of 
possible notation for standards).

For fcntl.h it's XOPEN || POSIX.1-2008.

So if comma-separated standards correspond to space-separated headers, 
it's as you say except for my proposed notation saying POSIX.1 for the 
1990 edition.

-- 
Joseph S. Myers
joseph@codesourcery.com
Rical Jasan Nov. 30, 2016, 10:39 a.m. UTC | #9 
On 11/25/2016 06:53 AM, Joseph Myers wrote:
> On Fri, 25 Nov 2016, Rical Jasan wrote:

> 

>> creature.texi could just be updated, but I don't think it needs to link

>> anywhere, otherwise it would be referencing everything that used it,

>> wouldn't it?  I may be misunderstanding what you meant by "<summary>"

>> above.  Generally, I would expect anything talking about feature test

>> macros to link back there, for detailed information.

> 

> What I mean is e.g. in creature.texi:

> 

> Functions from this standard are listed as POSIX.1-2008 in @ref{Summary of 

> Library Facilities}.

> 

> Or:

> 

> Functions from this standard are listed as POSIX.1-2008 in @ref{Summary of

> Library Facilities}, and in the Standards information in the individual 

> function description.

> 

> (Or maybe use quotes, ``POSIX.1-2008'', in this text.)

> 

> Where the function description would then have:

> 

> Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety 

> Concepts::.

> 

> Standards: POSIX.1-2008 (unistd.h). *Note Feature Test Macros::.


I like this.  This is one of the avenues I was going to suggest, though
I wasn't sure how amenable everybody would be to more boilerplate in
*every single* description.

Don't forget that standards annotations aren't only for functions.
Variables, macros, and types, even down to structs and their members can
all have standards annotations, so they're going to show up all over the
place.

I think the only place I found struct members worth annotating was in
glob_t, by the way, since there are GNU extensions, but there is a case
for it; generally I only annotated structs and not their members.  Case
in point, though, there are exceptions to everything.  Even after this
patchset, there are still a few things deserving annotation that aren't
(but they aren't detectable as such, so they're omitted).  Dealing with
those cases requires either significant reworking of the text or
additional macros (I used @vitem and @titem myself, which were very
useful, but I didn't want to introduce new macros in this patchset, and
there was only one case for each anyway).

>> One question I have is how are standards annotations embedded in the

>> manual going to look?  Currently, where I showed the FTMs in the

>> Summary, the standard @comment is used verbatim.

>>

>> The evolution I see the annotations taking is moving from @comments to

>> something like @headers{} and @standards{}.  If we use "POSIX.1-2008",

> 

> I'd imagine a macro taking both header and standard arguments, so multiple 

> instances of it can be used in the case where there are different headers, 

> with different standards associated.


That makes sense.  Your response to my question about header context
below helps here too.  I had been so focused on the functions, types,
etc., that I missed the obvious fact headers themselves are parts of the
standards too.

> I'd also imagine that the macro goes inside the body of the definition of 

> the relevant functions etc., so that only one instance is needed where you 

> have

> 

> @deffoo fun

> @deffoox fun2

> @deffoox fun3

> @standards{POSIX.1-2008, unistd.h}


If we're going to render it in the manual's text, as part of foo's
description, that's the only way.

> for all functions in the same standard / header.  And a macro variant that 

> also takes the name / names of functions, for cases where there is a group 

> documented together, some in different standards from others (e.g.

> 

> @deftypefun double log (double @var{x})

> @deftypefunx float logf (float @var{x})

> @deftypefunx {long double} logl (long double @var{x})

> @fstandards{log, C90, math.h}

> @fstandards{logf logl, C99, math.h}


What about @standardsx??  It's like, convention!  ;)

> which might expand to:

> 

> Standards (log): C90 (math.h). *Note Feature Test Macros::.

> Standards (logf logl): C99 (math.h). *Note Feature Test Macros::.

> 

> This is illustrative of the sort of thing I'd hope to see in the manual, 

> not a precise recipe for what the macros should look like.


I think it looks pretty good, honestly.  I had played with the idea a
bit, but wasn't combining the headers and standards, which I think makes
this work.  I'll probably use this approach when I start on the
conversion and see what crazy sorts of special cases crop up.  Like...

>> but here is the conditional in fnmatch.h:

>>

>> #if !defined _POSIX_C_SOURCE || _POSIX_C_SOURCE < 2 || defined _GNU_SOURCE

> 

> This conditional is fundamentally broken in glibc terms.  It would have 


I'm glad this should have given me pause, then, because it did.

<...>

> Any such fundamentally broken conditionals should not be used as a basis 

> for designing documentation infrastructure.  Rather, the header should be 

> fixed so that in glibc it includes <features.h> and has glibc-appropriate 

> conditionals.  That may require coordination with gnulib.


<...>

>> I had a question of header context I think is related to this.

>> Sometimes a function is annotated as being per a given standard, but

>> doesn't appear conditional on anything in the header.  I would have

>> assumed MISC or DEFAULT were implied, but sometimes things check

>> explicitly for MISC.  If MISC is still something to test for, what do we

>> assume is defined when there are no tests within a header?

> 

> Standard names are strictly more expressive than feature test macros 

> because they cover the case where a function was present in the first 

> standard that defined a given header.

> 

> For example, unistd.h comes from POSIX.1-1990.  So any function that is 

> declared in unistd.h unconditionally should be listed as POSIX.1-1990.  


I get this, but..

> That is completely separate from MISC, which is for *nonstandard* 

> functions that are declared in the absence of feature test macros (or for 

> XSI functions declared in the absence of feature test macros, since the 

> default standards don't include XSI; MISC tests should never be combined 

> with tests for non-XSI POSIX, as they are redundant in that case).


I don't think I'm completely following this.  Is this a redundant test,
then:

./math/bits/math-finite.h:#if defined __USE_MISC && defined __USE_ISOC99

My practical question is, if MISC is nonstandard, what would we document
in @standards?  Just MISC?  I see it replaces deprecated feature test
macros _BSD_SOURCE and _SVID_SOURCE (or rather _DEFAULT_SOURCE does,
which is the only thing that sets __USE_MISC).  Would we not want to
document that something came from BSD, for example?  (Also see comment
below about handling deprecation.)

> As another example: error and signal numbers are defined unconditionally 

> in the headers, but are mostly not in C90.  You can document the standards 

> individual numbers are defined in, which gives portability information 

> beyond what "no feature test macro needed with glibc" would give.

> 

>> So if we were to document FTMs, would these look like "-std=c99",

>> instead of "_ISOC99_SOURCE"?  And how to document "C95", which doesn't

>> have an "_ISOC95_SOURCE" or "-std=c95" (in my gcc(1))?

> 

> I don't think you should document feature test macros (certainly not 

> without a very careful review that the conditionals actually make sense).  

> As noted, these standards don't have feature test macros.  I don't think 

> listing compiler options for individual functions is appropriate either.  

> Most people reading the manual don't want to use feature test macros at 

> all for functions declared by default, and if they want to use feature 

> test macros for other functions _GNU_SOURCE will probably suffice.  

> Documenting the standards provides sufficient information for people 

> concerned about portability or about when the functions are declared.


That could make things easier, I suppose.  I was using the conditionals
mainly as hints, for later work in more fully vetting the standards,
admittedly banking on the fact there seemed to be little to no
established convention for what was already present in the standard
@comments.

> You use -std=iso9899:199409 for C95 (it was published 1995-04-01; 199409 

> is the version from __STDC_VERSION__).

> 

> Note that each POSIX version is based on some ISO C version.  So for 

> POSIX.1-2008 appropriate options are actually -std=c99 

> -D_POSIX_C_SOURCE=200809L.


OK, thank you.

>> Even if we were to accept textual standards, the combining expressions

>> are wont to get ugly, and we would have to parse the logic into a nicely

>> formatted sentence, which is the main reason I considered @ftm{} in

>> addition to @standards{}.

> 

> I wouldn't anticipate sentences, just Standards: whatever as above.


What do you think about handling the common, "This function is a GNU
extension.", throughout the descriptions?  Would you remove those in
lieu of "Standards: GNU (...)"?  It's one of the few consistent and
widespread phrases throughout the manual.

Also, what about deprecation?  I saw the exceptional case of gets
mentioned recently.  There are quite a few BSD things the manual warns
about being deprecated.  Maybe anything that can't be coloured properly
in @standards just deserves a nice paragraph somewhere in the description.


Thank you for all the help!  It is greatly appreciated.

Rical
Florian Weimer Nov. 30, 2016, 10:45 a.m. UTC | #10 
On 11/30/2016 11:39 AM, Rical Jasan wrote:
> On 11/25/2016 06:53 AM, Joseph Myers wrote:

>> Where the function description would then have:

>>

>> Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety

>> Concepts::.

>>

>> Standards: POSIX.1-2008 (unistd.h). *Note Feature Test Macros::.

>

> I like this.  This is one of the avenues I was going to suggest, though

> I wasn't sure how amenable everybody would be to more boilerplate in

> *every single* description.


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?

Thanks,
Florian
Rical Jasan Nov. 30, 2016, 10:46 a.m. UTC | #11 
On 11/25/2016 08:16 AM, Joseph Myers wrote:
> On Fri, 25 Nov 2016, Rical Jasan wrote:

> 

>> On 11/23/2016 09:42 AM, Joseph Myers wrote:

>>> In stdio.h, 

>>> SEEK_SET, SEEK_CUR, SEEK_END are all likewise C90.

>>

>> What about the other 2 headers?  I had:

>>

>> @comment stdio.h unistd.h fcntl.h

>> @comment ISOC99, POSIX, XOPEN || XOPEN2K8

>>

>> Do you want:

>>

>> @comment stdio.h unistd.h fcntl.h

>> @comment C90, POSIX, XOPEN || POSIX.1-2008

> 

> Well, I'd like that comment in summary.awk saying what the intended syntax 

> actually is in the case of multiple headers (how the standards are to be 

> matched to the headers).  But:


I'm not sure summary.awk does any matching, but I'd have to take a
closer look, as I wasn't watching explicitly for that.  I'll certainly
update the comment with accepted syntax, though.

> For stdio.h it's C90.

> 

> For unistd.h it's POSIX.1 (i.e. 1990 edition, in the list I gave of 

> possible notation for standards).

> 

> For fcntl.h it's XOPEN || POSIX.1-2008.

> 

> So if comma-separated standards correspond to space-separated headers, 

> it's as you say except for my proposed notation saying POSIX.1 for the 

> 1990 edition.


Would you like to see an additional patch in the set that converts
existing XOPEN2K, etc.?  I've only fixed the ones I introduced.

Rical
Joseph Myers Nov. 30, 2016, 12:37 p.m. UTC | #12 
On Wed, 30 Nov 2016, Rical Jasan wrote:

> I don't think I'm completely following this.  Is this a redundant test,

> then:

> 

> ./math/bits/math-finite.h:#if defined __USE_MISC && defined __USE_ISOC99


Formally it's redundant.  The use of __USE_ISOC99 there is to mirror the 
conditions under which bits/mathcalls.h is included to declare float and 
long double functions at all (see my comments in commit 
3bfee8beb8caa939020d942dfa405a3d98975749).  Arguably bits/math-finite.h 
should be merged into bits/mathcalls.h (i.e. have a way for the macros 
there to map to the __*_finite functions when appropriate), though that's 
complicated by the separate ia64 version of bits/math-finite.h.

> My practical question is, if MISC is nonstandard, what would we document

> in @standards?  Just MISC?  I see it replaces deprecated feature test


My suggestion was DEFAULT.

> macros _BSD_SOURCE and _SVID_SOURCE (or rather _DEFAULT_SOURCE does,

> which is the only thing that sets __USE_MISC).  Would we not want to

> document that something came from BSD, for example?  (Also see comment

> below about handling deprecation.)


I'd say any such historical information about sources of functions should 
go in free text.  Likewise if we say anything about a function that was 
BSD or SVID or GNU before it was adopted by POSIX, @standards would only 
mention (the relevant version of) POSIX, but free text could say more 
about the history.

> What do you think about handling the common, "This function is a GNU

> extension.", throughout the descriptions?  Would you remove those in

> lieu of "Standards: GNU (...)"?  It's one of the few consistent and

> widespread phrases throughout the manual.


Yes, I think free text describing standards could be removed when it 
doesn't give any more information than the @standards text.  Likewise free 
text saying what header has a declaration.

> Also, what about deprecation?  I saw the exceptional case of gets

> mentioned recently.  There are quite a few BSD things the manual warns

> about being deprecated.  Maybe anything that can't be coloured properly

> in @standards just deserves a nice paragraph somewhere in the description.


Indeed, something not handled by @standards needs free text.

Eventually it would be good for all of the conform/ data, the header 
contents and the standards annotations to be cross-checked against each 
other by the glibc testsuite.  (conform/ and headers are already checked 
against each other.  conform/ should correspond closely to the manual for 
standards properly handled in both, if everything including structure 
elements gets annotations in the manual.  Correspondence between the 
headers and the manual is necessarily weaker, because of symbols exposed 
by headers where the standards permit but don't require this and we don't 
want to define it to be a stable API for those headers, but checking such 
a correspondence is still useful and can cover more standards than 
conform/, including DEFAULT and GNU.)  That includes automatically finding 
undocumented interfaces, for which bugs should then be filed if not 
already open (we have extremely out-of-date scripts/documented.sh for 
listing undocumented functions as well).

When you're checking that the sets of implemented and documented 
interfaces match, you get into needing to document that an interface is 
only available in certain configurations of glibc (e.g. Linux-specific 
interfaces).  Thus I can see us eventually wanting macros (whether or not 
variants of @standards) that will insert text indicating how an interface 
is system-specific, for use by such checks to avoid complaining that an 
interface is documented that doesn't actually exist.

-- 
Joseph S. Myers
joseph@codesourcery.com
Joseph Myers Nov. 30, 2016, 12:50 p.m. UTC | #13 
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
Joseph Myers Nov. 30, 2016, 12:52 p.m. UTC | #14 
On Wed, 30 Nov 2016, Rical Jasan wrote:

> Would you like to see an additional patch in the set that converts

> existing XOPEN2K, etc.?  I've only fixed the ones I introduced.


Given that we define (and document) standard names to use to describe 
standards (and syntax for describing "standard A and standard B", 
"standard A and not standard B", etc.), fixes to existing annotations to 
use those names are useful.

-- 
Joseph S. Myers
joseph@codesourcery.com
Rical Jasan Dec. 2, 2016, 11:53 a.m. UTC | #15 
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
Joseph Myers Dec. 2, 2016, 1:55 p.m. UTC | #16 
On Fri, 2 Dec 2016, Rical Jasan wrote:

> 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


I'm envisaging "Safety" and "Standards" being plain links (in the HTML and 
PDF manuals) to the relevant manual sections, so you don't have the " | 
See Section 1.2.2.1 [POSIX Safety Concepts], page 2." and ", See Section 
1.3.4 [Feature Test Macros], page 15." text at all.  That makes things 
much shorter.  (I don't know if you can readily make such plain links from 
Texinfo at present, but I think it looks a lot better that way when you 
have such annotations appearing for every interface in the manual.)

-- 
Joseph S. Myers
joseph@codesourcery.com
Rical Jasan Dec. 5, 2016, 5:33 a.m. UTC | #17 
On 11/24/2016 05:37 AM, Joseph Myers wrote:
> As for names corresponding to standards / feature test macros, I suggest 

> one possibility:

> 

> C90 (everything is a superset of this apart from gets obsoletion)

> C95

> C99

> C11

>   (note that these four are normally selected with -std, not with feature 

>    test macros, though glibc has _ISOC99_SOURCE and _ISOC11_SOURCE)

> TR 27431-2:2010

> TS 18661-1:2014

> TS 18661-4:2015

> POSIX.1 (= 1990 edition)

> POSIX.2

> POSIX.1-1993

> POSIX.1-1995

> POSIX.1-2001

> XSI POSIX.1-2001

> POSIX.1-2008

> XSI POSIX.1-2008

> DEFAULT

> GNU

> XOPEN (= __USE_XOPEN; listed as XPG3 in conform/ tests; corresponds to 

>        functions in C435 that are not UX-shaded)

> XPG4 (= __USE_XOPEN_EXTENDED; corresponds to everything in C435)

> UNIX98

> LFS (= __USE_LARGEFILE64, i.e. *64 functions)


Since there haven't been any other proposals or comments on this one,
I'm using this list, but I was curious: is there a technical reason for
not using, e.g., "ISO C90"?

Rical
Rical Jasan Dec. 5, 2016, 7:59 a.m. UTC | #18 
On 12/02/2016 05:55 AM, Joseph Myers wrote:
> On Fri, 2 Dec 2016, Rical Jasan wrote:

> 

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

> 

> I'm envisaging "Safety" and "Standards" being plain links (in the HTML and 

> PDF manuals) to the relevant manual sections, so you don't have the " | 

> See Section 1.2.2.1 [POSIX Safety Concepts], page 2." and ", See Section 

> 1.3.4 [Feature Test Macros], page 15." text at all.  That makes things 

> much shorter.  (I don't know if you can readily make such plain links from 

> Texinfo at present, but I think it looks a lot better that way when you 

> have such annotations appearing for every interface in the manual.)


I don't think that's possible using Texinfo.  The @*ref-commands allow
some variance in their rendering, but nothing that overrides the entire
rendered string like that, from what I can see.

Rical
Joseph Myers Dec. 5, 2016, 6:22 p.m. UTC | #19 
On Sun, 4 Dec 2016, Rical Jasan wrote:

> Since there haven't been any other proposals or comments on this one,

> I'm using this list, but I was curious: is there a technical reason for

> not using, e.g., "ISO C90"?


No, just keeping the names short.

-- 
Joseph S. Myers
joseph@codesourcery.com
Rical Jasan Dec. 6, 2016, 10:57 a.m. UTC | #20 
On 11/24/2016 05:37 AM, Joseph Myers wrote:
> As for names corresponding to standards / feature test macros, I suggest 

> one possibility:

> 

> C90 (everything is a superset of this apart from gets obsoletion)

> C95

> C99

> C11

>   (note that these four are normally selected with -std, not with feature 

>    test macros, though glibc has _ISOC99_SOURCE and _ISOC11_SOURCE)

> TR 27431-2:2010

> TS 18661-1:2014

> TS 18661-4:2015

> POSIX.1 (= 1990 edition)

> POSIX.2

> POSIX.1-1993

> POSIX.1-1995

> POSIX.1-2001

> XSI POSIX.1-2001

> POSIX.1-2008

> XSI POSIX.1-2008

> DEFAULT

> GNU

> XOPEN (= __USE_XOPEN; listed as XPG3 in conform/ tests; corresponds to 

>        functions in C435 that are not UX-shaded)

> XPG4 (= __USE_XOPEN_EXTENDED; corresponds to everything in C435)

> UNIX98

> LFS (= __USE_LARGEFILE64, i.e. *64 functions)


As food for thought, since nobody has suggested alternatives yet, and
I've been examining all the variations in current use, what about:

BSD
4.3BSD
4.4BSD
GNU
ISO C90
ISO C95
ISO C99
ISO C11
ISO/IEC TR 27431-2:2010
ISO/IEC TS 18661-1:2014
ISO/IEC TS 18661-4:2015
LFS
Linux
POSIX.1-1990
POSIX.1-1993
POSIX.1-1995
POSIX.1-2001
POSIX.1-2008
POSIX.2-1992
Sun
SVID
UNIX 98
XPG
XPG2
XPG3
XPG4
XPG4.2
XSI POSIX.1-2001
XSI POSIX.1-2008

Ideally, unversioned names would be replaced by ones with versions.

The major differences are the use of XPG instead of XOPEN, which makes
it consistent with the versioned uses; adding versions to POSIX.[12],
since they look like less-specific catchalls otherwise; including the
standards body for the ISO standards (though that's mainly for the C*
standards, and aesthetic); and keeping the BSD and SVID standards,
because I hate to see information lost, when we already have it.  The
BSD/SVID standards could reference _DEFAULT_SOURCE, where the
description would state it encompasses BSD, SVID, MISC, etc.

I see the Unix standard typically formatted with a space, and capitalized.

Sun is a lame attempt; there are all of Sun, SunOS, and SUNRPC in
current use.  Suggestions welcome.

There is also "IPv6 Basic API", which should probably be an RFC or
something.

POSIX.1g is also used.

I imagine whatever we finally settle on to be accompanied by changes to
the Introduction, where we can list in more detail the variety of names
given standards are referred to by, and which the "canonical" standard
will reference.  I've been making a list of all the equivalent names one
tends to see.  We can use simpler names in the standards annotations,
but it would be nice in the Standards and Portability section to be able
to refer unambiguously to a specific document.

Playing another part in how this eventually all ties together are the
references in the standards annotations: would we refer back to Feature
Test Macros, or the given section describing the standard in Standards
and Portability?

Rical
Joseph Myers Dec. 6, 2016, 3:58 p.m. UTC | #21 
On Tue, 6 Dec 2016, Rical Jasan wrote:

> XPG

> XPG2

> XPG3

> XPG4

> XPG4.2


To clarify: you would use XPG4.2 for the interfaces enabled with 
_XOPEN_SOURCE_EXTENDED (UX-shaded in XPG4.2, what the conform/ data calls 
XPG4), XPG4 for interfaces not UX-shaded in XPG4.2 (which generally would 
have been in the original XPG4; which the conform/ data misleadingly calls 
XPG3)?  And older versions where actually in those older versions.

> POSIX.1g is also used.


I don't think we need to consider .1g (sockets) separately from .1-2001.

-- 
Joseph S. Myers
joseph@codesourcery.com
Zack Weinberg Dec. 6, 2016, 4:36 p.m. UTC | #22 
On 12/06/2016 05:57 AM, Rical Jasan wrote:
> As food for thought, since nobody has suggested alternatives yet, and

> I've been examining all the variations in current use, what about:


If this list is going to appear somewhere in the manual, it would be
easier to understand if it was organized first topically and then
chronologically.

ISO C90, C95, C99, C11, TRs/TSes
POSIX.1/2 1990, 1992, 1993, 1995, 2001 (XSI), 2008 (XSI)
LFS (2004?)

XPG3 (1990), XPG4(.2) (1992?), UNIX 98 (1998)
BSD 4.3 (1986), 4.4 (1993)

undated: GNU, Linux, BSD, System V, Sun

"BSD" includes both things that are really, really old (like a lot of
the networking APIs) and things that are brand new (like explicit_bzero,
if I ever manage to get that approved).  Similarly Linux, BSD, System V,
Sun.

"SVID" refers to a specific document, I think equivalent to one of the
XPG series, but we were using it as a catch-all for "not-standardized
thing from the System V lineage", so let's rename it "System V".

I don't think tracing history back before 1990 is terribly useful.  I'm
not even sure we're doing anyone any favors by preserving all those
pre-2001 POSIX feature selection knobs.

> ISO/IEC TR 27431-2:2010

> ISO/IEC TS 18661-1:2014

> ISO/IEC TS 18661-4:2015


Nobody's going to have any idea what the heck these are.  It's not wrong
to give them their official ISO/IEC numbers, but we need the short
titles as well.

> XSI POSIX.1-2001

> XSI POSIX.1-2008


XSI is an add-on module for POSIX, so it should be named *after* the
date (POSIX.1-2001 XSI, POSIX.1-2008 XSI)

> Sun is a lame attempt; there are all of Sun, SunOS, and SUNRPC in

> current use.  Suggestions welcome.


"Sun" is a good catch-all term for things invented by Sun Microsystems.
We're trying (painfully slowly) to get rid of the Sun RPC code, but
there will still be other Sun-derived stuff after it's gone.

> There is also "IPv6 Basic API", which should probably be an RFC or

> something.


https://tools.ietf.org/html/rfc3493 "Basic Socket Interface Extensions
for IPv6", probably.

> POSIX.1g is also used.


There were a whole bunch of documents named POSIX.1[a-z]; they were
folded into the base standard in either 1995 or 2001, and I'd recommend
we just document the point where that happened (so, treat .1g as another
name for .1-2001).

zw
diff mbox

Patch

diff --git a/manual/argp.texi b/manual/argp.texi
index bca3ca5..2088163 100644
--- a/manual/argp.texi
+++ b/manual/argp.texi
@@ -1133,35 +1133,53 @@  is determined by the @var{flags} argument.  This should consist of any of
 the following flags, or'd together:
 
 @vtable @code
+@comment argp.h
+@comment ???
 @item ARGP_HELP_USAGE
 A unix @samp{Usage:} message that explicitly lists all options.
 
+@comment argp.h
+@comment ???
 @item ARGP_HELP_SHORT_USAGE
 A unix @samp{Usage:} message that displays an appropriate placeholder to
 indicate where the options go; useful for showing the non-option
 argument syntax.
 
+@comment argp.h
+@comment ???
 @item ARGP_HELP_SEE
 A @samp{Try @dots{} for more help} message; @samp{@dots{}} contains the
 program name and @samp{--help}.
 
+@comment argp.h
+@comment ???
 @item ARGP_HELP_LONG
 A verbose option help message that gives each option available along
 with its documentation string.
 
+@comment argp.h
+@comment ???
 @item ARGP_HELP_PRE_DOC
 The part of the argp parser doc string preceding the verbose option help.
 
+@comment argp.h
+@comment ???
 @item ARGP_HELP_POST_DOC
 The part of the argp parser doc string that following the verbose option help.
 
+@comment argp.h
+@comment ???
 @item ARGP_HELP_DOC
 @code{(ARGP_HELP_PRE_DOC | ARGP_HELP_POST_DOC)}
 
+@comment argp.h
+@comment ???
 @item ARGP_HELP_BUG_ADDR
 A message that prints where to report bugs for this program, if the
 @code{argp_program_bug_address} variable contains this information.
 
+@comment argp.h
+@comment ???
 @item ARGP_HELP_LONG_ONLY
 This will modify any output to reflect the @code{ARGP_LONG_ONLY} mode.
 @end vtable
@@ -1171,9 +1189,13 @@  The following flags are only understood when used with
 printing its output, or terminates the program:
 
 @vtable @code
+@comment argp.h
+@comment ???
 @item ARGP_HELP_EXIT_ERR
 This will terminate the program with @code{exit (argp_err_exit_status)}.
 
+@comment argp.h
+@comment ???
 @item ARGP_HELP_EXIT_OK
 This will terminate the program with @code{exit (0)}.
 @end vtable
@@ -1182,16 +1204,22 @@  The following flags are combinations of the basic flags for printing
 standard messages:
 
 @vtable @code
+@comment argp.h
+@comment ???
 @item ARGP_HELP_STD_ERR
 Assuming that an error message for a parsing error has printed, this
 prints a message on how to get help, and terminates the program with an
 error.
 
+@comment argp.h
+@comment ???
 @item ARGP_HELP_STD_USAGE
 This prints a standard usage message and terminates the program with an
 error.  This is used when no other specific error messages are
 appropriate or available.
 
+@comment argp.h
+@comment ???
 @item ARGP_HELP_STD_HELP
 This prints the standard response for a @samp{--help} option, and
 terminates the program successfully.
diff --git a/manual/arith.texi b/manual/arith.texi
index 07dd733..d3a217c 100644
--- a/manual/arith.texi
+++ b/manual/arith.texi
@@ -331,22 +331,32 @@  This is a generic macro which works on all floating-point types and
 which returns a value of type @code{int}.  The possible values are:
 
 @vtable @code
+@comment math.h
+@comment ISOC99
 @item FP_NAN
 The floating-point number @var{x} is ``Not a Number'' (@pxref{Infinity
 and NaN})
+@comment math.h
+@comment ISOC99
 @item FP_INFINITE
 The value of @var{x} is either plus or minus infinity (@pxref{Infinity
 and NaN})
+@comment math.h
+@comment ISOC99
 @item FP_ZERO
 The value of @var{x} is zero.  In floating-point formats like @w{IEEE
 754}, where zero can be signed, this value is also returned if
 @var{x} is negative zero.
+@comment math.h
+@comment ISOC99
 @item FP_SUBNORMAL
 Numbers whose absolute value is too small to be represented in the
 normal format are represented in an alternate, @dfn{denormalized} format
 (@pxref{Floating Point Concepts}).  This format is less precise but can
 represent values closer to zero.  @code{fpclassify} returns this value
 for values of @var{x} in this alternate format.
+@comment math.h
+@comment ISOC99
 @item FP_NORMAL
 This value is returned for all other values of @var{x}.  It indicates
 that there is nothing special about the number.
@@ -714,7 +724,11 @@  such as by defining @code{_GNU_SOURCE}, and then you must include
 @comment math.h
 @comment ISO
 @deftypevr Macro float SNANF
+@comment math.h
+@comment ISO
 @deftypevrx Macro double SNAN
+@comment math.h
+@comment ISO
 @deftypevrx Macro {long double} SNANL
 These macros, defined by TS 18661-1:2014, are constant expressions for
 signaling NaNs.
@@ -2027,8 +2041,10 @@  NaN.
 @comment math.h
 @comment ISO
 @deftypefun int totalorder (double @var{x}, double @var{y})
+@comment math.h
 @comment ISO
 @deftypefunx int totalorderf (float @var{x}, float @var{y})
+@comment math.h
 @comment ISO
 @deftypefunx int totalorderl (long double @var{x}, long double @var{y})
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@@ -2049,8 +2065,10 @@  payload.
 @comment math.h
 @comment ISO
 @deftypefun int totalordermag (double @var{x}, double @var{y})
+@comment math.h
 @comment ISO
 @deftypefunx int totalordermagf (float @var{x}, float @var{y})
+@comment math.h
 @comment ISO
 @deftypefunx int totalordermagl (long double @var{x}, long double @var{y})
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@@ -2183,6 +2201,8 @@  part of a number.  There is no standard notation for an imaginary
 floating point constant.  Instead, @file{complex.h} defines two macros
 that can be used to create complex numbers.
 
+@comment complex.h
+@comment ISO
 @deftypevr Macro {const float complex} _Complex_I
 This macro is a representation of the complex number ``@math{0+1i}''.
 Multiplying a real floating-point value by @code{_Complex_I} gives a
@@ -2205,6 +2225,8 @@  Without an optimizing compiler this is more expensive than the use of
 the hassles if you use the @code{I} macro below if the name is not
 problem.
 
+@comment complex.h
+@comment ISO
 @deftypevr Macro {const float imaginary} _Imaginary_I
 This macro is a representation of the value ``@math{1i}''.  I.e., it is
 the value for which
@@ -2231,6 +2253,8 @@  imaginary part -4.0.
 @code{_Complex_I} is a bit of a mouthful.  @file{complex.h} also defines
 a shorter name for the same constant.
 
+@comment complex.h
+@comment ISO
 @deftypevr Macro {const float complex} I
 This macro has exactly the same value as @code{_Complex_I}.  Most of the
 time it is preferable.  However, it causes problems if you want to use
@@ -2873,7 +2897,11 @@  The @samp{strfrom} functions are declared in @file{stdlib.h}.
 @comment stdlib.h
 @comment ISO/IEC TS 18661-1
 @deftypefun int strfromd (char *restrict @var{string}, size_t @var{size}, const char *restrict @var{format}, double @var{value})
+@comment stdlib.h
+@comment ISO/IEC TS 18661-1
 @deftypefunx int strfromf (char *restrict @var{string}, size_t @var{size}, const char *restrict @var{format}, float @var{value})
+@comment stdlib.h
+@comment ISO/IEC TS 18661-1
 @deftypefunx int strfroml (char *restrict @var{string}, size_t @var{size}, const char *restrict @var{format}, long double @var{value})
 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
 @comment these functions depend on __printf_fp and __printf_fphex, which are
diff --git a/manual/creature.texi b/manual/creature.texi
index 257f871..babec55 100644
--- a/manual/creature.texi
+++ b/manual/creature.texi
@@ -218,6 +218,8 @@  cause them to be disabled.
 @comment (none)
 @comment GNU
 @defvr Macro _REENTRANT
+@comment (none)
+@comment ???
 @defvrx Macro _THREAD_SAFE
 If you define one of these macros, reentrant versions of several functions get
 declared.  Some of the functions are specified in POSIX.1c but many others
diff --git a/manual/filesys.texi b/manual/filesys.texi
index 0b83999..7befca2 100644
--- a/manual/filesys.texi
+++ b/manual/filesys.texi
@@ -285,28 +285,44 @@  This is the type of the file, possibly unknown.  The following constants
 are defined for its value:
 
 @vtable @code
+@comment dirent.h
+@comment MISC
 @item DT_UNKNOWN
 The type is unknown.  Only some filesystems have full support to
 return the type of the file, others might always return this value.
 
+@comment dirent.h
+@comment MISC
 @item DT_REG
 A regular file.
 
+@comment dirent.h
+@comment MISC
 @item DT_DIR
 A directory.
 
+@comment dirent.h
+@comment MISC
 @item DT_FIFO
 A named pipe, or FIFO.  @xref{FIFO Special Files}.
 
+@comment dirent.h
+@comment MISC
 @item DT_SOCK
 A local-domain socket.  @c !!! @xref{Local Domain}.
 
+@comment dirent.h
+@comment MISC
 @item DT_CHR
 A character device.
 
+@comment dirent.h
+@comment MISC
 @item DT_BLK
 A block device.
 
+@comment dirent.h
+@comment MISC
 @item DT_LNK
 A symbolic link.
 @end vtable
@@ -878,16 +894,26 @@  The last parameter is a flag giving more information about the current
 file.  It can have the following values:
 
 @vtable @code
+@comment ftw.h
+@comment XOPEN
 @item FTW_F
 The item is either a normal file or a file which does not fit into one
 of the following categories.  This could be special files, sockets etc.
+@comment ftw.h
+@comment XOPEN
 @item FTW_D
 The item is a directory.
+@comment ftw.h
+@comment XOPEN
 @item FTW_NS
 The @code{stat} call failed and so the information pointed to by the
 second parameter is invalid.
+@comment ftw.h
+@comment XOPEN
 @item FTW_DNR
 The item is a directory which cannot be read.
+@comment ftw.h
+@comment MISC || XOPEN_EXTENDED
 @item FTW_SL
 The item is a symbolic link.  Since symbolic links are normally followed
 seeing this value in a @code{ftw} callback function means the referenced
@@ -932,10 +958,14 @@  The first three arguments are the same as for the @code{__ftw_func_t}
 type.  However for the third argument some additional values are defined
 to allow finer differentiation:
 @vtable @code
+@comment ftw.h
+@comment XOPEN_EXTENDED
 @item FTW_DP
 The current item is a directory and all subdirectories have already been
 visited and reported.  This flag is returned instead of @code{FTW_D} if
 the @code{FTW_DEPTH} flag is passed to @code{nftw} (see below).
+@comment ftw.h
+@comment XOPEN_EXTENDED
 @item FTW_SLN
 The current item is a stale symbolic link.  The file it points to does
 not exist.
@@ -1083,25 +1113,35 @@  A second difference is that @code{nftw} takes a fourth argument, which
 is @math{0} or a bitwise-OR combination of any of the following values.
 
 @vtable @code
+@comment ftw.h
+@comment XOPEN_EXTENDED
 @item FTW_PHYS
 While traversing the directory symbolic links are not followed.  Instead
 symbolic links are reported using the @code{FTW_SL} value for the type
 parameter to the callback function.  If the file referenced by a
 symbolic link does not exist @code{FTW_SLN} is returned instead.
+@comment ftw.h
+@comment XOPEN_EXTENDED
 @item FTW_MOUNT
 The callback function is only called for items which are on the same
 mounted filesystem as the directory given by the @var{filename}
 parameter to @code{nftw}.
+@comment ftw.h
+@comment XOPEN_EXTENDED
 @item FTW_CHDIR
 If this flag is given the current working directory is changed to the
 directory of the reported object before the callback function is called.
 When @code{ntfw} finally returns the current directory is restored to
 its original value.
+@comment ftw.h
+@comment XOPEN_EXTENDED
 @item FTW_DEPTH
 If this option is specified then all subdirectories and files within
 them are processed before processing the top directory itself
 (depth-first processing).  This also means the type flag given to the
 callback function is @code{FTW_DP} and not @code{FTW_D}.
+@comment ftw.h
+@comment XOPEN_EXTENDED && GNU
 @item FTW_ACTIONRETVAL
 If this option is specified then return values from callbacks
 are handled differently.  If the callback returns @code{FTW_CONTINUE},
@@ -3264,6 +3304,8 @@  occurring later.  Checking for write errors is still required, and
 writes to memory-mapped regions created with @code{mmap} can still
 result in @code{SIGBUS}.
 
+@comment fcntl.h
+@comment XOPEN2K
 @deftypefun int posix_fallocate (int @var{fd}, off_t @var{offset}, off_t @var{length})
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 @c If the file system does not support allocation,
@@ -3322,6 +3364,8 @@  allocation.  Instead, an @code{EOPNOTSUPP} is returned to the caller.
 
 @end deftypefun
 
+@comment fcntl.h
+@comment XOPEN2K
 @deftypefun int posix_fallocate64 (int @var{fd}, off64_t @var{offset}, off64_t @var{length})
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 
diff --git a/manual/ipc.texi b/manual/ipc.texi
index 081b98f..1b41fba 100644
--- a/manual/ipc.texi
+++ b/manual/ipc.texi
@@ -20,6 +20,8 @@  by @theglibc{}.
 @c Need descriptions for all of these functions.
 
 @subsection System V Semaphores
+@comment sys/sem.h
+@comment SVID
 @deftypefun int semctl (int @var{semid}, int @var{semnum}, int @var{cmd});
 @safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{/linux}}}
 @c syscall(ipc) ok
@@ -30,16 +32,22 @@  by @theglibc{}.
 @c semid_ds.
 @end deftypefun
 
+@comment sys/sem.h
+@comment SVID
 @deftypefun int semget (key_t @var{key}, int @var{nsems}, int @var{semflg});
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 @c syscall(ipc) ok
 @end deftypefun
 
+@comment sys/sem.h
+@comment SVID
 @deftypefun int semop (int @var{semid}, struct sembuf *@var{sops}, size_t @var{nsops});
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 @c syscall(ipc) ok
 @end deftypefun
 
+@comment sys/sem.h
+@comment GNU
 @deftypefun int semtimedop (int @var{semid}, struct sembuf *@var{sops}, size_t @var{nsops}, const struct timespec *@var{timeout});
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 @c syscall(ipc) ok
@@ -47,17 +55,23 @@  by @theglibc{}.
 
 @subsection POSIX Semaphores
 
+@comment semaphore.h
+@comment POSIX
 @deftypefun int sem_init (sem_t *@var{sem}, int @var{pshared}, unsigned int @var{value});
 @safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}}
 @c Does not atomically update sem_t therefore AC-unsafe
 @c because it can leave sem_t partially initialized.
 @end deftypefun
 
+@comment semaphore.h
+@comment POSIX
 @deftypefun int sem_destroy (sem_t *@var{sem});
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 @c Function does nothing and is therefore always safe.
 @end deftypefun
 
+@comment semaphore.h
+@comment POSIX
 @deftypefun sem_t *sem_open (const char *@var{name}, int @var{oflag}, ...);
 @safety{@prelim{}@mtsafe{}@asunsafe{@asuinit{}}@acunsafe{@acuinit{}}}
 @c pthread_once asuinit
@@ -67,6 +81,8 @@  by @theglibc{}.
 @c shmfs on Linux.
 @end deftypefun
 
+@comment semaphore.h
+@comment POSIX
 @deftypefun int sem_close (sem_t *@var{sem});
 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
 @c lll_lock asulock aculock
@@ -77,12 +93,16 @@  by @theglibc{}.
 @c are not updated atomically.
 @end deftypefun
 
+@comment semaphore.h
+@comment POSIX
 @deftypefun int sem_unlink (const char *@var{name});
 @safety{@prelim{}@mtsafe{}@asunsafe{@asuinit{}}@acunsafe{@acucorrupt{}}}
 @c pthread_once asuinit acucorrupt aculock
 @c mempcpy acucorrupt
 @end deftypefun
 
+@comment semaphore.h
+@comment POSIX
 @deftypefun int sem_wait (sem_t *@var{sem});
 @safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}}
 @c atomic_increment (nwaiters) acucorrupt
@@ -95,21 +115,29 @@  by @theglibc{}.
 @c waiters count.
 @end deftypefun
 
+@comment semaphore.h
+@comment XOPEN2K
 @deftypefun int sem_timedwait (sem_t *@var{sem}, const struct timespec *@var{abstime});
 @safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}}
 @c Same safety issues as sem_wait.
 @end deftypefun
 
+@comment semaphore.h
+@comment POSIX
 @deftypefun int sem_trywait (sem_t *@var{sem});
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 @c All atomic operations are safe in all contexts.
 @end deftypefun
 
+@comment semaphore.h
+@comment POSIX
 @deftypefun int sem_post (sem_t *@var{sem});
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 @c Same safety as sem_trywait.
 @end deftypefun
 
+@comment semaphore.h
+@comment POSIX
 @deftypefun int sem_getvalue (sem_t *@var{sem}, int *@var{sval});
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 @c Atomic write of a value is safe in all contexts.
diff --git a/manual/lang.texi b/manual/lang.texi
index b6ad703..727bc49 100644
--- a/manual/lang.texi
+++ b/manual/lang.texi
@@ -478,6 +478,8 @@  of the same type.
 @comment stdarg.h
 @comment ISO
 @deftypefn {Macro} void va_copy (va_list @var{dest}, va_list @var{src})
+@comment stdarg.h
+@comment ISO
 @deftypefnx {Macro} void __va_copy (va_list @var{dest}, va_list @var{src})
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 @c This is no longer provided by glibc, but rather by the compiler.
@@ -1109,6 +1111,8 @@  where @code{radix} appears @code{FLT_MANT_DIG} times.
 @comment float.h
 @comment ISO
 @item DBL_MANT_DIG
+@comment float.h
+@comment ISO
 @itemx LDBL_MANT_DIG
 This is the number of base-@code{FLT_RADIX} digits in the floating point
 mantissa for the data types @code{double} and @code{long double},
@@ -1133,6 +1137,8 @@  The value of this macro is supposed to be at least @code{6}, to satisfy
 @comment float.h
 @comment ISO
 @item DBL_DIG
+@comment float.h
+@comment ISO
 @itemx LDBL_DIG
 
 These are similar to @code{FLT_DIG}, but for the data types
@@ -1150,6 +1156,8 @@  normalized floating point number of type @code{float}.
 @comment float.h
 @comment ISO
 @item DBL_MIN_EXP
+@comment float.h
+@comment ISO
 @itemx LDBL_MIN_EXP
 
 These are similar to @code{FLT_MIN_EXP}, but for the data types
@@ -1165,6 +1173,8 @@  of type @code{float}.  This is supposed to be @code{-37} or even less.
 @comment float.h
 @comment ISO
 @item DBL_MIN_10_EXP
+@comment float.h
+@comment ISO
 @itemx LDBL_MIN_10_EXP
 These are similar to @code{FLT_MIN_10_EXP}, but for the data types
 @code{double} and @code{long double}, respectively.
@@ -1180,6 +1190,8 @@  floating point number of type @code{float}.
 @comment float.h
 @comment ISO
 @item DBL_MAX_EXP
+@comment float.h
+@comment ISO
 @itemx LDBL_MAX_EXP
 These are similar to @code{FLT_MAX_EXP}, but for the data types
 @code{double} and @code{long double}, respectively.
@@ -1194,6 +1206,8 @@  of type @code{float}.  This is supposed to be at least @code{37}.
 @comment float.h
 @comment ISO
 @item DBL_MAX_10_EXP
+@comment float.h
+@comment ISO
 @itemx LDBL_MAX_10_EXP
 These are similar to @code{FLT_MAX_10_EXP}, but for the data types
 @code{double} and @code{long double}, respectively.
@@ -1211,6 +1225,8 @@  The smallest representable number is @code{- FLT_MAX}.
 @comment float.h
 @comment ISO
 @item DBL_MAX
+@comment float.h
+@comment ISO
 @itemx LDBL_MAX
 
 These are similar to @code{FLT_MAX}, but for the data types
@@ -1228,6 +1244,8 @@  to be no more than @code{1E-37}.
 @comment float.h
 @comment ISO
 @item DBL_MIN
+@comment float.h
+@comment ISO
 @itemx LDBL_MIN
 
 These are similar to @code{FLT_MIN}, but for the data types
@@ -1245,6 +1263,8 @@  be no greater than @code{1E-5}.
 @comment float.h
 @comment ISO
 @item DBL_EPSILON
+@comment float.h
+@comment ISO
 @itemx LDBL_EPSILON
 
 These are similar to @code{FLT_EPSILON}, but for the data types
diff --git a/manual/llio.texi b/manual/llio.texi
index 0db44e0..c401732 100644
--- a/manual/llio.texi
+++ b/manual/llio.texi
@@ -691,14 +691,20 @@  be one of the symbolic constants @code{SEEK_SET}, @code{SEEK_CUR}, or
 @code{SEEK_END}.
 
 @vtable @code
+@comment stdio.h unistd.h fcntl.h
+@comment ISOC99, POSIX, XOPEN || XOPEN2K8
 @item SEEK_SET
 Specifies that @var{offset} is a count of characters from the beginning
 of the file.
 
+@comment stdio.h unistd.h fcntl.h
+@comment ISOC99, POSIX, XOPEN || XOPEN2K8
 @item SEEK_CUR
 Specifies that @var{offset} is a count of characters from the current
 file position.  This count may be positive or negative.
 
+@comment stdio.h unistd.h fcntl.h
+@comment ISOC99, POSIX, XOPEN || XOPEN2K8
 @item SEEK_END
 Specifies that @var{offset} is a count of characters from the end of
 the file.  A negative count specifies a position within the current
@@ -859,12 +865,18 @@  of compatibility with older BSD systems.  They are defined in two
 different header files: @file{fcntl.h} and @file{sys/file.h}.
 
 @vtable @code
+@comment unistd.h sys/file.h
+@comment BSD, MISC
 @item L_SET
 An alias for @code{SEEK_SET}.
 
+@comment unistd.h sys/file.h
+@comment BSD, MISC
 @item L_INCR
 An alias for @code{SEEK_CUR}.
 
+@comment unistd.h sys/file.h
+@comment BSD, MISC
 @item L_XTND
 An alias for @code{SEEK_END}.
 @end vtable
@@ -1253,6 +1265,8 @@  One of @code{MAP_SHARED} or @code{MAP_PRIVATE} must be specified.
 They include:
 
 @vtable @code
+@comment sys/mman.h
+@comment BSD
 @item MAP_PRIVATE
 This specifies that writes to the region should never be written back
 to the attached file.  Instead, a copy is made for the process, and the
@@ -1263,6 +1277,8 @@  Since private mappings effectively revert to ordinary memory
 when written to, you must have enough virtual memory for a copy of
 the entire mmapped region if you use this mode with @code{PROT_WRITE}.
 
+@comment sys/mman.h
+@comment BSD
 @item MAP_SHARED
 This specifies that writes to the region will be written back to the
 file.  Changes made will be shared immediately with other processes
@@ -1272,13 +1288,19 @@  Note that actual writing may take place at any time.  You need to use
 @code{msync}, described below, if it is important that other processes
 using conventional I/O get a consistent view of the file.
 
+@comment sys/mman.h
+@comment BSD
 @item MAP_FIXED
 This forces the system to use the exact mapping address specified in
 @var{address} and fail if it can't.
 
 @c One of these is official - the other is obviously an obsolete synonym
 @c Which is which?
+@comment sys/mman.h
+@comment Linux, MISC
 @item MAP_ANONYMOUS
+@comment sys/mman.h
+@comment BSD, MISC
 @itemx MAP_ANON
 This flag tells the system to create an anonymous mapping, not connected
 to a file.  @var{filedes} and @var{offset} are ignored, and the region is
@@ -1402,12 +1424,16 @@  region given should not contain any unmapped space.
 
 @vtable @code
 
+@comment sys/mman.h
+@comment BSD
 @item MS_SYNC
 
 This flag makes sure the data is actually written @emph{to disk}.
 Normally @code{msync} only makes sure that accesses to a file with
 conventional I/O reflect the recent changes.
 
+@comment sys/mman.h
+@comment BSD
 @item MS_ASYNC
 
 This tells @code{msync} to begin the synchronization, but not to wait for
@@ -1494,22 +1520,32 @@  The valid BSD values for @var{advice} are:
 
 @vtable @code
 
+@comment sys/mman.h
+@comment MISC
 @item MADV_NORMAL
 The region should receive no further special treatment.
 
+@comment sys/mman.h
+@comment MISC
 @item MADV_RANDOM
 The region will be accessed via random page references.  The kernel
 should page-in the minimal number of pages for each page fault.
 
+@comment sys/mman.h
+@comment MISC
 @item MADV_SEQUENTIAL
 The region will be accessed via sequential page references.  This
 may cause the kernel to aggressively read-ahead, expecting further
 sequential references after any page fault within this region.
 
+@comment sys/mman.h
+@comment MISC
 @item MADV_WILLNEED
 The region will be needed.  The pages within this region may
 be pre-faulted in by the kernel.
 
+@comment sys/mman.h
+@comment MISC
 @item MADV_DONTNEED
 The region is no longer needed.  The kernel may free these pages,
 causing any changes to the pages to be lost, as well as swapped
@@ -1521,18 +1557,28 @@  The POSIX names are slightly different, but with the same meanings:
 
 @vtable @code
 
+@comment sys/mman.h
+@comment XOPEN2K
 @item POSIX_MADV_NORMAL
 This corresponds with BSD's @code{MADV_NORMAL}.
 
+@comment sys/mman.h
+@comment XOPEN2K
 @item POSIX_MADV_RANDOM
 This corresponds with BSD's @code{MADV_RANDOM}.
 
+@comment sys/mman.h
+@comment XOPEN2K
 @item POSIX_MADV_SEQUENTIAL
 This corresponds with BSD's @code{MADV_SEQUENTIAL}.
 
+@comment sys/mman.h
+@comment XOPEN2K
 @item POSIX_MADV_WILLNEED
 This corresponds with BSD's @code{MADV_WILLNEED}.
 
+@comment sys/mman.h
+@comment XOPEN2K
 @item POSIX_MADV_DONTNEED
 This corresponds with BSD's @code{MADV_DONTNEED}.
 
@@ -1587,6 +1633,8 @@  The semantics of @var{oflag} and @var{mode} arguments is same as in @code{open}.
 On failure @code{errno} is set.
 @end deftypefn
 
+@comment sys/mman.h
+@comment POSIX
 @deftypefn Function int shm_unlink (const char *@var{name})
 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asuinit{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
 @c shm_unlink @mtslocale @asuinit @ascuheap @asulock @aculock @acsmem @acsfd
@@ -1972,15 +2020,21 @@  input or output (or nothing), the information must be stored in the
 control block.  The possible values are:
 
 @vtable @code
+@comment aio.h
+@comment POSIX
 @item LIO_READ
 Start a read operation.  Read from the file at position
 @code{aio_offset} and store the next @code{aio_nbytes} bytes in the
 buffer pointed to by @code{aio_buf}.
 
+@comment aio.h
+@comment POSIX
 @item LIO_WRITE
 Start a write operation.  Write @code{aio_nbytes} bytes starting at
 @code{aio_buf} into the file starting at position @code{aio_offset}.
 
+@comment aio.h
+@comment POSIX
 @item LIO_NOP
 Do nothing for this control block.  This value is useful sometimes when
 an array of @code{struct aiocb} values contains holes, i.e., some of the
@@ -2907,47 +2961,73 @@  descriptions of the individual commands.
 Briefly, here is a list of what the various commands are.
 
 @vtable @code
+@comment fcntl.h
+@comment BSD
 @item F_DUPFD
 Duplicate the file descriptor (return another file descriptor pointing
 to the same open file).  @xref{Duplicating Descriptors}.
 
+@comment fcntl.h
+@comment BSD
 @item F_GETFD
 Get flags associated with the file descriptor.  @xref{Descriptor Flags}.
 
+@comment fcntl.h
+@comment BSD
 @item F_SETFD
 Set flags associated with the file descriptor.  @xref{Descriptor Flags}.
 
+@comment fcntl.h
+@comment BSD
 @item F_GETFL
 Get flags associated with the open file.  @xref{File Status Flags}.
 
+@comment fcntl.h
+@comment BSD
 @item F_SETFL
 Set flags associated with the open file.  @xref{File Status Flags}.
 
+@comment fcntl.h
+@comment BSD
 @item F_GETLK
 Test a file lock.  @xref{File Locks}.
 
+@comment fcntl.h
+@comment BSD
 @item F_SETLK
 Set or clear a file lock.  @xref{File Locks}.
 
+@comment fcntl.h
+@comment BSD
 @item F_SETLKW
 Like @code{F_SETLK}, but wait for completion.  @xref{File Locks}.
 
+@comment fcntl.h
+@comment GNU
 @item F_OFD_GETLK
 Test an open file description lock.  @xref{Open File Description Locks}.
 Specific to Linux.
 
+@comment fcntl.h
+@comment GNU
 @item F_OFD_SETLK
 Set or clear an open file description lock.  @xref{Open File Description Locks}.
 Specific to Linux.
 
+@comment fcntl.h
+@comment GNU
 @item F_OFD_SETLKW
 Like @code{F_OFD_SETLK}, but block until lock is acquired.
 @xref{Open File Description Locks}.  Specific to Linux.
 
+@comment fcntl.h
+@comment UNIX98 || XOPEN2K8
 @item F_GETOWN
 Get process or process group ID to receive @code{SIGIO} signals.
 @xref{Interrupt Input}.
 
+@comment fcntl.h
+@comment UNIX98 || XOPEN2K8
 @item F_SETOWN
 Set process or process group ID to receive @code{SIGIO} signals.
 @xref{Interrupt Input}.
@@ -3925,6 +4005,8 @@  When the same @code{struct flock} is reused as an argument to a
 
 @pindex fcntl.h.
 
+@comment fcntl.h
+@comment GNU
 @deftypevr Macro int F_OFD_GETLK
 This macro is used as the @var{command} argument to @code{fcntl}, to
 specify that it should get information about a lock.  This command
diff --git a/manual/locale.texi b/manual/locale.texi
index ae71ccc..8411eba 100644
--- a/manual/locale.texi
+++ b/manual/locale.texi
@@ -915,57 +915,139 @@  The type @code{nl_type} is defined in @file{nl_types.h}.  The argument
 The X/Open standard defines the following values:
 
 @vtable @code
+@comment langinfo.h
+@comment XOPEN
 @item CODESET
 @code{nl_langinfo} returns a string with the name of the coded character
 set used in the selected locale.
 
+@comment langinfo.h
+@comment XOPEN
 @item ABDAY_1
+@comment langinfo.h
+@comment XOPEN
 @itemx ABDAY_2
+@comment langinfo.h
+@comment XOPEN
 @itemx ABDAY_3
+@comment langinfo.h
+@comment XOPEN
 @itemx ABDAY_4
+@comment langinfo.h
+@comment XOPEN
 @itemx ABDAY_5
+@comment langinfo.h
+@comment XOPEN
 @itemx ABDAY_6
+@comment langinfo.h
+@comment XOPEN
 @itemx ABDAY_7
 @code{nl_langinfo} returns the abbreviated weekday name.  @code{ABDAY_1}
 corresponds to Sunday.
+@comment langinfo.h
+@comment XOPEN
 @item DAY_1
+@comment langinfo.h
+@comment XOPEN
 @itemx DAY_2
+@comment langinfo.h
+@comment XOPEN
 @itemx DAY_3
+@comment langinfo.h
+@comment XOPEN
 @itemx DAY_4
+@comment langinfo.h
+@comment XOPEN
 @itemx DAY_5
+@comment langinfo.h
+@comment XOPEN
 @itemx DAY_6
+@comment langinfo.h
+@comment XOPEN
 @itemx DAY_7
 Similar to @code{ABDAY_1} etc., but here the return value is the
 unabbreviated weekday name.
+@comment langinfo.h
+@comment XOPEN
 @item ABMON_1
+@comment langinfo.h
+@comment XOPEN
 @itemx ABMON_2
+@comment langinfo.h
+@comment XOPEN
 @itemx ABMON_3
+@comment langinfo.h
+@comment XOPEN
 @itemx ABMON_4
+@comment langinfo.h
+@comment XOPEN
 @itemx ABMON_5
+@comment langinfo.h
+@comment XOPEN
 @itemx ABMON_6
+@comment langinfo.h
+@comment XOPEN
 @itemx ABMON_7
+@comment langinfo.h
+@comment XOPEN
 @itemx ABMON_8
+@comment langinfo.h
+@comment XOPEN
 @itemx ABMON_9
+@comment langinfo.h
+@comment XOPEN
 @itemx ABMON_10
+@comment langinfo.h
+@comment XOPEN
 @itemx ABMON_11
+@comment langinfo.h
+@comment XOPEN
 @itemx ABMON_12
 The return value is abbreviated name of the month.  @code{ABMON_1}
 corresponds to January.
+@comment langinfo.h
+@comment XOPEN
 @item MON_1
+@comment langinfo.h
+@comment XOPEN
 @itemx MON_2
+@comment langinfo.h
+@comment XOPEN
 @itemx MON_3
+@comment langinfo.h
+@comment XOPEN
 @itemx MON_4
+@comment langinfo.h
+@comment XOPEN
 @itemx MON_5
+@comment langinfo.h
+@comment XOPEN
 @itemx MON_6
+@comment langinfo.h
+@comment XOPEN
 @itemx MON_7
+@comment langinfo.h
+@comment XOPEN
 @itemx MON_8
+@comment langinfo.h
+@comment XOPEN
 @itemx MON_9
+@comment langinfo.h
+@comment XOPEN
 @itemx MON_10
+@comment langinfo.h
+@comment XOPEN
 @itemx MON_11
+@comment langinfo.h
+@comment XOPEN
 @itemx MON_12
 Similar to @code{ABMON_1} etc., but here the month names are not abbreviated.
 Here the first value @code{MON_1} also corresponds to January.
+@comment langinfo.h
+@comment XOPEN
 @item AM_STR
+@comment langinfo.h
+@comment XOPEN
 @itemx PM_STR
 The return values are strings which can be used in the representation of time
 as an hour from 1 to 12 plus an am/pm specifier.
@@ -973,15 +1055,23 @@  as an hour from 1 to 12 plus an am/pm specifier.
 Note that in locales which do not use this time representation
 these strings might be empty, in which case the am/pm format
 cannot be used at all.
+@comment langinfo.h
+@comment XOPEN
 @item D_T_FMT
 The return value can be used as a format string for @code{strftime} to
 represent time and date in a locale-specific way.
+@comment langinfo.h
+@comment XOPEN
 @item D_FMT
 The return value can be used as a format string for @code{strftime} to
 represent a date in a locale-specific way.
+@comment langinfo.h
+@comment XOPEN
 @item T_FMT
 The return value can be used as a format string for @code{strftime} to
 represent time in a locale-specific way.
+@comment langinfo.h
+@comment XOPEN
 @item T_FMT_AMPM
 The return value can be used as a format string for @code{strftime} to
 represent time in the am/pm format.
@@ -989,6 +1079,8 @@  represent time in the am/pm format.
 Note that if the am/pm format does not make any sense for the
 selected locale, the return value might be the same as the one for
 @code{T_FMT}.
+@comment langinfo.h
+@comment XOPEN
 @item ERA
 The return value represents the era used in the current locale.
 
@@ -1002,18 +1094,28 @@  Specifying the @code{E} modifier in their format strings causes the
 @code{strftime} functions to use this information.  The format of the
 returned string is not specified, and therefore you should not assume
 knowledge of it on different systems.
+@comment langinfo.h
+@comment GNU
 @item ERA_YEAR
 The return value gives the year in the relevant era of the locale.
 As for @code{ERA} it should not be necessary to use this value directly.
+@comment langinfo.h
+@comment XOPEN
 @item ERA_D_T_FMT
 This return value can be used as a format string for @code{strftime} to
 represent dates and times in a locale-specific era-based way.
+@comment langinfo.h
+@comment XOPEN
 @item ERA_D_FMT
 This return value can be used as a format string for @code{strftime} to
 represent a date in a locale-specific era-based way.
+@comment langinfo.h
+@comment XOPEN
 @item ERA_T_FMT
 This return value can be used as a format string for @code{strftime} to
 represent time in a locale-specific era-based way.
+@comment langinfo.h
+@comment XOPEN
 @item ALT_DIGITS
 The return value is a representation of up to @math{100} values used to
 represent the values @math{0} to @math{99}.  As for @code{ERA} this
@@ -1022,98 +1124,158 @@  through the @code{strftime} function.  When the modifier @code{O} is
 used in a format which would otherwise use numerals to represent hours,
 minutes, seconds, weekdays, months, or weeks, the appropriate value for
 the locale is used instead.
+@comment langinfo.h
+@comment GNU
 @item INT_CURR_SYMBOL
 The same as the value returned by @code{localeconv} in the
 @code{int_curr_symbol} element of the @code{struct lconv}.
+@comment langinfo.h
+@comment GNU
 @item CURRENCY_SYMBOL
+@comment langinfo.h
+@comment Unix98
 @itemx CRNCYSTR
 The same as the value returned by @code{localeconv} in the
 @code{currency_symbol} element of the @code{struct lconv}.
 
 @code{CRNCYSTR} is a deprecated alias still required by Unix98.
+@comment langinfo.h
+@comment GNU
 @item MON_DECIMAL_POINT
 The same as the value returned by @code{localeconv} in the
 @code{mon_decimal_point} element of the @code{struct lconv}.
+@comment langinfo.h
+@comment GNU
 @item MON_THOUSANDS_SEP
 The same as the value returned by @code{localeconv} in the
 @code{mon_thousands_sep} element of the @code{struct lconv}.
+@comment langinfo.h
+@comment GNU
 @item MON_GROUPING
 The same as the value returned by @code{localeconv} in the
 @code{mon_grouping} element of the @code{struct lconv}.
+@comment langinfo.h
+@comment GNU
 @item POSITIVE_SIGN
 The same as the value returned by @code{localeconv} in the
 @code{positive_sign} element of the @code{struct lconv}.
+@comment langinfo.h
+@comment GNU
 @item NEGATIVE_SIGN
 The same as the value returned by @code{localeconv} in the
 @code{negative_sign} element of the @code{struct lconv}.
+@comment langinfo.h
+@comment GNU
 @item INT_FRAC_DIGITS
 The same as the value returned by @code{localeconv} in the
 @code{int_frac_digits} element of the @code{struct lconv}.
+@comment langinfo.h
+@comment GNU
 @item FRAC_DIGITS
 The same as the value returned by @code{localeconv} in the
 @code{frac_digits} element of the @code{struct lconv}.
+@comment langinfo.h
+@comment GNU
 @item P_CS_PRECEDES
 The same as the value returned by @code{localeconv} in the
 @code{p_cs_precedes} element of the @code{struct lconv}.
+@comment langinfo.h
+@comment GNU
 @item P_SEP_BY_SPACE
 The same as the value returned by @code{localeconv} in the
 @code{p_sep_by_space} element of the @code{struct lconv}.
+@comment langinfo.h
+@comment GNU
 @item N_CS_PRECEDES
 The same as the value returned by @code{localeconv} in the
 @code{n_cs_precedes} element of the @code{struct lconv}.
+@comment langinfo.h
+@comment GNU
 @item N_SEP_BY_SPACE
 The same as the value returned by @code{localeconv} in the
 @code{n_sep_by_space} element of the @code{struct lconv}.
+@comment langinfo.h
+@comment GNU
 @item P_SIGN_POSN
 The same as the value returned by @code{localeconv} in the
 @code{p_sign_posn} element of the @code{struct lconv}.
+@comment langinfo.h
+@comment GNU
 @item N_SIGN_POSN
 The same as the value returned by @code{localeconv} in the
 @code{n_sign_posn} element of the @code{struct lconv}.
 
+@comment langinfo.h
+@comment GNU
 @item INT_P_CS_PRECEDES
 The same as the value returned by @code{localeconv} in the
 @code{int_p_cs_precedes} element of the @code{struct lconv}.
+@comment langinfo.h
+@comment GNU
 @item INT_P_SEP_BY_SPACE
 The same as the value returned by @code{localeconv} in the
 @code{int_p_sep_by_space} element of the @code{struct lconv}.
+@comment langinfo.h
+@comment GNU
 @item INT_N_CS_PRECEDES
 The same as the value returned by @code{localeconv} in the
 @code{int_n_cs_precedes} element of the @code{struct lconv}.
+@comment langinfo.h
+@comment GNU
 @item INT_N_SEP_BY_SPACE
 The same as the value returned by @code{localeconv} in the
 @code{int_n_sep_by_space} element of the @code{struct lconv}.
+@comment langinfo.h
+@comment GNU
 @item INT_P_SIGN_POSN
 The same as the value returned by @code{localeconv} in the
 @code{int_p_sign_posn} element of the @code{struct lconv}.
+@comment langinfo.h
+@comment GNU
 @item INT_N_SIGN_POSN
 The same as the value returned by @code{localeconv} in the
 @code{int_n_sign_posn} element of the @code{struct lconv}.
 
+@comment langinfo.h
+@comment GNU
 @item DECIMAL_POINT
+@comment langinfo.h
+@comment Unix98
 @itemx RADIXCHAR
 The same as the value returned by @code{localeconv} in the
 @code{decimal_point} element of the @code{struct lconv}.
 
 The name @code{RADIXCHAR} is a deprecated alias still used in Unix98.
+@comment langinfo.h
+@comment GNU
 @item THOUSANDS_SEP
+@comment langinfo.h
+@comment Unix98
 @itemx THOUSEP
 The same as the value returned by @code{localeconv} in the
 @code{thousands_sep} element of the @code{struct lconv}.
 
 The name @code{THOUSEP} is a deprecated alias still used in Unix98.
+@comment langinfo.h
+@comment GNU
 @item GROUPING
 The same as the value returned by @code{localeconv} in the
 @code{grouping} element of the @code{struct lconv}.
+@comment langinfo.h
+@comment XOPEN
 @item YESEXPR
 The return value is a regular expression which can be used with the
 @code{regex} function to recognize a positive response to a yes/no
 question.  @Theglibc{} provides the @code{rpmatch} function for
 easier handling in applications.
+@comment langinfo.h
+@comment XOPEN
 @item NOEXPR
 The return value is a regular expression which can be used with the
 @code{regex} function to recognize a negative response to a yes/no
 question.
+@comment langinfo.h
+@comment GNU || (XOPEN && !XOPEN2K)
 @item YESSTR
 The return value is a locale-specific translation of the positive response
 to a yes/no question.
@@ -1124,6 +1286,8 @@  translation functions (@pxref{Message Translation}).
 
 The use of this symbol is deprecated.  Instead message translation
 should be used.
+@comment langinfo.h
+@comment GNU || (XOPEN && !XOPEN2K)
 @item NOSTR
 The return value is a locale-specific translation of the negative response
 to a yes/no question.  What is said for @code{YESSTR} is also true here.
@@ -1192,6 +1356,8 @@  Therefore the X/Open standards introduce a function which uses such
 locale information, making it easier for the user to format
 numbers according to these rules.
 
+@comment monetary.h
+@comment XOPEN
 @deftypefun ssize_t strfmon (char *@var{s}, size_t @var{maxsize}, const char *@var{format}, @dots{})
 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
 @c It (and strfmon_l) both call vstrfmon_l, which, besides accessing the
diff --git a/manual/math.texi b/manual/math.texi
index b4bb323..f5d8d09 100644
--- a/manual/math.texi
+++ b/manual/math.texi
@@ -77,30 +77,56 @@  All values are defined as preprocessor macros starting with @code{M_}.
 The values provided are:
 
 @vtable @code
+@comment math.h
+@comment MISC || XOPEN
 @item M_E
 The base of natural logarithms.
+@comment math.h
+@comment MISC || XOPEN
 @item M_LOG2E
 The logarithm to base @code{2} of @code{M_E}.
+@comment math.h
+@comment MISC || XOPEN
 @item M_LOG10E
 The logarithm to base @code{10} of @code{M_E}.
+@comment math.h
+@comment MISC || XOPEN
 @item M_LN2
 The natural logarithm of @code{2}.
+@comment math.h
+@comment MISC || XOPEN
 @item M_LN10
 The natural logarithm of @code{10}.
+@comment math.h
+@comment MISC || XOPEN
 @item M_PI
 Pi, the ratio of a circle's circumference to its diameter.
+@comment math.h
+@comment MISC || XOPEN
 @item M_PI_2
 Pi divided by two.
+@comment math.h
+@comment MISC || XOPEN
 @item M_PI_4
 Pi divided by four.
+@comment math.h
+@comment MISC || XOPEN
 @item M_1_PI
 The reciprocal of pi (1/pi)
+@comment math.h
+@comment MISC || XOPEN
 @item M_2_PI
 Two times the reciprocal of pi.
+@comment math.h
+@comment MISC || XOPEN
 @item M_2_SQRTPI
 Two times the reciprocal of the square root of pi.
+@comment math.h
+@comment MISC || XOPEN
 @item M_SQRT2
 The square root of two.
+@comment math.h
+@comment MISC || XOPEN
 @item M_SQRT1_2
 The reciprocal of the square root of two (also the square root of 1/2).
 @end vtable
diff --git a/manual/memory.texi b/manual/memory.texi
index 38d3c3a..da0896b 100644
--- a/manual/memory.texi
+++ b/manual/memory.texi
@@ -920,6 +920,7 @@  power of two than that, use @code{aligned_alloc} or @code{posix_memalign}.
 @file{stdlib.h}.
 
 @comment stdlib.h
+@comment ISOC11
 @deftypefun {void *} aligned_alloc (size_t @var{alignment}, size_t @var{size})
 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
 @c Alias to memalign.
@@ -1077,6 +1078,8 @@  You can adjust some parameters for dynamic memory allocation with the
 interface, defined in @file{malloc.h}.
 @pindex malloc.h
 
+@comment malloc.h
+@comment SVID/XPG
 @deftypefun int mallopt (int @var{param}, int @var{value})
 @safety{@prelim{}@mtunsafe{@mtuinit{} @mtasuconst{:mallopt}}@asunsafe{@asuinit{} @asulock{}}@acunsafe{@acuinit{} @aculock{}}}
 @c __libc_mallopt @mtuinit @mtasuconst:mallopt @asuinit @asulock @aculock
@@ -1092,6 +1095,8 @@  choices for @var{param}, as defined in @file{malloc.h}, are:
 
 @comment TODO: @item M_CHECK_ACTION
 @vtable @code
+@comment malloc.h
+@comment ???
 @item M_MMAP_MAX
 The maximum number of chunks to allocate with @code{mmap}.  Setting this
 to zero disables all use of @code{mmap}.
@@ -1101,6 +1106,8 @@  The default value of this parameter is @code{65536}.
 This parameter can also be set for the process at startup by setting the
 environment variable @env{MALLOC_MMAP_MAX_} to the desired value.
 
+@comment malloc.h
+@comment ???
 @item M_MMAP_THRESHOLD
 All chunks larger than this value are allocated outside the normal
 heap, using the @code{mmap} system call.  This way it is guaranteed
@@ -1117,6 +1124,8 @@  This parameter can also be set for the process at startup by setting the
 environment variable @env{MALLOC_MMAP_THRESHOLD_} to the desired value.
 @comment TODO: @item M_MXFAST
 
+@comment malloc.h
+@comment ???
 @item M_PERTURB
 If non-zero, memory blocks are filled with values depending on some
 low order bits of this parameter when they are allocated (except when
@@ -1131,6 +1140,8 @@  The default value of this parameter is @code{0}.
 This parameter can also be set for the process at startup by setting the
 environment variable @env{MALLOC_MMAP_PERTURB_} to the desired value.
 
+@comment malloc.h
+@comment ???
 @item M_TOP_PAD
 This parameter determines the amount of extra memory to obtain from the system
 when an arena needs to be extended.  It also specifies the number of bytes to
@@ -1142,6 +1153,8 @@  The default value of this parameter is @code{0}.
 This parameter can also be set for the process at startup by setting the
 environment variable @env{MALLOC_TOP_PAD_} to the desired value.
 
+@comment malloc.h
+@comment ???
 @item M_TRIM_THRESHOLD
 This is the minimum size (in bytes) of the top-most, releasable chunk
 that will trigger a system call in order to return memory to the system.
@@ -1154,6 +1167,8 @@  value is set statically to the provided input.
 This parameter can also be set for the process at startup by setting the
 environment variable @env{MALLOC_TRIM_THRESHOLD_} to the desired value.
 
+@comment malloc.h
+@comment ???
 @item M_ARENA_TEST
 This parameter specifies the number of arenas that can be created before the
 test on the limit to the number of arenas is conducted. The value is ignored if
@@ -1165,6 +1180,8 @@  systems.
 This parameter can also be set for the process at startup by setting the
 environment variable @env{MALLOC_ARENA_TEST} to the desired value.
 
+@comment malloc.h
+@comment ???
 @item M_ARENA_MAX
 This parameter sets the number of arenas to use regardless of the number of
 cores in the system.
@@ -1247,6 +1264,8 @@  must be called before the first such function.
 
 @end deftypefun
 
+@comment mcheck.h
+@comment ???
 @deftypefun {enum mcheck_status} mprobe (void *@var{pointer})
 @safety{@prelim{}@mtunsafe{@mtasurace{:mcheck} @mtasuconst{:malloc_hooks}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
 @c The linked list of headers may be modified concurrently by other
@@ -1271,6 +1290,8 @@  or @code{realloc}.  @code{mprobe} returns a value that says what
 inconsistency, if any, was found.  The values are described below.
 @end deftypefun
 
+@comment mcheck.h
+@comment ???
 @deftp {Data Type} {enum mcheck_status}
 This enumerated type describes what kind of inconsistency was detected
 in an allocated block, if any.  Here are the possible values:
@@ -3215,10 +3236,14 @@  other bits must be zero.
 
 @vtable @code
 
+@comment sys/mman.h
+@comment BSD, POSIX
 @item MCL_CURRENT
 Lock all pages which currently exist in the calling process' virtual
 address space.
 
+@comment sys/mman.h
+@comment BSD, POSIX
 @item MCL_FUTURE
 Set a mode such that any pages added to the process' virtual address
 space in the future will be locked from birth.  This mode does not
diff --git a/manual/message.texi b/manual/message.texi
index 2dae3ed..21317b3 100644
--- a/manual/message.texi
+++ b/manual/message.texi
@@ -267,6 +267,8 @@  The @code{catopen} function directly reads the values of the environment
 variables.
 
 
+@comment nl_types.h
+@comment XOPEN
 @deftypefun {char *} catgets (nl_catd @var{catalog_desc}, int @var{set}, int @var{message}, const char *@var{string})
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 The function @code{catgets} has to be used to access the message catalog
@@ -306,6 +308,8 @@  between several people working on the same project must be coordinated.
 We will see how some of these problems can be relaxed a bit (@pxref{Common
 Usage}).
 
+@comment nl_types.h
+@comment XOPEN
 @deftypefun int catclose (nl_catd @var{catalog_desc})
 @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{}}}
 @c catclose @ascuheap @acucorrupt @acsmem
diff --git a/manual/nss.texi b/manual/nss.texi
index ee70ad3..8c3f859 100644
--- a/manual/nss.texi
+++ b/manual/nss.texi
@@ -451,15 +451,23 @@  function returns a pointer to the result the reentrant function return
 an @code{enum nss_status} value:
 
 @vtable @code
+@comment nss.h
+@comment ???
 @item NSS_STATUS_TRYAGAIN
 numeric value @code{-2}
 
+@comment nss.h
+@comment ???
 @item NSS_STATUS_UNAVAIL
 numeric value @code{-1}
 
+@comment nss.h
+@comment ???
 @item NSS_STATUS_NOTFOUND
 numeric value @code{0}
 
+@comment nss.h
+@comment ???
 @item NSS_STATUS_SUCCESS
 numeric value @code{1}
 @end vtable
diff --git a/manual/pattern.texi b/manual/pattern.texi
index 30a76c8..9b3ff84 100644
--- a/manual/pattern.texi
+++ b/manual/pattern.texi
@@ -202,13 +202,19 @@  implementation contains some more fields which are non-standard
 extensions.
 
 @table @code
+@comment glob.h
+@comment POSIX.2
 @item gl_pathc
 The number of elements in the vector, excluding the initial null entries
 if the GLOB_DOOFFS flag is used (see gl_offs below).
 
+@comment glob.h
+@comment POSIX.2
 @item gl_pathv
 The address of the vector.  This field has type @w{@code{char **}}.
 
+@comment glob.h
+@comment POSIX.2
 @item gl_offs
 The offset of the first real element of the vector, from its nominal
 address in the @code{gl_pathv} field.  Unlike the other fields, this
@@ -223,6 +229,8 @@  The @code{gl_offs} field is meaningful only if you use the
 regardless of what is in this field, and the first real element comes at
 the beginning of the vector.
 
+@comment glob.h
+@comment GNU
 @item gl_closedir
 The address of an alternative implementation of the @code{closedir}
 function.  It is used if the @code{GLOB_ALTDIRFUNC} bit is set in
@@ -231,6 +239,8 @@  the flag parameter.  The type of this field is
 
 This is a GNU extension.
 
+@comment glob.h
+@comment GNU
 @item gl_readdir
 The address of an alternative implementation of the @code{readdir}
 function used to read the contents of a directory.  It is used if the
@@ -276,6 +286,8 @@  function, and deallocate it in the @code{gl_closedir} callback function.
 
 The @code{gl_readdir} member is a GNU extension.
 
+@comment glob.h
+@comment GNU
 @item gl_opendir
 The address of an alternative implementation of the @code{opendir}
 function.  It is used if the @code{GLOB_ALTDIRFUNC} bit is set in
@@ -284,6 +296,8 @@  the flag parameter.  The type of this field is
 
 This is a GNU extension.
 
+@comment glob.h
+@comment GNU
 @item gl_stat
 The address of an alternative implementation of the @code{stat} function
 to get information about an object in the filesystem.  It is used if the
@@ -292,6 +306,8 @@  this field is @w{@code{int (*) (const char *, struct stat *)}}.
 
 This is a GNU extension.
 
+@comment glob.h
+@comment GNU
 @item gl_lstat
 The address of an alternative implementation of the @code{lstat}
 function to get information about an object in the filesystems, not
@@ -301,6 +317,8 @@  is set in the flag parameter.  The type of this field is @code{@w{int
 
 This is a GNU extension.
 
+@comment glob.h
+@comment GNU
 @item gl_flags
 The flags used when @code{glob} was called.  In addition, @code{GLOB_MAGCHAR}
 might be set.  See @ref{Flags for Globbing} for more details.
@@ -323,13 +341,19 @@  implementation contains some more fields which are non-standard
 extensions.
 
 @table @code
+@comment glob.h
+@comment POSIX.2
 @item gl_pathc
 The number of elements in the vector, excluding the initial null entries
 if the GLOB_DOOFFS flag is used (see gl_offs below).
 
+@comment glob.h
+@comment POSIX.2
 @item gl_pathv
 The address of the vector.  This field has type @w{@code{char **}}.
 
+@comment glob.h
+@comment POSIX.2
 @item gl_offs
 The offset of the first real element of the vector, from its nominal
 address in the @code{gl_pathv} field.  Unlike the other fields, this
@@ -344,6 +368,8 @@  The @code{gl_offs} field is meaningful only if you use the
 regardless of what is in this field, and the first real element comes at
 the beginning of the vector.
 
+@comment glob.h
+@comment GNU
 @item gl_closedir
 The address of an alternative implementation of the @code{closedir}
 function.  It is used if the @code{GLOB_ALTDIRFUNC} bit is set in
@@ -352,6 +378,8 @@  the flag parameter.  The type of this field is
 
 This is a GNU extension.
 
+@comment glob.h
+@comment GNU
 @item gl_readdir
 The address of an alternative implementation of the @code{readdir64}
 function used to read the contents of a directory.  It is used if the
@@ -360,6 +388,8 @@  this field is @w{@code{struct dirent64 *(*) (void *)}}.
 
 This is a GNU extension.
 
+@comment glob.h
+@comment GNU
 @item gl_opendir
 The address of an alternative implementation of the @code{opendir}
 function.  It is used if the @code{GLOB_ALTDIRFUNC} bit is set in
@@ -368,6 +398,8 @@  the flag parameter.  The type of this field is
 
 This is a GNU extension.
 
+@comment glob.h
+@comment GNU
 @item gl_stat
 The address of an alternative implementation of the @code{stat64} function
 to get information about an object in the filesystem.  It is used if the
@@ -376,6 +408,8 @@  this field is @w{@code{int (*) (const char *, struct stat64 *)}}.
 
 This is a GNU extension.
 
+@comment glob.h
+@comment GNU
 @item gl_lstat
 The address of an alternative implementation of the @code{lstat64}
 function to get information about an object in the filesystems, not
@@ -385,6 +419,8 @@  is set in the flag parameter.  The type of this field is @code{@w{int
 
 This is a GNU extension.
 
+@comment glob.h
+@comment GNU
 @item gl_flags
 The flags used when @code{glob} was called.  In addition, @code{GLOB_MAGCHAR}
 might be set.  See @ref{Flags for Globbing} for more details.
diff --git a/manual/platform.texi b/manual/platform.texi
index cb16664..ccbe73c 100644
--- a/manual/platform.texi
+++ b/manual/platform.texi
@@ -14,6 +14,8 @@ 
 Facilities specific to PowerPC that are not specific to a particular
 operating system are declared in @file{sys/platform/ppc.h}.
 
+@comment sys/platform/ppc.h
+@comment ???
 @deftypefun {uint64_t} __ppc_get_timebase (void)
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 Read the current value of the Time Base Register.
@@ -28,6 +30,8 @@  without requiring assistance from the operating system, so it is very
 efficient.
 @end deftypefun
 
+@comment sys/platform/ppc.h
+@comment ???
 @deftypefun {uint64_t} __ppc_get_timebase_freq (void)
 @safety{@prelim{}@mtunsafe{@mtuinit{}}@asunsafe{@asucorrupt{:init}}@acunsafe{@acucorrupt{:init}}}
 @c __ppc_get_timebase_freq=__get_timebase_freq @mtuinit @acsfd
@@ -53,12 +57,16 @@  waiting on a lock intends to divert the shared resources to be used by other
 processors.  More information is available in @cite{Power ISA 2.06b - Book II -
 Section 3.2}.
 
+@comment sys/platform/ppc.h
+@comment ???
 @deftypefun {void} __ppc_yield (void)
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 Provide a hint that performance will probably be improved if shared resources
 dedicated to the executing processor are released for use by other processors.
 @end deftypefun
 
+@comment sys/platform/ppc.h
+@comment ???
 @deftypefun {void} __ppc_mdoio (void)
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 Provide a hint that performance will probably be improved if shared resources
@@ -66,6 +74,8 @@  dedicated to the executing processor are released until all outstanding storage
 accesses to caching-inhibited storage have been completed.
 @end deftypefun
 
+@comment sys/platform/ppc.h
+@comment ???
 @deftypefun {void} __ppc_mdoom (void)
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 Provide a hint that performance will probably be improved if shared resources
@@ -74,6 +84,8 @@  accesses to cacheable storage for which the data is not in the cache have been
 completed.
 @end deftypefun
 
+@comment sys/platform/ppc.h
+@comment ???
 @deftypefun {void} __ppc_set_ppr_med (void)
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 Set the Program Priority Register to medium value (default).
@@ -88,11 +100,15 @@  and @code{__ppc_set_ppc_med_low} (medium low).  More information
 available in @cite{Power ISA 2.06b - Book II - Section 3.1}.
 @end deftypefun
 
+@comment sys/platform/ppc.h
+@comment ???
 @deftypefun {void} __ppc_set_ppr_low (void)
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 Set the Program Priority Register to low value.
 @end deftypefun
 
+@comment sys/platform/ppc.h
+@comment ???
 @deftypefun {void} __ppc_set_ppr_med_low (void)
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 Set the Program Priority Register to medium low value.
@@ -102,11 +118,15 @@  Power ISA 2.07 extends the priorities that can be set to the Program Priority
 Register (PPR).  The following functions implement the new priority levels:
 very low and medium high.
 
+@comment sys/platform/ppc.h
+@comment ???
 @deftypefun {void} __ppc_set_ppr_very_low (void)
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 Set the Program Priority Register to very low value.
 @end deftypefun
 
+@comment sys/platform/ppc.h
+@comment ???
 @deftypefun {void} __ppc_set_ppr_med_high (void)
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 Set the Program Priority Register to medium high value.  The medium high
diff --git a/manual/process.texi b/manual/process.texi
index 085fdec..51d62ae 100644
--- a/manual/process.texi
+++ b/manual/process.texi
@@ -595,12 +595,16 @@  to the @code{waitpid} function.
 
 @comment Extra blank lines make it look better.
 @vtable @code
+@comment sys/wait.h
+@comment MISC
 @item WAIT_ANY
 
 This constant macro (whose value is @code{-1}) specifies that
 @code{waitpid} should return status information about any child process.
 
 
+@comment sys/wait.h
+@comment MISC
 @item WAIT_MYPGRP
 This constant (with value @code{0}) specifies that @code{waitpid} should
 return status information about any child process in the same process
@@ -612,11 +616,15 @@  argument to the @code{waitpid} function.  You can bitwise-OR the flags
 together to obtain a value to use as the argument.
 
 @vtable @code
+@comment sys/wait.h
+@comment POSIX.1
 @item WNOHANG
 
 This flag specifies that @code{waitpid} should return immediately
 instead of waiting, if there is no child process ready to be noticed.
 
+@comment sys/wait.h
+@comment POSIX.1
 @item WUNTRACED
 
 This flag specifies that @code{waitpid} should report the status of any
diff --git a/manual/resource.texi b/manual/resource.texi
index bf93375..2132e06 100644
--- a/manual/resource.texi
+++ b/manual/resource.texi
@@ -133,6 +133,7 @@  scheduled).
 @pindex sys/vtimes.h
 
 @comment sys/vtimes.h
+@comment ???
 @deftypefun int vtimes (struct vtimes *@var{current}, struct vtimes *@var{child})
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 @c Calls getrusage twice.
@@ -145,6 +146,8 @@  the invoking process alone in the structure to which it points.  If
 past children (which have terminated) of the invoking process in the structure
 to which it points.
 
+@comment sys/vtimes.h
+@comment ???
 @deftp {Data Type} {struct vtimes}
 This data type contains information about the resource usage of a process.
 Each member corresponds to a member of the @code{struct rusage} data type
@@ -398,6 +401,8 @@  with @code{EAGAIN}.  @xref{Creating a Process}.
 @comment sys/resource.h
 @comment BSD
 @item RLIMIT_NOFILE
+@comment sys/resource.h
+@comment BSD
 @itemx RLIMIT_OFILE
 The maximum number of files that the process can open.  If it tries to
 open more files than this, its open attempt fails with @code{errno}
@@ -452,9 +457,13 @@  the limit.
 The @var{cmd} values and the operations they specify are:
 @vtable @code
 
+@comment ulimit.h
+@comment BSD
 @item GETFSIZE
 Get the current limit on the size of a file, in units of 512 bytes.
 
+@comment ulimit.h
+@comment BSD
 @item SETFSIZE
 Set the current and maximum limit on the size of a file to @var{limit} *
 512 bytes.
@@ -495,16 +504,28 @@  A process tried to increase a maximum limit, but is not superuser.
 @var{resource} identifies the resource:
 
 @vtable @code
+@comment sys/vlimit.h
+@comment BSD
 @item LIM_CPU
 Maximum CPU time.  Same as @code{RLIMIT_CPU} for @code{setrlimit}.
+@comment sys/vlimit.h
+@comment BSD
 @item LIM_FSIZE
 Maximum file size.  Same as @code{RLIMIT_FSIZE} for @code{setrlimit}.
+@comment sys/vlimit.h
+@comment BSD
 @item LIM_DATA
 Maximum data memory.  Same as @code{RLIMIT_DATA} for @code{setrlimit}.
+@comment sys/vlimit.h
+@comment BSD
 @item LIM_STACK
 Maximum stack size.  Same as @code{RLIMIT_STACK} for @code{setrlimit}.
+@comment sys/vlimit.h
+@comment BSD
 @item LIM_CORE
 Maximum core file size.  Same as @code{RLIMIT_COR} for @code{setrlimit}.
+@comment sys/vlimit.h
+@comment BSD
 @item LIM_MAXRSS
 Maximum physical memory.  Same as @code{RLIMIT_RSS} for @code{setrlimit}.
 @end vtable
@@ -801,10 +822,16 @@  negative, @code{sched_setscheduler} keeps the existing scheduling policy.
 The following macros represent the valid values for @var{policy}:
 
 @vtable @code
+@comment sched.h
+@comment POSIX
 @item SCHED_OTHER
 Traditional Scheduling
+@comment sched.h
+@comment POSIX
 @item SCHED_FIFO
 First In First Out
+@comment sched.h
+@comment POSIX
 @item SCHED_RR
 Round Robin
 @end vtable
diff --git a/manual/search.texi b/manual/search.texi
index 1d9628d..3a80bae 100644
--- a/manual/search.texi
+++ b/manual/search.texi
@@ -332,6 +332,8 @@  used until the end of the program run.
 Entries of the hashing table and keys for the search are defined using
 this type:
 
+@comment search.h
+@comment SVID
 @deftp {Data type} {struct ENTRY}
 Both elements of this structure are pointers to zero-terminated strings.
 This is a limiting restriction of the functionality of the
@@ -591,6 +593,8 @@  which corresponds to the depth of the current node in the tree.  The
 root node has the depth @math{0} and its children have a depth of
 @math{1} and so on.  The @code{VISIT} type is an enumeration type.
 
+@comment search.h
+@comment SVID
 @deftp {Data Type} VISIT
 The @code{VISIT} value indicates the status of the current node in the
 tree and how the function is called.  The status of a node is either
@@ -601,15 +605,23 @@  after both children are processed.  This makes it possible to handle all
 three methods of tree traversal (or even a combination of them).
 
 @vtable @code
+@comment search.h
+@comment SVID
 @item preorder
 The current node is an internal node and the function is called before
 the first child was processed.
+@comment search.h
+@comment SVID
 @item postorder
 The current node is an internal node and the function is called after
 the first child was processed.
+@comment search.h
+@comment SVID
 @item endorder
 The current node is an internal node and the function is called after
 the second child was processed.
+@comment search.h
+@comment SVID
 @item leaf
 The current node is a leaf.
 @end vtable
diff --git a/manual/signal.texi b/manual/signal.texi
index 79e190d..c4335f4 100644
--- a/manual/signal.texi
+++ b/manual/signal.texi
@@ -1012,6 +1012,8 @@  The second argument, @var{action}, specifies the action to use for the
 signal @var{signum}.  This can be one of the following:
 
 @table @code
+@comment signal.h
+@comment ISO
 @item SIG_DFL
 @vindex SIG_DFL
 @cindex default action for a signal
@@ -1019,6 +1021,8 @@  signal @var{signum}.  This can be one of the following:
 The default actions for various kinds of signals are stated in
 @ref{Standard Signals}.
 
+@comment signal.h
+@comment ISO
 @item SIG_IGN
 @vindex SIG_IGN
 @cindex ignore action for a signal
@@ -3196,10 +3200,14 @@  There are two macros defined in @file{signal.h} that you should use in
 calculating this size:
 
 @vtable @code
+@comment signal.h
+@comment XOPEN
 @item SIGSTKSZ
 This is the canonical size for a signal stack.  It is judged to be
 sufficient for normal uses.
 
+@comment signal.h
+@comment XOPEN
 @item MINSIGSTKSZ
 This is the amount of signal stack space the operating system needs just
 to implement signal delivery.  The size of a signal stack @strong{must}
@@ -3216,9 +3224,13 @@  stack and increase @code{ss_size} accordingly.
 This field contains the bitwise @sc{or} of these flags:
 
 @vtable @code
+@comment signal.h
+@comment XOPEN
 @item SS_DISABLE
 This tells the system that it should not use the signal stack.
 
+@comment signal.h
+@comment XOPEN
 @item SS_ONSTACK
 This is set by the system, and indicates that the signal stack is
 currently in use.  If this bit is not set, then signals will be
diff --git a/manual/socket.texi b/manual/socket.texi
index 24b4563..8bd272d 100644
--- a/manual/socket.texi
+++ b/manual/socket.texi
@@ -498,6 +498,7 @@  The following functions, constants and data types are declared in the
 header file @file{net/if.h}.
 
 @comment net/if.h
+@comment MISC
 @deftypevr Constant size_t IFNAMSIZ
 This constant defines the maximum buffer size needed to hold an
 interface name, including its terminating zero byte.
@@ -827,6 +828,8 @@  When you call @code{bind} or @code{getsockname}, you should specify
 @code{sizeof (struct sockaddr_in)} as the @var{length} parameter if
 you are using an IPv4 Internet namespace socket address.
 
+@comment netinet/in.h
+@comment IPv6 Basic API
 @deftp {Data Type} {struct sockaddr_in6}
 This is the data type used to represent socket addresses in the IPv6
 namespace.  It has the following members:
diff --git a/manual/startup.texi b/manual/startup.texi
index e4c983a..4bc428c 100644
--- a/manual/startup.texi
+++ b/manual/startup.texi
@@ -220,6 +220,7 @@  programming of code like this the function @code{getsubopt} is
 available.
 
 @comment stdlib.h
+@comment XOPEN_EXTENDED || XOPEN2K8
 @deftypefun int getsubopt (char **@var{optionp}, char *const *@var{tokens}, char **@var{valuep})
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 @c getsubopt ok
@@ -666,6 +667,7 @@  basis there may be information that is not available any other way.
 
 @subsection Definition of @code{getauxval}
 @comment sys/auxv.h
+@comment ???
 @deftypefun {unsigned long int} getauxval (unsigned long int @var{type})
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 @c Reads from hwcap or iterates over constant auxv.
diff --git a/manual/stdio.texi b/manual/stdio.texi
index 355c563..b7e24a2 100644
--- a/manual/stdio.texi
+++ b/manual/stdio.texi
@@ -682,17 +682,23 @@  reinstated using this function.  There are three values defined for the
 @var{type} parameter.
 
 @vtable @code
+@comment stdio_ext.h
+@comment SunOS
 @item FSETLOCKING_INTERNAL
 The stream @code{stream} will from now on use the default internal
 locking.  Every stream operation with exception of the @code{_unlocked}
 variants will implicitly lock the stream.
 
+@comment stdio_ext.h
+@comment SunOS
 @item FSETLOCKING_BYCALLER
 After the @code{__fsetlocking} function returns, the user is responsible
 for locking the stream.  None of the stream operations will implicitly
 do this anymore until the state is set back to
 @code{FSETLOCKING_INTERNAL}.
 
+@comment stdio_ext.h
+@comment SunOS
 @item FSETLOCKING_QUERY
 @code{__fsetlocking} only queries the current locking state of the
 stream.  The return value will be @code{FSETLOCKING_INTERNAL} or
@@ -1792,6 +1798,8 @@  The @var{param-no} parts of the format must be integers in the range of
 implementations limit this number to a certain upper bound.  The exact
 limit can be retrieved by the following constant.
 
+@comment limits.h
+@comment XOPEN
 @defvr Macro NL_ARGMAX
 The value of @code{NL_ARGMAX} is the maximum value allowed for the
 specification of a positional parameter in a @code{printf} call.  The
@@ -5370,8 +5378,12 @@  bitwise OR combined if wanted, for the @var{classification} parameter of
 @code{fmtmsg}:
 
 @vtable @code
+@comment fmtmsg.h
+@comment ???
 @item MM_PRINT
 Display the message in standard error.
+@comment fmtmsg.h
+@comment ???
 @item MM_CONSOLE
 Display the message on the system console.
 @end vtable
@@ -5381,10 +5393,16 @@  following values which also is bitwise ORed with the
 @var{classification} parameter to @code{fmtmsg}:
 
 @vtable @code
+@comment fmtmsg.h
+@comment ???
 @item MM_HARD
 The source of the condition is some hardware.
+@comment fmtmsg.h
+@comment ???
 @item MM_SOFT
 The source of the condition is some software.
+@comment fmtmsg.h
+@comment ???
 @item MM_FIRM
 The source of the condition is some firmware.
 @end vtable
@@ -5394,10 +5412,16 @@  can describe the part of the system which detects the problem.  This is
 done by using exactly one of the following values:
 
 @vtable @code
+@comment fmtmsg.h
+@comment ???
 @item MM_APPL
 The erroneous condition is detected by the application.
+@comment fmtmsg.h
+@comment ???
 @item MM_UTIL
 The erroneous condition is detected by a utility.
+@comment fmtmsg.h
+@comment ???
 @item MM_OPSYS
 The erroneous condition is detected by the operating system.
 @end vtable
@@ -5406,8 +5430,12 @@  A last component of @var{classification} can signal the results of this
 message.  Exactly one of the following values can be used:
 
 @vtable @code
+@comment fmtmsg.h
+@comment ???
 @item MM_RECOVER
 It is a recoverable error.
+@comment fmtmsg.h
+@comment ???
 @item MM_NRECOV
 It is a non-recoverable error.
 @end vtable
@@ -5431,17 +5459,29 @@  Each of the parameters can be a special value which means this value
 is to be omitted.  The symbolic names for these values are:
 
 @vtable @code
+@comment fmtmsg.h
+@comment ???
 @item MM_NULLLBL
 Ignore @var{label} parameter.
+@comment fmtmsg.h
+@comment ???
 @item MM_NULLSEV
 Ignore @var{severity} parameter.
+@comment fmtmsg.h
+@comment ???
 @item MM_NULLMC
 Ignore @var{classification} parameter.  This implies that nothing is
 actually printed.
+@comment fmtmsg.h
+@comment ???
 @item MM_NULLTXT
 Ignore @var{text} parameter.
+@comment fmtmsg.h
+@comment ???
 @item MM_NULLACT
 Ignore @var{action} parameter.
+@comment fmtmsg.h
+@comment ???
 @item MM_NULLTAG
 Ignore @var{tag} parameter.
 @end vtable
@@ -5455,14 +5495,24 @@  table:
 @cindex severity class
 
 @vtable @code
+@comment fmtmsg.h
+@comment ???
 @item MM_NOSEV
 Nothing is printed, this value is the same as @code{MM_NULLSEV}.
+@comment fmtmsg.h
+@comment ???
 @item MM_HALT
 This value is printed as @code{HALT}.
+@comment fmtmsg.h
+@comment ???
 @item MM_ERROR
 This value is printed as @code{ERROR}.
+@comment fmtmsg.h
+@comment ???
 @item MM_WARNING
 This value is printed as @code{WARNING}.
+@comment fmtmsg.h
+@comment ???
 @item MM_INFO
 This value is printed as @code{INFO}.
 @end vtable
@@ -5555,6 +5605,8 @@  introducing new classes in a running program.  One could use the
 @code{setenv} or @code{putenv} function to set the environment variable,
 but this is toilsome.
 
+@comment fmtmsg.h
+@comment MISC
 @deftypefun int addseverity (int @var{severity}, const char *@var{string})
 @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{}}}
 This function allows the introduction of new severity classes which can be
diff --git a/manual/string.texi b/manual/string.texi
index 1986357..8ccc964 100644
--- a/manual/string.texi
+++ b/manual/string.texi
@@ -574,6 +574,7 @@  including the terminating null wide character) into the string
 the strings overlap.  The return value is the value of @var{wto}.
 @end deftypefun
 
+@comment string.h
 @comment SVID
 @deftypefun {char *} strdup (const char *@var{s})
 @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
@@ -884,6 +885,7 @@  in their header conventions.  @xref{Copying Strings and Arrays}.  The
 and the @samp{wc} functions are declared in the file @file{wchar.h}.
 
 @comment string.h
+@comment ???
 @deftypefun {char *} strncpy (char *restrict @var{to}, const char *restrict @var{from}, size_t @var{size})
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 This function is similar to @code{strcpy} but always copies exactly
diff --git a/manual/sysinfo.texi b/manual/sysinfo.texi
index 9a8b79d..1a10013 100644
--- a/manual/sysinfo.texi
+++ b/manual/sysinfo.texi
@@ -457,15 +457,25 @@  filesystem is mounted.  @file{fstab} defines five macros to describe the
 possible values:
 
 @vtable @code
+@comment fstab.h
+@comment BSD
 @item FSTAB_RW
 The filesystem gets mounted with read and write enabled.
+@comment fstab.h
+@comment BSD
 @item FSTAB_RQ
 The filesystem gets mounted with read and write enabled.  Write access
 is restricted by quotas.
+@comment fstab.h
+@comment BSD
 @item FSTAB_RO
 The filesystem gets mounted read-only.
+@comment fstab.h
+@comment BSD
 @item FSTAB_SW
 This is not a real filesystem, it is a swap device.
+@comment fstab.h
+@comment BSD
 @item FSTAB_XX
 This entry from the @file{fstab} file is totally ignored.
 @end vtable
@@ -618,13 +628,19 @@  name one also knows the filesystem name.  Nevertheless here follows the
 list of the symbols provided in @file{mntent.h}.
 
 @vtable @code
+@comment mntent.h
+@comment ???
 @item MNTTYPE_IGNORE
 This symbol expands to @code{"ignore"}.  The value is sometimes used in
 @file{fstab} files to make sure entries are not used without removing them.
+@comment mntent.h
+@comment ???
 @item MNTTYPE_NFS
 Expands to @code{"nfs"}.  Using this macro sometimes could make sense
 since it names the default NFS implementation, in case both version 2
 and 3 are supported.
+@comment mntent.h
+@comment ???
 @item MNTTYPE_SWAP
 This symbol expands to @code{"swap"}.  It names the special @file{fstab}
 entry which names one of the possibly multiple swap partitions.
@@ -642,23 +658,35 @@  might be many more options which are possible so it doesn't make much sense
 to rely on these macros but to be consistent here is the list:
 
 @vtable @code
+@comment mntent.h
+@comment ???
 @item MNTOPT_DEFAULTS
 Expands to @code{"defaults"}.  This option should be used alone since it
 indicates all values for the customizable values are chosen to be the
 default.
+@comment mntent.h
+@comment ???
 @item MNTOPT_RO
 Expands to @code{"ro"}.  See the @code{FSTAB_RO} value, it means the
 filesystem is mounted read-only.
+@comment mntent.h
+@comment ???
 @item MNTOPT_RW
 Expands to @code{"rw"}.  See the @code{FSTAB_RW} value, it means the
 filesystem is mounted with read and write permissions.
+@comment mntent.h
+@comment ???
 @item MNTOPT_SUID
 Expands to @code{"suid"}.  This means that the SUID bit (@pxref{How
 Change Persona}) is respected when a program from the filesystem is
 started.
+@comment mntent.h
+@comment ???
 @item MNTOPT_NOSUID
 Expands to @code{"nosuid"}.  This is the opposite of @code{MNTOPT_SUID},
 the SUID bit for all files from the filesystem is ignored.
+@comment mntent.h
+@comment ???
 @item MNTOPT_NOAUTO
 Expands to @code{"noauto"}.  At startup time the @code{mount} program
 will ignore this entry if it is started with the @code{-a} option to
@@ -913,11 +941,15 @@  file accesses via @code{ioctl}.
 following mask and masked value macros:
 
 @vtable @code
+@comment sys/mount.h
+@comment Linux
 @item MS_MGC_MASK
 This multibit field contains a magic number.  If it does not have the value
 @code{MS_MGC_VAL}, @code{mount} assumes all the following bits are zero and
 the @var{data} argument is a null string, regardless of their actual values.
 
+@comment sys/mount.h
+@comment Linux
 @item MS_REMOUNT
 This bit on means to remount the filesystem.  Off means to mount it.
 @c There is a mask MS_RMT_MASK in mount.h that says only two of the options
@@ -925,36 +957,52 @@  This bit on means to remount the filesystem.  Off means to mount it.
 @c MS_RMT_MASK that says they all can be reset.  As far as I can tell,
 @c libc just passes the arguments straight through to the kernel.
 
+@comment sys/mount.h
+@comment Linux
 @item MS_RDONLY
 This bit on specifies that no writing to the filesystem shall be allowed
 while it is mounted.  This cannot be overridden by @code{ioctl}.  This
 option is available on nearly all filesystems.
 
+@comment sys/mount.h
+@comment Linux
 @item MS_NOSUID
 This bit on specifies that Setuid and Setgid permissions on files in the
 filesystem shall be ignored while it is mounted.
 
+@comment sys/mount.h
+@comment Linux
 @item MS_NOEXEC
 This bit on specifies that no files in the filesystem shall be executed
 while the filesystem is mounted.
 
+@comment sys/mount.h
+@comment Linux
 @item MS_NODEV
 This bit on specifies that no device special files in the filesystem
 shall be accessible while the filesystem is mounted.
 
+@comment sys/mount.h
+@comment Linux
 @item MS_SYNCHRONOUS
 This bit on specifies that all writes to the filesystem while it is
 mounted shall be synchronous; i.e., data shall be synced before each
 write completes rather than held in the buffer cache.
 
+@comment sys/mount.h
+@comment Linux
 @item MS_MANDLOCK
 This bit on specifies that mandatory locks on files shall be permitted while
 the filesystem is mounted.
 
+@comment sys/mount.h
+@comment Linux
 @item MS_NOATIME
 This bit on specifies that access times of files shall not be updated when
 the files are accessed while the filesystem is mounted.
 
+@comment sys/mount.h
+@comment Linux
 @item MS_NODIRATIME
 This bit on specifies that access times of directories shall not be updated
 when the directories are accessed while the filesystem in mounted.
@@ -1068,6 +1116,8 @@  mask macro:
 
 @vtable @code
 
+@comment sys/mount.h
+@comment Linux
 @item MNT_FORCE
 This bit on means to force the unmounting even if the filesystem is
 busy, by making it unbusy first.  If the bit is off and the filesystem is
diff --git a/manual/syslog.texi b/manual/syslog.texi
index 7b73a09..ab051f9 100644
--- a/manual/syslog.texi
+++ b/manual/syslog.texi
@@ -222,12 +222,16 @@  implicitly and uses defaults for the information in @var{ident} and
 single bit masks:
 
 @vtable @code
+@comment sys/syslog.h
+@comment BSD
 @item LOG_PERROR
 If on, @code{openlog} sets up the connection so that any @code{syslog}
 on this connection writes its message to the calling process' Standard
 Error stream in addition to submitting it to Syslog.  If off, @code{syslog}
 does not write the message to Standard Error.
 
+@comment sys/syslog.h
+@comment BSD
 @item LOG_CONS
 If on, @code{openlog} sets up the connection so that a @code{syslog} on
 this connection that fails to submit a message to Syslog writes the
@@ -235,11 +239,15 @@  message instead to system console.  If off, @code{syslog} does not write
 to the system console (but of course Syslog may write messages it
 receives to the console).
 
+@comment sys/syslog.h
+@comment BSD
 @item LOG_PID
 When on, @code{openlog} sets up the connection so that a @code{syslog}
 on this connection inserts the calling process' Process ID (PID) into
 the message.  When off, @code{openlog} does not insert the PID.
 
+@comment sys/syslog.h
+@comment BSD
 @item LOG_NDELAY
 When on, @code{openlog} opens and connects the @file{/dev/log} socket.
 When off, a future @code{syslog} call must open and connect the socket.
@@ -247,6 +255,8 @@  When off, a future @code{syslog} call must open and connect the socket.
 @strong{Portability note:}  In early systems, the sense of this bit was
 exactly the opposite.
 
+@comment sys/syslog.h
+@comment BSD
 @item LOG_ODELAY
 This bit does nothing.  It exists for backward compatibility.
 
@@ -338,42 +348,80 @@  The possible values for the facility code are (macros):
 @c if you try to use it here, just selects default.
 
 @vtable @code
+@comment sys/syslog.h
+@comment BSD
 @item LOG_USER
 A miscellaneous user process
+@comment sys/syslog.h
+@comment BSD
 @item LOG_MAIL
 Mail
+@comment sys/syslog.h
+@comment BSD
 @item LOG_DAEMON
 A miscellaneous system daemon
+@comment sys/syslog.h
+@comment BSD
 @item LOG_AUTH
 Security (authorization)
+@comment sys/syslog.h
+@comment BSD
 @item LOG_SYSLOG
 Syslog
+@comment sys/syslog.h
+@comment BSD
 @item LOG_LPR
 Central printer
+@comment sys/syslog.h
+@comment BSD
 @item LOG_NEWS
 Network news (e.g. Usenet)
+@comment sys/syslog.h
+@comment BSD
 @item LOG_UUCP
 UUCP
+@comment sys/syslog.h
+@comment BSD
 @item LOG_CRON
 Cron and At
+@comment sys/syslog.h
+@comment BSD
 @item LOG_AUTHPRIV
 Private security (authorization)
+@comment sys/syslog.h
+@comment BSD
 @item LOG_FTP
 Ftp server
+@comment sys/syslog.h
+@comment BSD
 @item LOG_LOCAL0
 Locally defined
+@comment sys/syslog.h
+@comment BSD
 @item LOG_LOCAL1
 Locally defined
+@comment sys/syslog.h
+@comment BSD
 @item LOG_LOCAL2
 Locally defined
+@comment sys/syslog.h
+@comment BSD
 @item LOG_LOCAL3
 Locally defined
+@comment sys/syslog.h
+@comment BSD
 @item LOG_LOCAL4
 Locally defined
+@comment sys/syslog.h
+@comment BSD
 @item LOG_LOCAL5
 Locally defined
+@comment sys/syslog.h
+@comment BSD
 @item LOG_LOCAL6
 Locally defined
+@comment sys/syslog.h
+@comment BSD
 @item LOG_LOCAL7
 Locally defined
 @end vtable
@@ -393,20 +441,36 @@  Syslog connection was opened.  @xref{Syslog Example}.
 The possible values for the priority code are (macros):
 
 @vtable @code
+@comment sys/syslog.h
+@comment BSD
 @item LOG_EMERG
 The message says the system is unusable.
+@comment sys/syslog.h
+@comment BSD
 @item LOG_ALERT
 Action on the message must be taken immediately.
+@comment sys/syslog.h
+@comment BSD
 @item LOG_CRIT
 The message states a critical condition.
+@comment sys/syslog.h
+@comment BSD
 @item LOG_ERR
 The message describes an error.
+@comment sys/syslog.h
+@comment BSD
 @item LOG_WARNING
 The message is a warning.
+@comment sys/syslog.h
+@comment BSD
 @item LOG_NOTICE
 The message describes a normal but important event.
+@comment sys/syslog.h
+@comment BSD
 @item LOG_INFO
 The message is purely informational.
+@comment sys/syslog.h
+@comment BSD
 @item LOG_DEBUG
 The message is only for debugging purposes.
 @end vtable
diff --git a/manual/terminal.texi b/manual/terminal.texi
index 0c0ded1..050c591 100644
--- a/manual/terminal.texi
+++ b/manual/terminal.texi
@@ -1847,14 +1847,20 @@  following values:
 
 @c Extra blank lines here make it look better.
 @vtable @code
+@comment termios.h
+@comment POSIX.1
 @item TCIFLUSH
 
 Clear any input data received, but not yet read.
 
+@comment termios.h
+@comment POSIX.1
 @item TCOFLUSH
 
 Clear any output data written, but not yet transmitted.
 
+@comment termios.h
+@comment POSIX.1
 @item TCIOFLUSH
 
 Clear both queued input and output.
@@ -1899,15 +1905,23 @@  The @var{action} argument specifies what operation to perform, and can
 be one of the following values:
 
 @vtable @code
+@comment termios.h
+@comment POSIX.1
 @item TCOOFF
 Suspend transmission of output.
 
+@comment termios.h
+@comment POSIX.1
 @item TCOON
 Restart transmission of output.
 
+@comment termios.h
+@comment POSIX.1
 @item TCIOFF
 Transmit a STOP character.
 
+@comment termios.h
+@comment POSIX.1
 @item TCION
 Transmit a START character.
 @end vtable
diff --git a/manual/time.texi b/manual/time.texi
index dccb979..bad9ce6 100644
--- a/manual/time.texi
+++ b/manual/time.texi
@@ -981,6 +981,8 @@  precision clocks.
 These functions are declared in @file{sys/timex.h}.
 
 @tindex struct ntptimeval
+@comment sys/timex.h
+@comment Linux
 @deftp {Data Type} {struct ntptimeval}
 This structure is used for information about the system clock.  It
 contains the following members:
@@ -1017,6 +1019,8 @@  The return value is @code{0} on success and other values on failure.  The
 following @code{errno} error conditions are defined for this function:
 
 @vtable @code
+@comment sys/timex.h
+@comment Linux
 @item TIME_ERROR
 The precision clock model is not properly set up at the moment, thus the
 clock must be considered unsynchronized, and the values should be
@@ -1025,6 +1029,8 @@  treated with care.
 @end deftypefun
 
 @tindex struct timex
+@comment timex.h
+@comment Linux
 @deftp {Data Type} {struct timex}
 This structure is used to control and monitor the system clock.  It
 contains the following members:
diff --git a/manual/users.texi b/manual/users.texi
index 0924f39..c32faca 100644
--- a/manual/users.texi
+++ b/manual/users.texi
@@ -1013,6 +1013,8 @@  The exit status of the process.
 @end table
 @end deftp
 
+@comment utmp.h
+@comment SVID
 @deftp {Data Type} {struct utmp}
 The @code{utmp} data structure is used to hold information about entries
 in the user accounting database.  On @gnusystems{} it has the following
@@ -1455,10 +1457,14 @@  default @code{getutent}, @code{getutid}, @code{getutline} and
 
 The following macros are defined for use as the @var{file} argument:
 
+@comment paths.h
+@comment BSD
 @deftypevr Macro {char *} _PATH_UTMP
 This macro is used to specify the user accounting database.
 @end deftypevr
 
+@comment paths.h
+@comment BSD
 @deftypevr Macro {char *} _PATH_WTMP
 This macro is used to specify the user accounting log file.
 @end deftypevr
@@ -1511,6 +1517,8 @@  These functions, described in the X/Open Portability Guide, are declared
 in the header file @file{utmpx.h}.
 @pindex utmpx.h
 
+@comment utmpx.h
+@comment XPG4.2
 @deftp {Data Type} {struct utmpx}
 The @code{utmpx} data structure contains at least the following members: