diff mbox

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

Message ID 20161206105525.21117-4-ricaljasan@pacific.net
State New
Headers show

Commit Message

Rical Jasan Dec. 6, 2016, 10:55 a.m. UTC
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 a standard derived from any feature test macros
	  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 uses a loose convention
	of standard names, though the syntax is essentially free-form.
	It prefers names that indicate specific standards and the
	oldest relevant standard, where known (e.g., "C90" over "ISO"
	or "POSIX.1-2001" over "POSIX").

	* 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/startup.texi: Likewise.
	* manual/stdio.texi: Likewise.
	* manual/string.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

Zack Weinberg Dec. 6, 2016, 1:23 p.m. UTC | #1
On 12/06/2016 05:55 AM, Rical Jasan wrote:
>       This commit completes header and standard annotations for all

>       @def*-commands and @vtable @items.


A high-level observation: I don't think MISC should appear in these
annotations.  MISC is an artifact of <features.h> having collapsed
_BSD_SOURCE and _SVID_SOURCE together, IIUC.  The manual should
continue to document which lineage each item came from, as that is
still relevant to people trying to write portable code.

I also have corrections to a number of the annotations:

> 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

_REENTRANT and _THREAD_SAFE were _not_ GNU inventions; they were both
invented by proprietary Unix vendors in the 1990-1995 timeframe.  I
*think* _REENTRANT was originally a Sun thing.  I don't know about
_THREAD_SAFE.

More to the point, though, they're so obsolete that there may not be
any point keeping them around either in the manual or the headers
anymore.  I'll send a separate message about that.

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


The DT_* constants are all from BSD.

>  The item is a directory which cannot be read.

> +@comment ftw.h

> +@comment MISC || XPG4

...
> +@comment ftw.h

> +@comment XPG4 && GNU


Based on Issue 7's history annotations, I believe the correct
provenance annotations for the FTW_* constants are:

SVID: FTW_F, FTW_D, FTW_DNR, FTW_NS
XPG4.2: FTW_DP, FTW_SL, FTW_SLN
XPG4.2: FTW_PHYS, FTW_MOUNT, FTW_CHDIR, FTW_DEPTH
GNU: FTW_ACTIONRETVAL

(SVID1 had ftw(); XPG4.2 added nftw(); the second set of constants
only make sense for use with nftw().)

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

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


Why are we documenting __va_copy at all?

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


Wasn't `long double` added in C99?  If so, all of the LDBL_* constants
are properly marked C99, not ISO.  (GCC's <float.h> defines them
unconditionally, but it supports `long double` as an extension in C90
mode.)

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

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

>  @item SEEK_SET


This is going to be really confusing.  I suspect it means "C90 puts
this macro in stdio.h, POSIX.1 additionally in unistd.h, and XOPEN in
fcntl.h" but I do hope we find a less ambiguous way to express that.

>  @vtable @code

> +@comment sys/mman.h

> +@comment BSD

>  @item MAP_PRIVATE


mmap() itself was invented in SVR4, and the MAP_SHARED, MAP_PRIVATE,
MAP_FIXED constants were there from the beginning.
http://pubs.opengroup.org/onlinepubs/9699919799/functions/mmap.html
says "First released in Issue 4, Version 2" under CHANGE HISTORY.
I'm not sure exactly what annotations that corresponds to, but BSD is
definitely not right.

> +@comment sys/mman.h

> +@comment BSD

>  @item MS_SYNC


Same as above.  msync() seems to have gone back and forth between XSI
and BASE depending on exactly which level of the standard you're
looking at, argh.

> +@comment sys/mman.h

> +@comment MISC

>  @item MADV_NORMAL

>  The region should receive no further special treatment.


Now these, these should be marked BSD.  (Functions that POSIX renamed
from 'foo' to 'posix_foo' upon standardization are *usually* from the
BSD lineage.
https://www.freebsd.org/cgi/man.cgi?query=madvise&apropos=0&sektion=0&manpath=FreeBSD+10.3-RELEASE+and+Ports&arch=default&format=html
confirms this case: "The madvise() system call first appeared in 4.4BSD.")

>  @comment TODO: @item M_CHECK_ACTION

>  @vtable @code

> +@comment malloc.h

> +@comment ???

>  @item M_MMAP_MAX


All of these M_* constants are specific to glibc's malloc
implementation and should therefore be marked GNU.

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


The NSS mechanism was invented by Sun, but <nss.h> is not a documented
interface in Solaris 11, so I think these are properly GNU.

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


We need an annotation for "defined by the base ABI for the CPU."
I know there are similar functions for ARM (__aeabi_*) and IA64, and
probably others - that we only document the PowerPC ones is just a
matter of the PowerPC maintainers having been more diligent than
average in the past.

>  @comment Extra blank lines make it look better.

>  @vtable @code

> +@comment sys/wait.h

> +@comment MISC

>  @item WAIT_ANY

...
> +@comment sys/wait.h

> +@comment MISC

>  @item WAIT_MYPGRP


These constants do not appear in the FreeBSD manpage for waitpid, so
they are probably SVID.

>  @comment sys/vtimes.h

> +@comment ???

>  @deftypefun int vtimes (struct vtimes *@var{current}, struct vtimes

>                          *@var{child})


Oh wow, it's not often I trip over an interface that's so old I've
never heard of it.  This one isn't in the current FreeBSD manpages,
the 4.3BSD manpages, *or* the Solaris manpages, but it *is* in the
online AIX manpages, which means that SVID is probably the best
approximation.

("This function is obsolete" would be another good thing to have a
machine-parseable annotation for.)

>  @vtable @code

> +@comment fmtmsg.h

> +@comment ???


This entire header is from SVR4 and is XSI in Issue 7.
http://pubs.opengroup.org/onlinepubs/9699919799/functions/fmtmsg.html

>  @vtable @code

> +@comment mntent.h

> +@comment ???


BSD for all of these.

zw
Andreas Schwab Dec. 6, 2016, 2:26 p.m. UTC | #2
On Dez 06 2016, Zack Weinberg <zackw@panix.com> wrote:

> Wasn't `long double` added in C99?


long double was already in C89, C99 only added the IEC 60559
floating-point arithmetic support.

Andreas.

-- 
Andreas Schwab, SUSE Labs, schwab@suse.de
GPG Key fingerprint = 0196 BAD8 1CE9 1970 F4BE  1748 E4D4 88E3 0EEA B9D7
"And now for something completely different."
Joseph Myers Dec. 6, 2016, 4:23 p.m. UTC | #3
On Tue, 6 Dec 2016, Zack Weinberg wrote:

> On 12/06/2016 05:55 AM, Rical Jasan wrote:

> >       This commit completes header and standard annotations for all

> >       @def*-commands and @vtable @items.

> 

> A high-level observation: I don't think MISC should appear in these

> annotations.  MISC is an artifact of <features.h> having collapsed

> _BSD_SOURCE and _SVID_SOURCE together, IIUC.  The manual should


