Re: [PATCH v3 5/6] man2/chmod.2: add C digit separators to clarify POSIX feature release dates and long numeric digit strings

["G. Branden Robinson" <g.branden.robinson@gmail.com>]

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

Hi Tom,

At 2023-02-18T18:31:25+0000, Tom Schwindl wrote:
> > Do you expect C programmers to be more likely to copy and paste from
> > the man page source document or from the rendered page (probably in
> > a terminal window, but possibly from a PDF)?
> >
> 
> I expect them to copy & paste from the rendered page but I thought
> writing out "'" is a bit cumbersome so I refer to it as \[aq].

Ahh, that can be a bit confusing without clear context.  :D

> My "worry" with this was that new programmers could potentially
> execute a command like the following:
> 
>   $ cc -D_POSIX_C_SOURCE=1993'09L test.c
> 
> and wonder what they did wrong.

I see--that is a good point.  But I don't know that there is much the
man pages can do about that issue, apart from having a better intro(1)
page.  The scenario you imagine is an unfortunate consequence of the
grouping character WG14 selected.

New C programmers on *nix are going to have to develop some
sophistication with the POSIX shell language as well, and that will be
even more the case now--a cost of letting the Swiss win battles...

Mainly because Alex is reading, I will point out that Ada did this, and
several other aspects of numeric literals, right--40 years ago.

>> Numeric literals are all introduced by an initial digit. A
>> requirement that has long been recognized when printing numeric
>> tables is for a character to break up long sequences of digits: in
>> Ada, the underline character serves this purpose. In contrast to
>> identifiers, underlines in numeric literals do not alter the meaning,
>> so that 12_000 naturally has the same value as 12000.
>>
>> A simple sequence of digits is an integer literal written in decimal
>> notation. For other bases from 2 up to 16, the base is given first
>> and is followed by a sequence of digits enclosed by sharp characters
>> (#) or by colons (:), the colon being used as replacement character
>> for the sharp, but only when the sharp is not available. The enclosed
>> digits may include the letters A to F for bases greater than ten.
>> Thus, the conventional ways of expressing bit patterns in binary,
>> octal, or hexadecimal are provided.
>>
>> Real literals must contain a period, which represents the radix
>> point. They may be expressed in decimal notation or with other bases.
>> Finally, both integer and real literals may include the letter E
>> followed by an exponent.

http://archive.adaic.com/standards/83rat/html/ratl-02-01.html#2.1

But C programmers have long indulged in the sport of ignoring every
lesson any other programming language had to teach, whether through
careful design or blundering mistake.[1]  C'est la vie.

> But thinking about it a bit longer, copy & pasting from the rendered
> manpage might be the bigger issue.

This prospect was a major factor in my efforts to get groff's own man
pages much more fastidious in this respect, and to promulgate the usage
of appropriate special characters in man page sources, an initiative
that I'm not sure has yet taken flight, although Linux man-pages is
rapidly improving in this regard.  The real test is whether such careful
practice percolates elsewhere, where disinterest in (or outright
resentment of) writing documentation, in man(7), mdoc(7), or any other
form, is rampant.

Regards,
Branden

[1] Thompson discarded type checking and "//" comments from BCPL; the
    latter came back relatively painlessly (though only in C99, which
    Ritchie refused to endorse).  The former has been resurrected in
    fitful stages, and only where the suffering imposed by careless
    typing can be discerned as imposing engineering costs in defect
    resolution greater than in initial implementation by a factor of
    1,000 or more.

    https://www.bell-labs.com/usr/dmr/www/chist.html

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