documenting multiple standards
>From wcrtomb(3): The wcrtomb() function conforms to ISO/IEC 9899/AMD1:1995 (``ISO C90, Amendment 1''). The restrict qualifier is added at ISO/IEC 9899/1999 (``ISO C99''). This wording is confusing. Is it implying that we don't use a restrict qualifier? (We do.) If a standard changes, do we have to document how the old standard differs from what we currently follow? That seems awfully complicated. Can we just document the latest standard, or "the earliest standard that doesn't appreciably differ from the latest standard"? What's the guiding practice here?
Re: documenting multiple standards
On Sun, Oct 25, 2015 at 12:58 AM, Anthony J. Bentleywrote: > From wcrtomb(3): > > The wcrtomb() function conforms to ISO/IEC 9899/AMD1:1995 (``ISO C90, > Amendment 1''). The restrict qualifier is added at ISO/IEC 9899/1999 > (``ISO C99''). > > This wording is confusing. Is it implying that we don't use a restrict > qualifier? (We do.) > > If a standard changes, do we have to document how the old standard > differs from what we currently follow? That seems awfully complicated. > Can we just document the latest standard, or "the earliest standard > that doesn't appreciably differ from the latest standard"? > > What's the guiding practice here? I agree.
Re: documenting multiple standards
On Sun, Oct 25, 2015 at 01:58:21AM -0600, Anthony J. Bentley wrote: > >From wcrtomb(3): > > The wcrtomb() function conforms to ISO/IEC 9899/AMD1:1995 (``ISO C90, > Amendment 1''). The restrict qualifier is added at ISO/IEC 9899/1999 > (``ISO C99''). > > This wording is confusing. Is it implying that we don't use a restrict > qualifier? (We do.) > > If a standard changes, do we have to document how the old standard > differs from what we currently follow? That seems awfully complicated. > Can we just document the latest standard, or "the earliest standard > that doesn't appreciably differ from the latest standard"? > > What's the guiding practice here? > common sense ;) we have a very consistent text for STANDARDS in userland. but the stuff in sections 2 and 3 have been added bit by bit, so there's a lot of differences. in the text for wcrtomb.3, it does look like DESCRIPTION needs updating to document "restrict". but the text in STANDARDS is not trying to say restrict was added later but unsupported by us. you could look at changing that text, but it'd be best if it were done consistently across sections 2 and 3, not just for one page. there is no attempt to document differences in previous standards. really you just want to note whether something is relevant to a (recent) standard, broadly whether our implementation conforms, and broadly how our implementation differs. it's a time consuming exercise. jmc
Re: documenting multiple standards
>>From wcrtomb(3): > > The wcrtomb() function conforms to ISO/IEC 9899/AMD1:1995 (``ISO C90, > Amendment 1''). The restrict qualifier is added at ISO/IEC 9899/1999 > (``ISO C99''). > >This wording is confusing. Is it implying that we don't use a restrict >qualifier? (We do.) > >If a standard changes, do we have to document how the old standard >differs from what we currently follow? That seems awfully complicated. >Can we just document the latest standard, or "the earliest standard >that doesn't appreciably differ from the latest standard"? > >What's the guiding practice here? Man pages should documnet what people need, trying to avoid ambiguity or overpreciseness. True or false: The wcrtomb() function conforms to ISO/IEC 9899/1999 (``ISO C99'').