__USE_MISC long predates that.  The old comment before that consolidation 
was "Define things common to BSD and System V Unix." (now "Define things 
from 4.3BSD or System V Unix.", reflecting the change from "BSD intersect 
SysV" to "BSD union SysV").

But actually I expect plenty of __USE_MISC declarations came from other 
sources, including GNU-invented things that happen to be declared by 
default (in headers that aren't themselves GNU-invented) rather than just 
with _GNU_SOURCE.

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

> 

> Wasn't `long double` added in C99?  If so, all of the LDBL_* constants

> are properly marked C99, not ISO.  (GCC's <float.h> defines them

> unconditionally, but it supports `long double` as an extension in C90

> mode.)


The FLT_* and LDBL_* constants are C90.  The float and long double 
functions in math.h (and strtof and strtold) were introduced in C99.

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

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

> >  @item SEEK_SET

> 

> This is going to be really confusing.  I suspect it means "C90 puts

> this macro in stdio.h, POSIX.1 additionally in unistd.h, and XOPEN in

> fcntl.h" but I do hope we find a less ambiguous way to express that.


I hope the syntax gets replaced by macros that take both header and 
standards as arguments, so they are always clearly paired.

> >  @vtable @code

> > +@comment sys/mman.h

> > +@comment BSD

> >  @item MAP_PRIVATE

> 

> mmap() itself was invented in SVR4, and the MAP_SHARED, MAP_PRIVATE,

> MAP_FIXED constants were there from the beginning.

> http://pubs.opengroup.org/onlinepubs/9699919799/functions/mmap.html

> says "First released in Issue 4, Version 2" under CHANGE HISTORY.

> I'm not sure exactly what annotations that corresponds to, but BSD is

> definitely not right.


POSIX.1-1993 (otherwise known as POSIX.1b; available as a 40 MB PDF from 
IEEE Xplore if you have a site license for that) adds sys/mman.h with 
contents MAP_FAILED MAP_FIXED MAP_PRIVATE MAP_SHARED MCL_CURRENT 
MCL_FUTURE MS_ASYNC MS_INVALIDATE MS_SYNC PROT_EXEC PROT_NONE PROT_READ 
PROT_WRITE mlock mlockall mmap mprotect msync munlock munlockall munmap 
shm_open shm_unlink.  XPG4.2 has a subset of that, which indicates 
documenting some interfaces as POSIX.1-1993 and some as POSIX.1-1993 || 
XPG4.2 (see bug 17663 for the headers failing to reflect that not all are 
in XPG4.2, with the conform/ data having a matching bug).

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

> 

> We need an annotation for "defined by the base ABI for the CPU."

> I know there are similar functions for ARM (__aeabi_*) and IA64, and

> probably others - that we only document the PowerPC ones is just a


The __aeabi_* functions don't have header declarations, just an ABI.  
(There are ARM extension APIs with headers - defined in ACLE - but those 
are generally pure header / compiler intrinsic APIs with no corresponding 
library functions.)

> >  @comment Extra blank lines make it look better.

> >  @vtable @code

> > +@comment sys/wait.h

> > +@comment MISC

> >  @item WAIT_ANY

> ...

> > +@comment sys/wait.h

> > +@comment MISC

> >  @item WAIT_MYPGRP

> 

> These constants do not appear in the FreeBSD manpage for waitpid, so

> they are probably SVID.


SVID (fourth edition) is available from 
<http://www.sco.com/developers/devspecs/>.  I don't see them there.  They 
were __USE_BSD before commit 498afc54dfee41d33ba519f496e96480badace8e 
unified things in the headers.

> ("This function is obsolete" would be another good thing to have a

> machine-parseable annotation for.)


It was certainly noted when we did the unification that we should consider 
properly obsoleting some of the __USE_MISC functions (making them into 
compat symbols so not included for new architectures or available for new 
links, with or without a period of being declared as deprecated in the 
headers first).  Much the same no doubt applies to non-function interfaces 
as well.

-- 
Joseph S. Myers
joseph@codesourcery.com
Zack Weinberg Dec. 6, 2016, 7:23 p.m. UTC | #4
On 12/06/2016 11:23 AM, Joseph Myers wrote:
> On Tue, 6 Dec 2016, Zack Weinberg wrote:

> 

>> On 12/06/2016 05:55 AM, Rical Jasan wrote:

>>>       This commit completes header and standard annotations for all

>>>       @def*-commands and @vtable @items.

>>

>> A high-level observation: I don't think MISC should appear in these

>> annotations.  MISC is an artifact of <features.h> having collapsed

>> _BSD_SOURCE and _SVID_SOURCE together, IIUC.  The manual should

> 

> __USE_MISC long predates that.  The old comment before that consolidation 

> was "Define things common to BSD and System V Unix." (now "Define things 

> from 4.3BSD or System V Unix.", reflecting the change from "BSD intersect 

> SysV" to "BSD union SysV").

> 

> But actually I expect plenty of __USE_MISC declarations came from other 

> sources, including GNU-invented things that happen to be declared by 

> default (in headers that aren't themselves GNU-invented) rather than just 

> with _GNU_SOURCE.


Yeah, I've noticed cases like that myself.

So the rationale I gave was wrong, but I think the point - MISC is not a
useful thing to say in the manual - is only underlined by your
observations.  Yes?

>> Wasn't `long double` added in C99?  If so, all of the LDBL_* constants

>> are properly marked C99, not ISO.  (GCC's <float.h> defines them

>> unconditionally, but it supports `long double` as an extension in C90

>> mode.)

> 

> The FLT_* and LDBL_* constants are C90.  The float and long double 

> functions in math.h (and strtof and strtold) were introduced in C99.


Oh, OK, never mind then.

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

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

>>>  @item SEEK_SET

>>

>> This is going to be really confusing.  I suspect it means "C90 puts

>> this macro in stdio.h, POSIX.1 additionally in unistd.h, and XOPEN in

>> fcntl.h" but I do hope we find a less ambiguous way to express that.

> 

> I hope the syntax gets replaced by macros that take both header and 

> standards as arguments, so they are always clearly paired.


Concur.

>>>  @vtable @code

>>> +@comment sys/mman.h

>>> +@comment BSD

>>>  @item MAP_PRIVATE

>>

>> mmap() itself was invented in SVR4, and the MAP_SHARED, MAP_PRIVATE,

>> MAP_FIXED constants were there from the beginning.

>> http://pubs.opengroup.org/onlinepubs/9699919799/functions/mmap.html

>> says "First released in Issue 4, Version 2" under CHANGE HISTORY.

>> I'm not sure exactly what annotations that corresponds to, but BSD is

>> definitely not right.

> 

> POSIX.1-1993 (otherwise known as POSIX.1b; available as a 40 MB PDF from 

> IEEE Xplore if you have a site license for that) adds sys/mman.h with 

> contents MAP_FAILED MAP_FIXED MAP_PRIVATE MAP_SHARED MCL_CURRENT 

> MCL_FUTURE MS_ASYNC MS_INVALIDATE MS_SYNC PROT_EXEC PROT_NONE PROT_READ 

> PROT_WRITE mlock mlockall mmap mprotect msync munlock munlockall munmap 

> shm_open shm_unlink.  XPG4.2 has a subset of that, which indicates 

> documenting some interfaces as POSIX.1-1993 and some as POSIX.1-1993 || 

> XPG4.2 (see bug 17663 for the headers failing to reflect that not all are 

> in XPG4.2, with the conform/ data having a matching bug).


So, how useful do you think the older POSIX/XPG/whatever conformance
modes actually are nowadays?  Could we conceivably get away with pruning
the list down to

 * C90 and nothing more
 * C99 and nothing more
 * C11 and nothing more

 * Cxx + POSIX.1-2001
 * Cxx + POSIX.1-2001 + XSI
 * Cxx + POSIX.1-2008
 * Cxx + POSIX.1-2008 + XSI

 * _DEFAULT_SOURCE
 * _GNU_SOURCE

plus the semi-orthogonal LFS and ATFILE toggles?

(I think POSIX.1-2001 is a good cutoff point because it's the first
unified POSIX/XPG standard and basically ubiquitous in my experience,
because there are still widely-used systems that haven't adopted all the
new stuff in -2008 (e.g. OSX.latest still doesn't have the _l
functions), and because -2008 removed a number of functions that are
still heavily used, e.g. gettimeofday, setcontext.)

(This is *largely* an independent issue from what should be in the
manual - I personally value detailed provenance information in the
manual, but verifying the history back into the early nineties gets
difficult, can involve spending money, and it's unclear to me how useful
it is to people who aren't history nerds.)

>> We need an annotation for "defined by the base ABI for the CPU."

>> I know there are similar functions for ARM (__aeabi_*) and IA64, and

>> probably others - that we only document the PowerPC ones is just a

> 

> The __aeabi_* functions don't have header declarations, just an ABI.  

> (There are ARM extension APIs with headers - defined in ACLE - but those 

> are generally pure header / compiler intrinsic APIs with no corresponding 

> library functions.)


Does that mean they shouldn't be documented, in your opinion? / Does
that mean we don't need the "defined by the base ABI for the CPU"
annotation that I suggested, in your opinion?

>>>  @comment Extra blank lines make it look better.

>>>  @vtable @code

>>> +@comment sys/wait.h

>>> +@comment MISC

>>>  @item WAIT_ANY

>> ...

>>> +@comment sys/wait.h

>>> +@comment MISC

>>>  @item WAIT_MYPGRP

>>

>> These constants do not appear in the FreeBSD manpage for waitpid, so

>> they are probably SVID.

> 

> SVID (fourth edition) is available from 

> <http://www.sco.com/developers/devspecs/>.  I don't see them there.  They 

> were __USE_BSD before commit 498afc54dfee41d33ba519f496e96480badace8e 

> unified things in the headers.


Hmm.  Spelunking around in http://minnie.tuhs.org/cgi-bin/utree.pl, the
oldest thing I can find that is recognizably <sys/wait.h> is from
4.3BSD-Reno,
http://minnie.tuhs.org/cgi-bin/utree.pl?file=4.3BSD-Reno/src/sys/sys/wait.h,
and it does have the WAIT_ANY, WAIT_MYPGRP constants.  (4.2BSD has
http://minnie.tuhs.org/cgi-bin/utree.pl?file=4.2BSD/usr/src/sys/h/wait.h
which is related but clearly not the same file, and does not have those
macros.)  That site doesn't have the System V lineage, but I can't
really see those macros _not_ getting standardized if they were from
that lineage, so that's good enough for me to agree they were from BSD.

>> ("This function is obsolete" would be another good thing to have a

>> machine-parseable annotation for.)

> 

> It was certainly noted when we did the unification that we should consider 

> properly obsoleting some of the __USE_MISC functions (making them into 

> compat symbols so not included for new architectures or available for new 

> links, with or without a period of being declared as deprecated in the 

> headers first).  Much the same no doubt applies to non-function interfaces 

> as well.


I'm for such an obsoletions pass, but it's probably 2.26 material at
this point, and let's not tie it up with the manual work.

zw
Joseph Myers Dec. 6, 2016, 9:42 p.m. UTC | #5
On Tue, 6 Dec 2016, Zack Weinberg wrote:

> > But actually I expect plenty of __USE_MISC declarations came from other 

> > sources, including GNU-invented things that happen to be declared by 

> > default (in headers that aren't themselves GNU-invented) rather than just 

> > with _GNU_SOURCE.

> 

> Yeah, I've noticed cases like that myself.

> 

> So the rationale I gave was wrong, but I think the point - MISC is not a

> useful thing to say in the manual - is only underlined by your

> observations.  Yes?


It gives the information that something is declared by default.  It might 
be refined to give more information about the origin of the interface, but 
it's still useful information.

> So, how useful do you think the older POSIX/XPG/whatever conformance

> modes actually are nowadays?  Could we conceivably get away with pruning


I don't have a clear notion of how people use the conformance modes (any 
of them) in general.  Those modes aren't problematic to support the way 
pre-ISO-C standards are (and we exclude the odd feature from them that's 
problematic to support).

> plus the semi-orthogonal LFS and ATFILE toggles?


It's not clear to me that ATFILE is a useful toggle now (it's a subset of 
_POSIX_C_SOURCE=200809L).  (For that matter, _LARGEFILE_SOURCE, as opposed 
to __LARGEFILE64_SOURCE, only enables declarations of fseeko / ftello, 
which are also in POSIX.1-2001 as well as UNIX 98.  And features.h defines 
a macro _ISOC95_SOURCE which is never used at all.)

> > The __aeabi_* functions don't have header declarations, just an ABI.  

> > (There are ARM extension APIs with headers - defined in ACLE - but those 

> > are generally pure header / compiler intrinsic APIs with no corresponding 

> > library functions.)

> 

> Does that mean they shouldn't be documented, in your opinion? / Does

> that mean we don't need the "defined by the base ABI for the CPU"

> annotation that I suggested, in your opinion?


I think we should document APIs (things declared in headers), not ABIs.  
That primarily means APIs in glibc's headers, though documenting features 
from standard headers provided by GCC seems reasonable.

I don't think we should document ABI-only interfaces with no API.  And I 
don't think we should document architecture-specific APIs from headers 
provided by GCC such as arm_acle.h or x86 *intrin.h (there are huge 
numbers of such APIs).

The PowerPC examples you gave are however APIs from a header provided by 
glibc, so should be documented.

-- 
Joseph S. Myers
joseph@codesourcery.com
Joseph Myers Dec. 7, 2016, 4:31 p.m. UTC | #6
On Tue, 6 Dec 2016, Rical Jasan wrote:

> diff --git a/manual/argp.texi b/manual/argp.texi

> index bca3ca5..f1767cc 100644

> --- a/manual/argp.texi

> +++ b/manual/argp.texi


All the changes to this file are OK.

> diff --git a/manual/arith.texi b/manual/arith.texi

> index 0c182c5..eee9880 100644

> --- a/manual/arith.texi

> +++ b/manual/arith.texi


All the changes to this file are OK.  Note for when making annotations 
more consistent in standard naming in future that:

> @@ -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 TS 18661-1:2014

>  @deftypevrx Macro double SNAN

> +@comment math.h

> +@comment TS 18661-1:2014

>  @deftypevrx Macro {long double} SNANL


All three are TS 18661-1:2014.

> @@ -2041,8 +2055,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{}}

> @@ -2063,8 +2079,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})


As are all these.

> diff --git a/manual/lang.texi b/manual/lang.texi

> index 6281840..5e4d1d3 100644

> --- a/manual/lang.texi

> +++ b/manual/lang.texi


All the changes to this file are OK apart from the question of whether to 
document __va_copy at all.

> diff --git a/manual/string.texi b/manual/string.texi

> index 1986357..683a20f 100644

> --- a/manual/string.texi

> +++ b/manual/string.texi


All the changes to this file are OK.

I think the approved pieces should be committed to reduce the size of the 
patch in future revisions.

-- 
Joseph S. Myers
joseph@codesourcery.com
Rical Jasan Dec. 8, 2016, 2:56 a.m. UTC | #7
On 12/07/2016 08:31 AM, Joseph Myers wrote:
> On Tue, 6 Dec 2016, Rical Jasan wrote:

> 

>> diff --git a/manual/argp.texi b/manual/argp.texi

>> index bca3ca5..f1767cc 100644

>> --- a/manual/argp.texi

>> +++ b/manual/argp.texi

> 

> All the changes to this file are OK.

> 

>> diff --git a/manual/arith.texi b/manual/arith.texi

>> index 0c182c5..eee9880 100644

>> --- a/manual/arith.texi

>> +++ b/manual/arith.texi

> 

> All the changes to this file are OK.  Note for when making annotations 

> more consistent in standard naming in future that:

> 

>> @@ -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 TS 18661-1:2014

>>  @deftypevrx Macro double SNAN

>> +@comment math.h

>> +@comment TS 18661-1:2014

>>  @deftypevrx Macro {long double} SNANL

> 

> All three are TS 18661-1:2014.

> 

>> @@ -2041,8 +2055,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{}}

