manual: Refactor documentation of CHAR_BIT.

manual: Refactor documentation of CHAR_BIT.

[Rical Jasan]

[-- Attachment #1: Type: text/plain, Size: 585 bytes --]

This single-@item @table is better defined with @defvr, since the
CHAR_BIT macro has @standards (being declared in a header), and @items
in @tables are not considered annotatable.  Using @defvr automatically
includes the macro in the Variable and Constant Macro Index and
ensures its inclusion the Summary of Library Facilities.  The file
include/limits.h identifies the macro as coming from C99.

	* manual/lang.texi (CHAR_BIT): Convert from an @table to an
	@defvr.  Change standard from ISO to C99.
---
 manual/lang.texi | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0002-manual-Refactor-documentation-of-CHAR_BIT.patch --]
[-- Type: text/x-patch; name="0002-manual-Refactor-documentation-of-CHAR_BIT.patch", Size: 828 bytes --]

diff --git a/manual/lang.texi b/manual/lang.texi
index cf0e4e73cd..4b04232e3c 100644
--- a/manual/lang.texi
+++ b/manual/lang.texi
@@ -629,9 +629,8 @@ There is no operator in the C language that can give you the number of
 bits in an integer data type.  But you can compute it from the macro
 @code{CHAR_BIT}, defined in the header file @file{limits.h}.
 
-@table @code
-@item CHAR_BIT
-@standards{ISO, limits.h}
+@defvr Macro CHAR_BIT
+@standards{C99, limits.h}
 This is the number of bits in a @code{char}---eight, on most systems.
 The value has type @code{int}.
 
@@ -641,7 +640,7 @@ this:
 @smallexample
 sizeof (@var{type}) * CHAR_BIT
 @end smallexample
-@end table
+@end defvr
 
 That expression includes padding bits as well as value and sign bits.
 On all systems supported by @theglibc{}, standard integer types other

manual: Update @standards for [__]va_copy.

[Rical Jasan]

[-- Attachment #1: Type: text/plain, Size: 498 bytes --]

There is question as to whether __va_copy should be documented in the
glibc manual at all.  Since users searching for *va_copy are likely to
find this manual, and GCC doesn't document either, it is important we
continue to provide some kind of reference.

stdarg(3) documents va_copy as being introduced in C99.

	* lang.texi (va_copy): Change standard from ISO to C99.
	(__va_copy): Add standard and header annotation.
---
 manual/lang.texi | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-manual-Update-standards-for-__-va_copy.patch --]
[-- Type: text/x-patch; name="0001-manual-Update-standards-for-__-va_copy.patch", Size: 609 bytes --]

diff --git a/manual/lang.texi b/manual/lang.texi
index c4b641d4e1..cf0e4e73cd 100644
--- a/manual/lang.texi
+++ b/manual/lang.texi
@@ -471,7 +471,8 @@ of the same type.
 
 @deftypefn {Macro} void va_copy (va_list @var{dest}, va_list @var{src})
 @deftypefnx {Macro} void __va_copy (va_list @var{dest}, va_list @var{src})
-@standardsx{va_copy, ISO, stdarg.h}
+@standardsx{va_copy, C99, stdarg.h}
+@standardsx{__va_copy, GNU, stdarg.h}
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 @c This is no longer provided by glibc, but rather by the compiler.
 The @code{va_copy} macro allows copying of objects of type

Re: manual: Refactor documentation of CHAR_BIT.

[Zack Weinberg]

On 06/17/2017 04:42 AM, Rical Jasan wrote:
> This single-@item @table is better defined with @defvr, since the
> CHAR_BIT macro has @standards (being declared in a header), and @items
> in @tables are not considered annotatable.  Using @defvr automatically
> includes the macro in the Variable and Constant Macro Index and
> ensures its inclusion the Summary of Library Facilities.

This part of the change is OK.

> The file include/limits.h identifies the macro as coming from C99.

I think this macro really was in C90, and
http://flash-gordon.me.uk/ansi.c.txt includes it, which is the closest I
can come to checking.  Joseph, do you know for sure?

