This is the mail archive of the libc-alpha@sourceware.org mailing list for the glibc project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: Re: RFC: handling ISO C feature test macros


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


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]