documenting multiple standards

[Anthony J. Bentley]

>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

[Philip Guenther]

On Sun, Oct 25, 2015 at 12:58 AM, 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?

I agree.

Re: documenting multiple standards

[Jason McIntyre]

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

[Theo de Raadt]

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