Note that the comment at the top of the header file

/*
 *      ISO C99 Standard: 7.10/5.2.4.2.1 Sizes of integer types <limits.h>
 */

should _not_ be taken to imply anything about which standard specifies
which bits of the header.  It's meant to point you to the core _overall_
specification for the header, and we seem to consistently refer to C99
for that even when the header existed in C90 (compare libio/stdio.h, for
instance).

zw

Re: manual: Update @standards for [__]va_copy.

[Zack Weinberg]

On 06/17/2017 04:42 AM, Rical Jasan wrote:
> There is question as to whether __va_copy should be documented in the
> glibc manual at all.  Since users searching for *va_copy are likely to
> find this manual, and GCC doesn't document either, it is important we
> continue to provide some kind of reference.

Let's leave alone the question of whether we should document a GCC
extension for now.

This patch is OK with some additional wording adjustments: in the second
paragraph of the @deftypefn block, change "This macro" to
"@code{va_copy}", "@samp{gcc -ansi}" to "@samp{gcc -std=c90}", and "The
macro @code{__va_copy} is available as a GNU extension;" to "GCC
provides @code{__va_copy}, as an extension, in any standards mode."
Delete the clause beginning "before GCC 3.0", as I believe compilers
that old will no longer work with glibc's headers anyway.

zw

Re: manual: Update @standards for [__]va_copy.

[Andreas Schwab]

On Jun 17 2017, Zack Weinberg <zackw@panix.com> wrote:

> Delete the clause beginning "before GCC 3.0", as I believe compilers
> that old will no longer work with glibc's headers anyway.

We still support ancient GCC versions.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: manual: Refactor documentation of CHAR_BIT.

[Joseph Myers]

On Sat, 17 Jun 2017, Zack Weinberg wrote:

> On 06/17/2017 04:42 AM, Rical Jasan wrote:
> > This single-@item @table is better defined with @defvr, since the
> > CHAR_BIT macro has @standards (being declared in a header), and @items
> > in @tables are not considered annotatable.  Using @defvr automatically
> > includes the macro in the Variable and Constant Macro Index and
> > ensures its inclusion the Summary of Library Facilities.
> 
> This part of the change is OK.
> 
> > The file include/limits.h identifies the macro as coming from C99.
> 
> I think this macro really was in C90, and
> http://flash-gordon.me.uk/ansi.c.txt includes it, which is the closest I
> can come to checking.  Joseph, do you know for sure?

CHAR_BIT is C90.

-- 
Joseph S. Myers
joseph@codesourcery.com

[PATCH v2] manual: Update @standards for [__]va_copy.

[Rical Jasan]

The ISO version in which va_copy was introduced is made explicit, and
__va_copy is given @standards.  The description is updated to be more
clear about the origins of each macro, and the reader is informed
these macros are now provided by the compiler (information previously
embedded in a Texinfo @comment).

	* lang.texi (va_copy): Change standard from ISO to C99.
	(__va_copy): Add standard and header annotation.
	Update description for clarity of origins and current use.
---
 manual/lang.texi | 15 +++++++++------
 1 file changed, 9 insertions(+), 6 deletions(-)

diff --git a/manual/lang.texi b/manual/lang.texi
index cacbdfb7c5..0ba002a396 100644
--- a/manual/lang.texi
+++ b/manual/lang.texi
@@ -471,18 +471,21 @@ of the same type.
 
 @deftypefn {Macro} void va_copy (va_list @var{dest}, va_list @var{src})
 @deftypefnx {Macro} void __va_copy (va_list @var{dest}, va_list @var{src})
-@standardsx{va_copy, ISO, stdarg.h}
+@standardsx{va_copy, C99, stdarg.h}
+@standardsx{__va_copy, GNU, stdarg.h}
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
-@c This is no longer provided by glibc, but rather by the compiler.
 The @code{va_copy} macro allows copying of objects of type
 @code{va_list} even if this is not an integral type.  The argument pointer
 in @var{dest} is initialized to point to the same argument as the
 pointer in @var{src}.
 