>> @@ -2063,8 +2079,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})

> 

> As are all these.


Right.  I have a branch with these, and the way I originally designed
the patchset those would have gone in v2 5/5 since they would have been
changes and not purely new, but they didn't make it.  I started to go
down a rabbit hole when dealing with ISO because I couldn't address all
of them based on immediate context, so I had shelved it for the time
being as incomplete (unlike the conversion of X/Open to XOPEN, which was
purely formatting, and complete, for example).  v2 5/5 wound up focusing
on formatting, and reducing the variety of alternate spellings of the
same standard, and not converting all the names I could.

>> diff --git a/manual/lang.texi b/manual/lang.texi

>> index 6281840..5e4d1d3 100644

>> --- a/manual/lang.texi

>> +++ b/manual/lang.texi

> 

> All the changes to this file are OK apart from the question of whether to 

> document __va_copy at all.


It'll error out after check-stds.pl is added if it isn't annotated, and
we can always remove it later once that question is answered.  Others
will have to weigh in on the matter, though; I don't have much of an
opinion either way.

>> diff --git a/manual/string.texi b/manual/string.texi

>> index 1986357..683a20f 100644

>> --- a/manual/string.texi

>> +++ b/manual/string.texi

> 

> All the changes to this file are OK.

> 

> I think the approved pieces should be committed to reduce the size of the 

