Re: [PATCH v3] NULL.3const: Add documentation for NULL

[Alejandro Colomar <alx.manpages@gmail.com>]

[-- Attachment #1.1: Type: text/plain, Size: 4925 bytes --]

Hi Ingo,

On 7/27/22 12:49, Ingo Schwarze wrote:
> Hi Alejandro,
> 
> Alejandro Colomar wrote on Tue, Jul 26, 2022 at 02:02:56PM +0200:
>> On 7/25/22 20:49, Ingo Schwarze wrote:
>>> Alejandro Colomar wrote on Sun, Jul 24, 2022 at 09:19:32PM +0200:
> 
>>>> +.B 0
> 
>>> There is really no need to mark up integer constants.
> 
>> groff_man_style(7):
>>                 Use  bold for literal portions of syntax synopses,
>>                 for command‐line options in running text, and  for
>>                 literals  that are major topics of the subject un‐
>>                 der discussion; for example, this page  uses  bold
>>                 for  macro,  string,  and  register  names.  In an
>>                 .EX/.EE example of  interactive  I/O  (such  as  a
>>                 shell session), set only user input in bold.
>>
>> Since this is a literal that is a major topic of the subject under
>> discussion, I prefer to be a bit pedantic here and boldface it.
>>
>> I guess it's no big issue; does it hurt readability too much for you?
> 
> No, it's no big deal and doesn't hurt readability.  It only looks
> slightly unusual.
> 
> There are cases where a bare '0' character needs to be bold face,
> for example when discussing ".Fl 0" in xargs(1).  But here, you
> are just talking about the integer 0.  The "major topic" here
> is ".Dv NULL", not the ordinary integer 0 that is internally used
> to define that constant.
> Bold face is mostly for literals that the user needs to type -
> and the user is specifically *not* supposed to type this 0.

Well, the suggestion of not recommending typing 0 is one thing.

But, the thing is, it's not exactly the integer 0; 0 represents the null 
pointer in pointer contexts, even if the null pointer was for example 
0xFFFF on some weird platform.  Even in ISO C, where NULL is not defined 
to be (void *)0; some conforming platform could perfectly `#define (void 
*)-1`, but the platform should then still interpret literal `0` as if 
the user had typed `NULL`, or `(void *)-1`.

So, I really consider `0` as an alternative representation, of course 
worse than NULL, of the major topic "null pointer constant".

> 
> That's why i consider the .B pointless; then again, it does not
> do much harm either.
> 
> 
>>>> +.SH CONFORMING TO
> 
>>> That should be ".SH STANDARDS".
> 
>> We use CONFORMING TO in Linux.  Don't know why; just history, I guess.
>> See man-pages(7).
> 
> Weird.
> 
> I failed to find a single instance of "CONFORMING TO" in AT&T UNIX
> (including v6, PWB, v7, 32v, v8, v10, System III, SVR1, SVR2) nor in
> any version of UCB CSRG BSD.  So considering that System V and BSD are
> widely considered the two main original branches of the development
> of Unix-like operating systems and Linux is often considered to have
> drawn inspiration from both, the section name "CONFORMING TO" does
> not appear to be a UNIX thing.  For example, Aeleen Frisch, "Essential
> System Administration", O'Reilly, Cambridge 1995, considers Linux
> as slightly more influenced by 4.3BSD than by System V Release 3.
> 
> STANDARDS, on the other hand, is present since 4.3BSD-Reno (June 1990).
> 
> 4.3BSD-Reno predates the first version of the Linux kernel by more than
> a year, and the first Linux manual pages probably for longer than that.
> 
> So i have no idea where "CONFORMING TO" may have come from.

I don't like the idea of being inconsistent with other Unix systems with 
no good reason.  's/CONFORMING TO/STANDARDS/' might happen some day; 
just saying.

> 
> 
> [...]
>>>> +.SH BUGS
> 
>>> The following is misplaced in BUGS.  It is not talking about any bug,
>>> nor about any API design defect.
> 
>> Oh, I do consider this a bug in the API design.  I placed it there on
>> purpose.
>>
>> Allowing the bit pattern of all 0s to represent a valid pointer (and
>> thus not a null pointer) is something that could be meaningful many
>> decades ago, when architectures were more different.
>>
>> Nowadays, every arch out there is 2's complement, and uses 0s as the
>> null pointer.  The standard should simplify, and allow memset(2)ing
>> pointers.
>>
>> In fact, AFAIK, the next revision of POSIX will fix that bug.  But I
>> don't remember well the details of that.
> 
> Fair points.  You convinced me this isn't misplaced in BUGS.

Awww, I did! :-)

Still, I may completely remove that text, since it doesn't trigger in 
POSIX systems, AFAIK.  The bug is only theoretical in POSIX (and 
practical in non-POSIX, but that's outside of our scope).

I'm also considering a round of trimming 3type pages, by removing 
theoretical stuff that I added, that really doesn't matter in POSIX 
systems, or doesn't matter to users.

Yours,

Alex


> 
> Yours,
>    Ingo

-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]