This is the mail archive of the
libc-alpha@sourceware.org
mailing list for the glibc project.
Re: Re: RFC: handling ISO C feature test macros
- From: Rical Jasan <ricaljasan at pacific dot net>
- To: Joseph Myers <joseph at codesourcery dot com>, Roland McGrath <roland at hack dot frob dot com>
- Cc: libc-alpha at sourceware dot org
- Date: Fri, 3 Jun 2016 02:52:34 -0700
- Subject: Re: Re: RFC: handling ISO C feature test macros
- Authentication-results: sourceware.org; auth=none
- References: <alpine dot DEB dot 2 dot 20 dot 1606022153110 dot 9542 at digraph dot polyomino dot org dot uk>
On 06/02/2016 03:29 PM, Joseph Myers wrote:
>> * generate or cross-check that information in the manual (and make it
>> > easy to do the same for linux man pages, though that is not directly
>> > our problem)
> The manual doesn't have such information in any systematic form at all at
> present.
>
> * Various functions say in free-text form where they came from.
>
> * There are the "@comment stdio.h", "@comment ISO" etc. before definitions
> in the manual, used to generate summary.texi. There is no actual defined
> list of standard names used in those comments, and they sometimes e.g.
> distinguish "BSD" and "SVID", a distinction no longer made in the headers.
>
> Might the following be a desired state for the manual? The @comment
> entries are replaced by macros like those used for safety information.
> Those expand to a statement of what standards the function is in / headers
> and feature test macros are required to use it. The standards mentioned
> are limited to those relevant to feature test macros, so MISC or DEFAULT
> in place of BSD / SVID for __USE_MISC functions. Those entries could be
> verified automatically based on including the headers with different
> macros defined - given information about which standards are relevant with
> which headers (as declarations are unconditional in a header if they are
> present for all standards with that header, even if not all standards
> supported by glibc). (There would of course be complications for
> declarations only present for some systems, but the manual ought to
> indicate such cases anyway.) Free-form text about standards for
> individual functions could be removed if felt not to add anything useful
> to the macro calls, but that would be a separate cleanup.
I like that you mention this, because one of the things that struck me
in my read through the manual was exactly this free-form style of
annotation and the way its non-definitive nature only raised the
question as to whether the information was still timely, correct, or
relevant.
I have some notes-to-future-self about addressing some related issues,
but I'm in no place to vet whether things belong to a particular
standard or provide any historical insights on them; e.g., when they
were introduced, were they subsequently deprecated, etc. One cleanup I
intended to ask about later was creating something like '@gnuext{}',
which could be placed in descriptions, and expand to the sentence "This
function is a GNU extension." (Or variable, etc., as appropriate.)
Aside from the benefits of making the sentence shorter to type and
guaranteeing they are all annotated in a consistent way (beats grepping
for all the variations on "GNU extension", including accounting for
word/line boundaries), there was something about reading the same phrase
written the same way scattered throughout the manual that made it feel
reliable, and also easy to recognize.
Another cleanup -- and one I felt was more important than @gnuext{} --
was putting the reference to the relevant header file *in every
description*. In the past, when I've simply used the manual as a
reference, it's a total pain when you have to go searching around the
rest of the section or chapter hoping to find where that thing was
declared. I say felt because that was before I found Appendix B, the
summary, but it would still be nice to have all the information you
needed to use the thing included in its description---and all the
descriptions do have the aforementioned "@c fcntl.h" sitting right above
them in the .texi files right along with "@c POSIX.1" or "@c Unix98".
So, to the answer the question, yes, something like that does sound
desirable. The manual could use a lot of work in becoming more cohesive
and comprehensive.
Hear, hear.
Rical