> patch in future revisions.


That would be for someone other than myself to handle, correct?  Then,
when I rebase against master for v3, it'll be automatically adjusted.
Should the commit message be changed, for either one or the other?

Rical
Joseph Myers Dec. 8, 2016, 2:02 p.m. UTC | #8
On Wed, 7 Dec 2016, Rical Jasan wrote:

> > I think the approved pieces should be committed to reduce the size of the 

> > patch in future revisions.

> 

> That would be for someone other than myself to handle, correct?  Then,


I'm assuming you have commit access and will commit approved patches, or 
pieces of patches that make sense on their own.

-- 
Joseph S. Myers
joseph@codesourcery.com
Rical Jasan Dec. 12, 2016, 9:01 a.m. UTC | #9
On 12/08/2016 06:02 AM, Joseph Myers wrote:
> On Wed, 7 Dec 2016, Rical Jasan wrote:

> 

>>> I think the approved pieces should be committed to reduce the size of the 

>>> patch in future revisions.

>>

>> That would be for someone other than myself to handle, correct?  Then,

> 

> I'm assuming you have commit access and will commit approved patches, or 

> pieces of patches that make sense on their own.


I don't think I have commit access; I've never committed anything thus
far, at least.  What do I need to get that process started?  On the
wiki, I see a page for a Committer's Checklist, but that isn't about
becoming a committer.

Rical
Joseph Myers Dec. 14, 2016, 6:18 p.m. UTC | #10
On Mon, 12 Dec 2016, Rical Jasan wrote:

> On 12/08/2016 06:02 AM, Joseph Myers wrote:

> > On Wed, 7 Dec 2016, Rical Jasan wrote:

> > 

> >>> I think the approved pieces should be committed to reduce the size of the 

> >>> patch in future revisions.

> >>

> >> That would be for someone other than myself to handle, correct?  Then,

> > 

> > I'm assuming you have commit access and will commit approved patches, or 

> > pieces of patches that make sense on their own.

> 

> I don't think I have commit access; I've never committed anything thus

> far, at least.  What do I need to get that process started?  On the

> wiki, I see a page for a Committer's Checklist, but that isn't about

> becoming a committer.


Please complete <https://sourceware.org/cgi-bin/pdw/ps_form.cgi> and name 
me as approver.

-- 
Joseph S. Myers
joseph@codesourcery.com
Rical Jasan Dec. 14, 2016, 11:30 p.m. UTC | #11
On 12/14/2016 10:18 AM, Joseph Myers wrote:
> On Mon, 12 Dec 2016, Rical Jasan wrote:

>> On 12/08/2016 06:02 AM, Joseph Myers wrote:

>>> On Wed, 7 Dec 2016, Rical Jasan wrote:

>>>

>>>>> I think the approved pieces should be committed to reduce the size of the 

>>>>> patch in future revisions.

>>>>

>>>> That would be for someone other than myself to handle, correct?  Then,

>>>

>>> I'm assuming you have commit access and will commit approved patches, or 

>>> pieces of patches that make sense on their own.

>>

>> I don't think I have commit access; I've never committed anything thus

>> far, at least.  What do I need to get that process started?  On the

>> wiki, I see a page for a Committer's Checklist, but that isn't about

>> becoming a committer.

> 

> Please complete <https://sourceware.org/cgi-bin/pdw/ps_form.cgi> and name 

> me as approver.


Completed the form.

