[v3] manual: Refactor documentation of CHAR_BIT.

  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(-)
  

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
  

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
  

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
  

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