-This macro was added in ISO C99.  When building for strict conformance
-to ISO C90 (@samp{gcc -ansi}), it is not available.  The macro
-@code{__va_copy} is available as a GNU extension in any standards
-mode; before GCC 3.0, it was the only macro for this functionality.
+@code{va_copy} was added in ISO C99.  When building for strict
+conformance to ISO C90 (@samp{gcc -std=c90}), it is not available.
+GCC provides @code{__va_copy}, as an extension, in any standards mode;
+before GCC 3.0, it was the only macro for this functionality.
+
+These macros are no longer provided by @theglibc{}, but rather by the
+compiler.
 @end deftypefn
 
 If you want to use @code{va_copy} and be portable to pre-C99 systems,
-- 
2.12.2

[PATCH v2] manual: Refactor documentation of CHAR_BIT.

[Rical Jasan]

This single-@item @table is better defined with @deftypevr, since the
CHAR_BIT macro has @standards (being declared in a header), and @items
in @tables are not considered annotatable.  Using @deftypevr
automatically includes the macro in the Variable and Constant Macro
Index and ensures its inclusion the Summary of Library Facilities.
@deftypevr is used to record the type of the macro so that it also
appears in the Summary.

	* manual/lang.texi (CHAR_BIT): Convert from an @table to an
	@deftypevr.  Change standard from ISO to C90.
---
 manual/lang.texi | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/manual/lang.texi b/manual/lang.texi
index 0ba002a396..6d0a44062c 100644
--- a/manual/lang.texi
+++ b/manual/lang.texi
@@ -631,11 +631,9 @@ There is no operator in the C language that can give you the number of
 bits in an integer data type.  But you can compute it from the macro
 @code{CHAR_BIT}, defined in the header file @file{limits.h}.
 
-@table @code
-@item CHAR_BIT
-@standards{ISO, limits.h}
+@deftypevr Macro int CHAR_BIT
+@standards{C90, limits.h}
 This is the number of bits in a @code{char}---eight, on most systems.
-The value has type @code{int}.
 
 You can compute the number of bits in any data type @var{type} like
 this:
@@ -643,7 +641,7 @@ this:
 @smallexample
 sizeof (@var{type}) * CHAR_BIT
 @end smallexample
-@end table
+@end deftypevr
 
 That expression includes padding bits as well as value and sign bits.
 On all systems supported by @theglibc{}, standard integer types other
-- 
2.12.2

Re: manual: Refactor documentation of CHAR_BIT.

[Florian Weimer]

On 06/17/2017 10:42 AM, Rical Jasan wrote:
> +@defvr Macro CHAR_BIT
> +@standards{C99, limits.h}
>  This is the number of bits in a @code{char}---eight, on most systems.
>  The value has type @code{int}.

Current POSIX requires CHAR_BIT to be 8, and we might as well say so.

Thanks,
Florian

Re: manual: Refactor documentation of CHAR_BIT.

[Zack Weinberg]

On 06/20/2017 08:11 AM, Florian Weimer wrote:
> On 06/17/2017 10:42 AM, Rical Jasan wrote:
>> +@defvr Macro CHAR_BIT
>> +@standards{C99, limits.h}
>>  This is the number of bits in a @code{char}---eight, on most systems.
>>  The value has type @code{int}.
> 
> Current POSIX requires CHAR_BIT to be 8, and we might as well say so.

Specifically, that requirement was added in POSIX.1-2001 (aka Issue 6), per
http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/limits.h.html.

I agree that this should be mentioned.

zw

[PATCH v3] manual: Refactor documentation of CHAR_BIT.

[Rical Jasan]

This single-@item @table is better defined with @deftypevr, since the
CHAR_BIT macro has @standards (being declared in a header), and @items
in @tables are not considered annotatable.  Using @deftypevr
automatically includes the macro in the Variable and Constant Macro
Index and ensures its inclusion the Summary of Library Facilities.
@deftypevr is used to record the type of the macro so that it also
appears in the Summary.