Rical
Rical Jasan Dec. 15, 2016, 9:58 a.m. UTC | #12
On 12/14/2016 03:30 PM, Rical Jasan wrote:
> On 12/14/2016 10:18 AM, Joseph Myers wrote:

>> On Mon, 12 Dec 2016, Rical Jasan wrote:

>>> On 12/08/2016 06:02 AM, Joseph Myers wrote:

>>>> On Wed, 7 Dec 2016, Rical Jasan wrote:

>>>>

>>>>>> I think the approved pieces should be committed to reduce the size of the 

>>>>>> patch in future revisions.

>>>>>

>>>>> That would be for someone other than myself to handle, correct?  Then,

>>>>

>>>> I'm assuming you have commit access and will commit approved patches, or 

>>>> pieces of patches that make sense on their own.

>>>

>>> I don't think I have commit access; I've never committed anything thus

>>> far, at least.  What do I need to get that process started?  On the

>>> wiki, I see a page for a Committer's Checklist, but that isn't about

>>> becoming a committer.

>>

>> Please complete <https://sourceware.org/cgi-bin/pdw/ps_form.cgi> and name 

>> me as approver.

> 

> Completed the form.


Received notice my account was set up.  Thank you!  Am currently
reviewing the wiki, particularly GlibcGit.  (I see on MAINTAINERS I
could have found the form under "Becoming a maintainer (developer)"...
that should probably be a rite of passage hahah)

To confirm the approved pieces for once I'm prepared to push the commit
button, were you referring to only the chapters so far in this patch
([v2 3/5] {argp,arith,lang,string}.texi) or also the first two
(patches)?  [v2 1/5] has been OK'd, no other comments; [v2 2/5] also
was, though a typo was pointed out in the commit message.

On the topic of commit messages, How would you like me to write them if
this patch goes in piecewise?  Should the first one look how I submitted
it in this patch and subsequent patches can refer back to it or
duplicate it?  Or should they be rewritten to be more specific for each
commit (maybe if committed by file)?

Excited,
Rical
Joseph Myers Dec. 15, 2016, 1:01 p.m. UTC | #13
On Thu, 15 Dec 2016, Rical Jasan wrote:

> To confirm the approved pieces for once I'm prepared to push the commit

> button, were you referring to only the chapters so far in this patch

> ([v2 3/5] {argp,arith,lang,string}.texi) or also the first two

> (patches)?  [v2 1/5] has been OK'd, no other comments; [v2 2/5] also

> was, though a typo was pointed out in the commit message.


I'm referring to all patches or parts of patches that have been approved.

> On the topic of commit messages, How would you like me to write them if

> this patch goes in piecewise?  Should the first one look how I submitted

> it in this patch and subsequent patches can refer back to it or

> duplicate it?  Or should they be rewritten to be more specific for each

> commit (maybe if committed by file)?


The commit messages should be accurate in relation to the patch version 
actually committed.

-- 
Joseph S. Myers
joseph@codesourcery.com
Rical Jasan Feb. 7, 2017, 5:12 a.m. UTC | #14
On to 2.26!

I apologize for the sudden absence.  I was pulled away by some
priorities that kept me longer than I expected.  I've caught up on
libc-alpha and picked back up the work on header and standards annotations.

On 12/15/2016 05:01 AM, Joseph Myers wrote:
> On Thu, 15 Dec 2016, Rical Jasan wrote:

>> To confirm the approved pieces for once I'm prepared to push the commit

>> button, were you referring to only the chapters so far in this patch

>> ([v2 3/5] {argp,arith,lang,string}.texi) or also the first two

>> (patches)?  [v2 1/5] has been OK'd, no other comments; [v2 2/5] also

>> was, though a typo was pointed out in the commit message.

> 

> I'm referring to all patches or parts of patches that have been approved.

> 

>> On the topic of commit messages, How would you like me to write them if

>> this patch goes in piecewise?  Should the first one look how I submitted

>> it in this patch and subsequent patches can refer back to it or

>> duplicate it?  Or should they be rewritten to be more specific for each

>> commit (maybe if committed by file)?

> 

> The commit messages should be accurate in relation to the patch version 

> actually committed.


If I'm going to piecemeal [1], I have a question about how best to
change the commit message.  Chapter-by-chapter it's easier to provide
more detail, so I wrote the following for argp.texi, for example:

----
argp.texi contains several @vtables with variables lacking header and
standard annotations.  All ARGP_* variables are GNU extensions
declared in argp.h, and are annotated accordingly.

        * manual/argp.texi: Annotate variables declared in argp.h
        as GNU extensions.
----

The commit message in [1], however, contains the rationale behind these
changes, which is lost if I break the chapters apart and give specifics.
 If I were to include the rationale in every chapter, that would be
overly redundant.  I feel the patches speak for themselves, given the
rationale, but I also understand the need to ease review for larger diffs.

So, how would you like the per-chapter commits to read?

Thank you,
Rical

[1] https://sourceware.org/ml/libc-alpha/2016-12/msg00141.html
Joseph Myers Feb. 7, 2017, 4:40 p.m. UTC | #15
On Mon, 6 Feb 2017, Rical Jasan wrote:

> The commit message in [1], however, contains the rationale behind these

> changes, which is lost if I break the chapters apart and give specifics.

>  If I were to include the rationale in every chapter, that would be

> overly redundant.  I feel the patches speak for themselves, given the

> rationale, but I also understand the need to ease review for larger diffs.


I'd say the first commit should give the general description of the issues 
/ design of changes being made, then describe what's being done in that 
particular commit.  Subsequent ones might then refer back to the first 
commit / submission of that patch for details of the overall issue / 
changes.

-- 
Joseph S. Myers
joseph@codesourcery.com
Rical Jasan Feb. 8, 2017, 8:50 a.m. UTC | #16
On 02/07/2017 08:40 AM, Joseph Myers wrote:
> On Mon, 6 Feb 2017, Rical Jasan wrote:

> 

>> The commit message in [1], however, contains the rationale behind these

>> changes, which is lost if I break the chapters apart and give specifics.

>>  If I were to include the rationale in every chapter, that would be

>> overly redundant.  I feel the patches speak for themselves, given the

>> rationale, but I also understand the need to ease review for larger diffs.

> 

> I'd say the first commit should give the general description of the issues 

> / design of changes being made, then describe what's being done in that 

> particular commit.  Subsequent ones might then refer back to the first 

> commit / submission of that patch for details of the overall issue / 

> changes.


I was reflecting on this project today and yet another option crossed my
mind.  When I originally submitted this patchset, I had no idea what the
eventual framework would look like (well, had some ideas, but nothing
proposed or discussed)---I only knew that at least completing the header
and standards comments, even if just stubs, would make it easier later.
This patchset, however, kicked off some discussion about that framework,
resulting in a proposal like the following (very brief; see [1]):

  @def... foo
  @standards{GNU, foo.h}

