Patchwork manual: Refactor documentation of CHAR_BIT.

login
register
mail settings
Submitter Rical Jasan
Date June 17, 2017, 8:42 a.m.
Message ID <20170617084202.4662-2-ricaljasan@pacific.net>
Download mbox | patch
Permalink /patch/21062/
State New
Headers show

Comments

Rical Jasan - June 17, 2017, 8:42 a.m.
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(-)
Zack Weinberg - June 17, 2017, 1:53 p.m.
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
Joseph Myers - June 19, 2017, 3:01 p.m.
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.
Florian Weimer - June 20, 2017, 12:11 p.m.
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
Zack Weinberg - June 20, 2017, 12:16 p.m.
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

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