The description is updated to mention a later POSIX requirement that
this macro have the value 8.

	* manual/lang.texi (CHAR_BIT): Convert from an @table to an
	@deftypevr.  Change standard from ISO to C90.  Mention the
	POSIX.1-2001 requirement of the value 8.
---
 manual/lang.texi | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)

diff --git a/manual/lang.texi b/manual/lang.texi
index c4b641d4e1..75af677dc9 100644
--- a/manual/lang.texi
+++ b/manual/lang.texi
@@ -628,11 +628,10 @@ There is no operator in the C language that can give you the number of
 bits in an integer data type.  But you can compute it from the macro
 @code{CHAR_BIT}, defined in the header file @file{limits.h}.
 
-@table @code
-@item CHAR_BIT
-@standards{ISO, limits.h}
-This is the number of bits in a @code{char}---eight, on most systems.
-The value has type @code{int}.
+@deftypevr Macro int CHAR_BIT
+@standards{C90, limits.h}
+This is the number of bits in a @code{char}.  POSIX.1-2001 requires
+this to be 8.
 
 You can compute the number of bits in any data type @var{type} like
 this:
@@ -640,7 +639,7 @@ this:
 @smallexample
 sizeof (@var{type}) * CHAR_BIT
 @end smallexample
-@end table
+@end deftypevr
 
 That expression includes padding bits as well as value and sign bits.
 On all systems supported by @theglibc{}, standard integer types other
-- 
2.12.2

Re: [PATCH v3] manual: Refactor documentation of CHAR_BIT.

[Florian Weimer]

On 06/20/2017 03:44 PM, Rical Jasan wrote:
> @@ -628,11 +628,10 @@ There is no operator in the C language that can give you the number of
>  bits in an integer data type.  But you can compute it from the macro
>  @code{CHAR_BIT}, defined in the header file @file{limits.h}.

Sorry for scope creep, but the paragraph is inaccurate: We now have
*_WIDTH macros, and you actually cannot easily compute the number of
usable bits in a portable manner.

Rest of the patch looks fine to me.

Thanks,
Florian

[PING] [PATCH v2] manual: Update @standards for [__]va_copy.

[Rical Jasan]

Ping

The review of v1 had some difference of opinion [1] regarding the
mention of GCC 3.0.  I left it in, but addressed the other comments [2].

Rical

[1] https://sourceware.org/ml/libc-alpha/2017-06/msg00768.html
[2] https://sourceware.org/ml/libc-alpha/2017-06/msg00765.html

On 06/20/2017 04:03 AM, Rical Jasan wrote:
> The ISO version in which va_copy was introduced is made explicit, and
> __va_copy is given @standards.  The description is updated to be more
> clear about the origins of each macro, and the reader is informed
> these macros are now provided by the compiler (information previously
> embedded in a Texinfo @comment).
> 
> 	* lang.texi (va_copy): Change standard from ISO to C99.
> 	(__va_copy): Add standard and header annotation.
> 	Update description for clarity of origins and current use.
> ---
>  manual/lang.texi | 15 +++++++++------
>  1 file changed, 9 insertions(+), 6 deletions(-)
> 
> diff --git a/manual/lang.texi b/manual/lang.texi
> index cacbdfb7c5..0ba002a396 100644
> --- a/manual/lang.texi
> +++ b/manual/lang.texi
> @@ -471,18 +471,21 @@ of the same type.
>  
>  @deftypefn {Macro} void va_copy (va_list @var{dest}, va_list @var{src})
>  @deftypefnx {Macro} void __va_copy (va_list @var{dest}, va_list @var{src})
> -@standardsx{va_copy, ISO, stdarg.h}
> +@standardsx{va_copy, C99, stdarg.h}
> +@standardsx{__va_copy, GNU, stdarg.h}
>  @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> -@c This is no longer provided by glibc, but rather by the compiler.
>  The @code{va_copy} macro allows copying of objects of type
>  @code{va_list} even if this is not an integral type.  The argument pointer
>  in @var{dest} is initialized to point to the same argument as the
>  pointer in @var{src}.
>  
> -This macro was added in ISO C99.  When building for strict conformance
> -to ISO C90 (@samp{gcc -ansi}), it is not available.  The macro
> -@code{__va_copy} is available as a GNU extension in any standards
> -mode; before GCC 3.0, it was the only macro for this functionality.
> +@code{va_copy} was added in ISO C99.  When building for strict
> +conformance to ISO C90 (@samp{gcc -std=c90}), it is not available.
> +GCC provides @code{__va_copy}, as an extension, in any standards mode;
> +before GCC 3.0, it was the only macro for this functionality.
> +
> +These macros are no longer provided by @theglibc{}, but rather by the
> +compiler.
>  @end deftypefn
>  
>  If you want to use @code{va_copy} and be portable to pre-C99 systems,
> 