There remains a good bit of detail to work out, including:

  * handling multiple headers/standards
  * handling @*x lists
  * placement in block (e.g., above/below @safety)
  * formatting of output
  * standardized standard names
  * generating the Summary
  * enforcing/checking annotations

but I think we have a good enough idea to start playing with it.

More to my point, though, how do you feel about abandoning this patchset
in favour of a v3 that tries to get us all the way through to the end,
now that I have something to work with in that regard?

I hate to unnecessarily burden reviewers, and having to review the
entirety of the comment-based changes, and then eventually having to
review the conversion, is probably more time-consuming than it needs to
be.  Given the discussion around [1], going directly there at this point
should only require a single pass for review (after all the other review
deciding how we want it look, etc., etc. ;).

I'd envision a v3 containing patches for:

  1. Introducing the @standards and related macros.
  2. Script(s) to generate the Summary and check annotations.
  3. Adding and converting annotations.

I imagine it's best to apply that kind of change all at once, but the
annotations are probably easier to review by chapter (as evidenced by
this thread).  I suppose I could kick out chapter-based patches for
review as I finish them (that review is basically for correctness;
output formatting and standards names can be ironed out separately/along
the way) and just wait until everything's ack'd to push?  Is that a
reasonable approach?

That also solves the problem of per-chapter v2 patches feeling out of
context, which I think is where my thought process started this
morning...  The new macros would have to go in first, so the stage will
already be set for all subsequent commits.

Thank you for your patience.  :)

Rical

[1] https://sourceware.org/ml/libc-alpha/2016-11/msg00923.html
Joseph Myers Feb. 8, 2017, 1:51 p.m. UTC | #17
On Wed, 8 Feb 2017, Rical Jasan wrote:

> I'd envision a v3 containing patches for:

> 

>   1. Introducing the @standards and related macros.

>   2. Script(s) to generate the Summary and check annotations.

>   3. Adding and converting annotations.


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

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

-- 
Joseph S. Myers
joseph@codesourcery.com
Rical Jasan Feb. 12, 2017, 6:01 a.m. UTC | #18
On 02/08/2017 05:51 AM, Joseph Myers wrote:
> On Wed, 8 Feb 2017, Rical Jasan wrote:

> 

>> I'd envision a v3 containing patches for:

>>

>>   1. Introducing the @standards and related macros.

>>   2. Script(s) to generate the Summary and check annotations.

>>   3. Adding and converting annotations.

> 

> I think any conversion to @standards should have the following property: 

> there is a patch that changes all existing comment-based annotations to 

> @standards-based annotations, leaving the generated summary and the whole 

> of the formatted manuals unchanged after the patch.  That patch should 

> contain a small manually written patch (adapting the summary-generation 

> script to read @standards instead of comments, adding dummy definitions of 

> @standards macros), a script that does the conversion (which of course 

> wouldn't be committed, just the results of running it would be), and a 

> large purely automatically generated set of changes made by the conversion 

> script.

> 

> That is, there must not be an "Adding and converting annotations." patch; 

> the automated conversion must be clearly separated from any patch that 

> actually changes or adds any annotations to the manual.  (This does not 

> assert whether such changes and additions happen before or after the 

> conversion.)


I am currently working on this, though it may take a little while with
my schedule.  I have the basics of the conversion script in place so
far, and am hunting down all the exceptions.

Rical
Rical Jasan April 4, 2017, 3:56 a.m. UTC | #19
Alright, it's time for an update and to request some direction.

I currently have a patchset that looks like:

  1) Introduce the conversion script.
  2) Create the @standards* macros.
  3) Perform some pre-conversion cleanup.
  4) Convert header and standards @comments to @standards.
  5) Replace summary.awk with summary.pl.
  6) Introduce a @standards-checking script.
  ...) Per-file commits completing @standards.
  N) Remove the conversion script.

I plan on folding the syntax-checking into summary.pl; they're separate
right now for workflow reasons.  Similarly, the conversion script can be
removed anytime after the conversion patch, but I leave it in because
it's nice to have in the working tree for reference.

As of (5), there is a near 1:1 conversion from @comment-based
annotations to @standards.  "Near", because summary.awk didn't always
get everything right.  The significant difference in summary.texi is how
missing headers or standards are rendered, now being @emph{no header} or
"???", respectively.  Some @ref nodes are correctly reported where they
were not before.  Some ordering differences are present, due to the way
the files are parsed and entries stored.  Note that the locale is
respected, so different users may have differently-ordered Summary
chapters, but summary.awk appears to have done this as well.

For the @standards macros, I've created both @standards{STD, HDR} and
@standardsx{foo, STD, HDR}.  The proposed usage is:

  @item FOO
  @standards{STD, HDR}

  @deftypefun foo
  @deftypefunx fool
  @standardsx{foo, STD, HDR}
  @standardsx{fool, STD, HDR}

  @item SEEK_SET
  @standards{C90, stdio.h}
  @standards{POSIX.1, unistd.h}
  @standards{XOPEN || POSIX.1-2008, fcntl.h}

I'm not particularly concerned with addressing the logical combinations
of standards, or canonicalizing standards names at this time.  The
@standards* macros in macros.texi are empty placeholders, so there is
plenty of time to work out the details before we flip the rendering
switch.  They'll simply look like they always have in the Summary in the
meantime.

I use the SEEK_SET example to show one possible way of dealing with
multiple headers and standards.  Note that @standardsx is used for all
elements in @*x chains, including the first non-@*x element.  What
differentiates it is the inclusion of the annotated element's name,
necessary to distinguish the elements in lists using @*x-commands.

The conversion script is written to be 1:1 with summary.awk, so multiple
header and standard annotations aren't created according to the SEEK_SET
example above.  Instead, @comma{} is used:

  @item SEEK_SET
  @standards{C90@comma{} POSIX.1@comma{} XOPEN || POSIX.1-2008, \
             stdio.h@comma{} unistd.h@comma{} fcntl.h}

It's messier, but easily identified and converted later.

My question at this point is whether I should submit (1-5,N) to get the
@standards conversion over with, while more-or-less maintaining the
status quo, or if I should not worry about maintaining that and take it
a couple steps further.  I could submit the first patchset with (1-5,N)
as-is, with some additional patches to convert @comma{}s to multiple
@standards, and add in enforcing along with the completion patches, but
I think that last bit was intended to happen in a separate patchset.