Re: [PATCH v3] manual: Refactor documentation of CHAR_BIT.

[Rical Jasan]

On 06/22/2017 06:23 AM, Florian Weimer wrote:
> On 06/20/2017 03:44 PM, Rical Jasan wrote:
>> @@ -628,11 +628,10 @@ There is no operator in the C language that can give you the number of
>>  bits in an integer data type.  But you can compute it from the macro
>>  @code{CHAR_BIT}, defined in the header file @file{limits.h}.
> 
> Sorry for scope creep, but the paragraph is inaccurate: We now have
> *_WIDTH macros, and you actually cannot easily compute the number of
> usable bits in a portable manner.
> 
> Rest of the patch looks fine to me.
> 
> Thanks,
> Florian

Can I commit the refactoring [1] and prepare a follow-up patch?  The
issues you point out in the diff context go even further in this
section.  The issues I see are:

  * The name of the section itself is "Computing the Width of an Integer
Data Type", which is probably better named "Width of an Integer Type"
now (and would be consistent with the following section "Range of an
Integer Type").

  * The bit vector example could use LONG_WIDTH.

  * If the computation of the number of bits in any given data type
isn't possible using CHAR_BIT, that example needs to be either removed
or given a @strong{Portability Note:} (and updated with a better
example, if possible).

  * Simply removing the inaccurate paragraph doesn't improve the
section; it should still say something to introduce CHAR_BIT, which
provided the practical example of computing LONGBITS for the bit vector
example that introduced the section.

Basically, it just needs to be rewritten...

Rical

[1] https://sourceware.org/ml/libc-alpha/2017-06/msg00915.html

Re: [PATCH v3] manual: Refactor documentation of CHAR_BIT.

[Florian Weimer]

On 07/27/2017 01:28 PM, Rical Jasan wrote:
> On 06/22/2017 06:23 AM, Florian Weimer wrote:
>> On 06/20/2017 03:44 PM, Rical Jasan wrote:
>>> @@ -628,11 +628,10 @@ There is no operator in the C language that can give you the number of
>>>  bits in an integer data type.  But you can compute it from the macro
>>>  @code{CHAR_BIT}, defined in the header file @file{limits.h}.
>>
>> Sorry for scope creep, but the paragraph is inaccurate: We now have
>> *_WIDTH macros, and you actually cannot easily compute the number of
>> usable bits in a portable manner.
>>
>> Rest of the patch looks fine to me.
>>
>> Thanks,
>> Florian
> 
> Can I commit the refactoring [1] and prepare a follow-up patch?  The
> issues you point out in the diff context go even further in this
> section.

Sure, please go ahead.  Note that the hard freeze is starting really
soon now.

Thanks,
Florian

Re: [PATCH v3] manual: Refactor documentation of CHAR_BIT.

[Rical Jasan]

On 07/27/2017 04:31 AM, Florian Weimer wrote:
> On 07/27/2017 01:28 PM, Rical Jasan wrote:
>> Can I commit the refactoring [1] and prepare a follow-up patch?  The
>> issues you point out in the diff context go even further in this
>> section.
> Sure, please go ahead.  Note that the hard freeze is starting really
> soon now.

Committed as d3675d95.

I've submitted a proposal for the larger documentation changes.

Thank you,
Rical

[PING] [PATCH v2] manual: Update @standards for [__]va_copy.

[Rical Jasan]

Ping^2

On 06/20/2017 04:03 AM, Rical Jasan wrote:
> The ISO version in which va_copy was introduced is made explicit, and
> __va_copy is given @standards.  The description is updated to be more
> clear about the origins of each macro, and the reader is informed
> these macros are now provided by the compiler (information previously
> embedded in a Texinfo @comment).
> 
> 	* lang.texi (va_copy): Change standard from ISO to C99.
> 	(__va_copy): Add standard and header annotation.
> 	Update description for clarity of origins and current use.
> ---
>  manual/lang.texi | 15 +++++++++------
>  1 file changed, 9 insertions(+), 6 deletions(-)
> 
> diff --git a/manual/lang.texi b/manual/lang.texi
> index cacbdfb7c5..0ba002a396 100644
> --- a/manual/lang.texi
> +++ b/manual/lang.texi
> @@ -471,18 +471,21 @@ of the same type.
>  
>  @deftypefn {Macro} void va_copy (va_list @var{dest}, va_list @var{src})
>  @deftypefnx {Macro} void __va_copy (va_list @var{dest}, va_list @var{src})
> -@standardsx{va_copy, ISO, stdarg.h}
> +@standardsx{va_copy, C99, stdarg.h}
> +@standardsx{__va_copy, GNU, stdarg.h}
>  @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> -@c This is no longer provided by glibc, but rather by the compiler.
>  The @code{va_copy} macro allows copying of objects of type
>  @code{va_list} even if this is not an integral type.  The argument pointer
>  in @var{dest} is initialized to point to the same argument as the
>  pointer in @var{src}.
>  
> -This macro was added in ISO C99.  When building for strict conformance
> -to ISO C90 (@samp{gcc -ansi}), it is not available.  The macro
> -@code{__va_copy} is available as a GNU extension in any standards
> -mode; before GCC 3.0, it was the only macro for this functionality.
> +@code{va_copy} was added in ISO C99.  When building for strict
> +conformance to ISO C90 (@samp{gcc -std=c90}), it is not available.
> +GCC provides @code{__va_copy}, as an extension, in any standards mode;
> +before GCC 3.0, it was the only macro for this functionality.
> +
> +These macros are no longer provided by @theglibc{}, but rather by the
> +compiler.
>  @end deftypefn
>  
>  If you want to use @code{va_copy} and be portable to pre-C99 systems,

Re: [PATCH v2] manual: Update @standards for [__]va_copy.

[Florian Weimer]

On 06/20/2017 01:03 PM, Rical Jasan wrote:
> The ISO version in which va_copy was introduced is made explicit, and
> __va_copy is given @standards.  The description is updated to be more
> clear about the origins of each macro, and the reader is informed
> these macros are now provided by the compiler (information previously
> embedded in a Texinfo @comment).
> 
> 	* lang.texi (va_copy): Change standard from ISO to C99.
> 	(__va_copy): Add standard and header annotation.
> 	Update description for clarity of origins and current use.

Looks good to me.

Thanks,
Florian

Re: [PATCH v2] manual: Update @standards for [__]va_copy.

[Rical Jasan]

On 08/10/2017 09:34 AM, Florian Weimer wrote:
> On 06/20/2017 01:03 PM, Rical Jasan wrote:
>> The ISO version in which va_copy was introduced is made explicit, and
>> __va_copy is given @standards.  The description is updated to be more
>> clear about the origins of each macro, and the reader is informed
>> these macros are now provided by the compiler (information previously
>> embedded in a Texinfo @comment).
>>
>> 	* lang.texi (va_copy): Change standard from ISO to C99.
>> 	(__va_copy): Add standard and header annotation.
>> 	Update description for clarity of origins and current use.
> 
> Looks good to me.

Thank you.  Committed.

Rical