With the conversion to @standards, it becomes much easier to work on all
this; now we can `grep ^@standards', whereas it's anybody's guess which
@comments held standards or headers before, so let me know what you'd
like most to see.

Thank you,
Rical
Joseph Myers April 4, 2017, 11:26 a.m. UTC | #20
On Tue, 4 Apr 2017, Rical Jasan wrote:

> the files are parsed and entries stored.  Note that the locale is

> respected, so different users may have differently-ordered Summary

> chapters, but summary.awk appears to have done this as well.


Respecting the locale is a simple bug; LC_ALL=C should be used in the 
makefile when running anything that does sorting etc. as part of the build 
process (as it already is in many places).

-- 
Joseph S. Myers
joseph@codesourcery.com
Rical Jasan April 5, 2017, 3:08 a.m. UTC | #21
On 04/04/2017 04:26 AM, Joseph Myers wrote:
> On Tue, 4 Apr 2017, Rical Jasan wrote:

>> the files are parsed and entries stored.  Note that the locale is

>> respected, so different users may have differently-ordered Summary

>> chapters, but summary.awk appears to have done this as well.

> 

> Respecting the locale is a simple bug; LC_ALL=C should be used in the 

> makefile when running anything that does sorting etc. as part of the build 

> process (as it already is in many places).


But I like case insensitive sorting and expect exit, _Exit, and _exit to
all be together in my manual.  :P  Anyway, "fixed" locally.

Wrt. the patchset outline, how much of that would you like to see in v3?

If I don't also supply the completion patches, I'll leave out the
checking/enforcing bits in summary.pl to avoid breaking the build.
There would then be significantly less to review, and the new content
for completing the @standards can be a follow-up in a separate patchset.

If you think the proposed syntax is acceptable, I'll also need to make a
few tweaks to what I currently have, mostly so the conversion script
doesn't use @comma{} for multiple standards or headers.  I didn't begin
addressing special cases until the bulk of the conversion was already in
place, to see how it all panned out.

The syntax I'm proposing at this point looks like:

  @item FOO
  @standards{STD, HDR}

  @deftypefun foo
  @deftypefunx fool
  @standardsx{foo, STD, HDR}
  @standardsx{fool, STD, HDR}

  @item BAR
  @standards{STD1, HDR1}
  @standards{STD2, HDR2}

I believe that cleanly addresses both the generation of summary.texi and
the eventual rendering we'd like to have.  It does not address
canonicalization of standards names (which could be enforced later in
summary.pl), or whether or how to combine standards, those issues being
in a different scope.  Since the conversion creates the @standards from
the @comments used by summary.awk and @standards aren't rendered yet,
the status quo is maintained in that regard.

The headers and standards are essentially rendered as-is in the Summary,
with headers being wrapped in @file{}.  The Summary entries are as-is as
well, whether macros, variables, function prototypes, or what-have-you.
The entries are all @items in a @table that uses @code.

If we use the proposed syntax, there is also a choice of whether to
change the Summary accordingly, or do any extra work to keep it the
same.  Consider the following entry:

  @comment crypt
  @item char * crypt (const char *@var{key}, const char *@var{salt})

  @file{crypt.h} (BSD, SVID):  @ref{crypt}.

If we have in the manual:

  @item char * crypt (const char *@var{key}, const char *@var{salt})
  @standards{BSD, crypt.h}
  @standards{SVID, crypt.h}

The entry in summary.texi could become:

  @comment crypt
  @item char * crypt (const char *@var{key}, const char *@var{salt})

  @file{crypt.h} (BSD):  @ref{crypt}.

  @file{crypt.h} (SVID):  @ref{crypt}.

Currently, there is only a single line for every entry, so that also
changes the status quo for summary.texi, similar to ignoring locale.
This change is probably desirable, since it represents the same issue of
correlation we're trying to solve by allowing multiple @standards to
annotate a single element.  I suppose the downside is that it's a little
more verbose, but this is a reference manual.

Rical
Rical Jasan June 16, 2017, 8:28 a.m. UTC | #22
While recapping my completion patches, I realized I missed committing
these.  The comment below about committing the approved parts to reduce
volume later is what kicked off my getting commit access, but then I
jumped into @standards, which became v3.

I verified the substance of the patches was unchanged, and updated them
to use @standards.  Any deviations from the OK'd portions are noted
below.  Each of the files is considered complete by summary.pl when
enforcing.

On 12/07/2016 08:31 AM, Joseph Myers wrote:
> On Tue, 6 Dec 2016, Rical Jasan wrote:

> 

>> diff --git a/manual/argp.texi b/manual/argp.texi

>> index bca3ca5..f1767cc 100644

>> --- a/manual/argp.texi

>> +++ b/manual/argp.texi

> 

> All the changes to this file are OK.


Committed as 76b9ffef.

>> diff --git a/manual/arith.texi b/manual/arith.texi

>> index 0c182c5..eee9880 100644

>> --- a/manual/arith.texi

>> +++ b/manual/arith.texi

> 

> All the changes to this file are OK.  Note for when making annotations 

> more consistent in standard naming in future that:

> 

>> @@ -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 TS 18661-1:2014

>>  @deftypevrx Macro double SNAN

>> +@comment math.h

>> +@comment TS 18661-1:2014

>>  @deftypevrx Macro {long double} SNANL

> 

> All three are TS 18661-1:2014.


Since a single @standards can annotate all of these, I used "TS
18661-1:2014".

>> @@ -2041,8 +2055,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{}}

>> @@ -2063,8 +2079,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})

> 

> As are all these.


Also used "TS 18661-1:2014" with a single @standards.

Other deviations in this file:

  * _Imaginary_I was not converted because it is in an @ignore block.
  * The strfrom[dfl] annotations were completed in 7d641c41.

Committed as 1b009d5a.

>> diff --git a/manual/lang.texi b/manual/lang.texi

>> index 6281840..5e4d1d3 100644

>> --- a/manual/lang.texi

>> +++ b/manual/lang.texi

> 

> All the changes to this file are OK apart from the question of whether to 

> document __va_copy at all.


I think this file is better served by a different set of changes at this
point, so I will submit that for review separately.

>> diff --git a/manual/string.texi b/manual/string.texi

>> index 1986357..683a20f 100644

>> --- a/manual/string.texi

>> +++ b/manual/string.texi

> 

> All the changes to this file are OK.


Committed as a448ee41.

This one highlights an issue with summary.pl, where even when enforcing,
it currently doesn't catch these because the "???" placeholder is still
considered valid syntax (the annotated elements do have @standards).
However, this is something I took into consideration when writing the
script, so that once all the /^@standards.*\?\?\?/ have been addressed,
it should be a simple patch to consider it an error.

> I think the approved pieces should be committed to reduce the size of the 

> patch in future revisions.


Moving forward, I'll submit each chapter separately to help avoid that
problem.

Thank you,
Rical
Zack Weinberg June 16, 2017, 1:40 p.m. UTC | #23
On Tue, Apr 4, 2017 at 11:08 PM, Rical Jasan <ricaljasan@pacific.net> wrote:
> On 04/04/2017 04:26 AM, Joseph Myers wrote:

>> On Tue, 4 Apr 2017, Rical Jasan wrote:

>>> the files are parsed and entries stored.  Note that the locale is

>>> respected, so different users may have differently-ordered Summary

>>> chapters, but summary.awk appears to have done this as well.

>>

>> Respecting the locale is a simple bug; LC_ALL=C should be used in the

>> makefile when running anything that does sorting etc. as part of the build

>> process (as it already is in many places).

>

> But I like case insensitive sorting and expect exit, _Exit, and _exit to

> all be together in my manual.  :P  Anyway, "fixed" locally.


Would you please start a separate thread about this?  I can imagine
the indexes being more useful both ways, and we ought to be able to
arrange for ASCII-case-insensitive sorting independent of locale if we
conclude that it's a good idea.

(The most obvious question here is whether all the UPPERCASE_CONSTANTS
should get their own thumb notches, but there may be other factors.)

zw
diff mbox

Patch

diff --git a/manual/argp.texi b/manual/argp.texi
index bca3ca5..f1767cc 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 GNU
 @item ARGP_HELP_USAGE
 A unix @samp{Usage:} message that explicitly lists all options.
 
+@comment argp.h
+@comment GNU
 @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 GNU
 @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 GNU
 @item ARGP_HELP_LONG
 A verbose option help message that gives each option available along
 with its documentation string.
 
+@comment argp.h
+@comment GNU
 @item ARGP_HELP_PRE_DOC
 The part of the argp parser doc string preceding the verbose option help.
 
+@comment argp.h
+@comment GNU
 @item ARGP_HELP_POST_DOC
 The part of the argp parser doc string that following the verbose option help.
 
+@comment argp.h
+@comment GNU
 @item ARGP_HELP_DOC
 @code{(ARGP_HELP_PRE_DOC | ARGP_HELP_POST_DOC)}
 
+@comment argp.h
+@comment GNU
 @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 GNU
 @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 GNU
 @item ARGP_HELP_EXIT_ERR
 This will terminate the program with @code{exit (argp_err_exit_status)}.
 
+@comment argp.h
+@comment GNU
 @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 GNU
 @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 GNU
 @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 GNU
 @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 0c182c5..eee9880 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 C99
 @item FP_NAN
 The floating-point number @var{x} is ``Not a Number'' (@pxref{Infinity
 and NaN})
+@comment math.h
+@comment C99
 @item FP_INFINITE
 The value of @var{x} is either plus or minus infinity (@pxref{Infinity
 and NaN})
+@comment math.h
+@comment C99
 @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 C99
 @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 C99
 @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 TS 18661-1:2014
 @deftypevrx Macro double SNAN
+@comment math.h
+@comment TS 18661-1:2014
 @deftypevrx Macro {long double} SNANL
 These macros, defined by TS 18661-1:2014, are constant expressions for
 signaling NaNs.
@@ -2041,8 +2055,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{}}
@@ -2063,8 +2079,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{}}
@@ -2197,6 +2215,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 C99
 @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
@@ -2219,6 +2239,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 C99
 @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
@@ -2245,6 +2267,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 C99
 @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
@@ -2887,7 +2911,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 TS 18661-1:2014
 @deftypefunx int strfromf (char *restrict @var{string}, size_t @var{size}, const char *restrict @var{format}, float @var{value})
+@comment stdlib.h
+@comment TS 18661-1:2014
 @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 3880bc9..8ddb8b7 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 || XPG4
 @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 XPG4
 @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 XPG4
 @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 XPG4
 @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 XPG4
 @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 XPG4
 @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 XPG4
 @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 XPG4 && GNU
 @item FTW_ACTIONRETVAL
 If this option is specified then return values from callbacks
 are handled differently.  If the callback returns @code{FTW_CONTINUE},
@@ -3239,6 +3279,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 POSIX.1-2001
 @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,
@@ -3297,6 +3339,8 @@  allocation.  Instead, an @code{EOPNOTSUPP} is returned to the caller.
 
 @end deftypefun
 
+@comment fcntl.h
+@comment POSIX.1-2001 && LFS
 @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..b7f867b 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 POSIX.1-2001
 @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 6281840..5e4d1d3 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 GNU
 @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 9643bcb..dfefd4d 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 C90, POSIX.1, XOPEN || POSIX.1-2008
 @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 C90, POSIX.1, XOPEN || POSIX.1-2008
 @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 C90, POSIX.1, XOPEN || POSIX.1-2008
 @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
@@ -1250,6 +1262,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
@@ -1260,6 +1274,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
@@ -1269,13 +1285,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
@@ -1399,12 +1421,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
@@ -1491,22 +1517,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
@@ -1518,18 +1554,28 @@  The POSIX names are slightly different, but with the same meanings:
 
 @vtable @code
 
+@comment sys/mman.h
+@comment POSIX.1-2001
 @item POSIX_MADV_NORMAL
 This corresponds with BSD's @code{MADV_NORMAL}.
 
+@comment sys/mman.h
+@comment POSIX.1-2001
 @item POSIX_MADV_RANDOM
 This corresponds with BSD's @code{MADV_RANDOM}.
 
+@comment sys/mman.h
+@comment POSIX.1-2001
 @item POSIX_MADV_SEQUENTIAL
 This corresponds with BSD's @code{MADV_SEQUENTIAL}.
 
+@comment sys/mman.h
+@comment POSIX.1-2001
 @item POSIX_MADV_WILLNEED
 This corresponds with BSD's @code{MADV_WILLNEED}.
 
+@comment sys/mman.h
+@comment POSIX.1-2001
 @item POSIX_MADV_DONTNEED
 This corresponds with BSD's @code{MADV_DONTNEED}.
 
@@ -1584,6 +1630,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
@@ -1969,15 +2017,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
@@ -2904,47 +2958,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 || POSIX.1-2008
 @item F_GETOWN
 Get process or process group ID to receive @code{SIGIO} signals.
 @xref{Interrupt Input}.
 
+@comment fcntl.h
+@comment UNIX98 || POSIX.1-2008
 @item F_SETOWN
 Set process or process group ID to receive @code{SIGIO} signals.
 @xref{Interrupt Input}.
@@ -3919,6 +3999,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..953dc4d 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 && !POSIX.1-2001)
 @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 && !POSIX.1-2001)
 @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 5ad8732..f91d66d 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..b8dde63 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 C11
 @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 GNU
 @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 GNU
 @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 d6a1bfe..08ada58 100644
--- a/manual/signal.texi
+++ b/manual/signal.texi
@@ -1002,6 +1002,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
@@ -1009,6 +1011,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
@@ -3183,10 +3187,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}
@@ -3203,9 +3211,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 25d9276..32073fb 100644
--- a/manual/socket.texi
+++ b/manual/socket.texi
@@ -493,6 +493,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.
@@ -822,6 +823,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..070ce3d 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 XPG4 || POSIX.1-2008
 @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 GNU
 @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 dbb21ca..fc15202 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
@@ -5367,8 +5375,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
@@ -5378,10 +5390,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
@@ -5391,10 +5409,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
@@ -5403,8 +5427,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
@@ -5428,17 +5456,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
@@ -5452,14 +5492,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
@@ -5552,6 +5602,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..683a20f 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 C90
 @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 0c5fdd1..46b21e2 100644
--- a/manual/terminal.texi
+++ b/manual/terminal.texi
@@ -1843,14 +1843,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.
@@ -1895,15 +1901,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 47e28fe..1cae402 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
@@ -1445,10 +1447,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
@@ -1501,6 +1507,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: