Re: [PATCH 1/4] system_data_types.7: Add '__int128'

["Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>]

Hi Florian,

On 10/5/20 9:12 AM, Florian Weimer wrote:
> * Paul Eggert:
> 
>> On 10/2/20 12:01 PM, Alejandro Colomar wrote:
>>> If you propose not to document the stdint types either,
>>
>> This is not a stdint.h issue. __int128 is not in stdint.h and is not a
>> system data type in any real sense; it's purely a compiler
>> issue. Besides, do we start repeating the GCC manual too, while we're
>> at it? At some point we need to restrain ourselves and stay within the
>> scope of the man pages.
> 
> The manual pages also duplicate the glibc manual, and as far as I know,
> it's what programmers actually read.  (Downstream, we receive many more
> man-pages bugs than glibc or GCC manual bugs.)  Most developers use
> distributions 

I presume by most you mean "Debian + Ubuntu"? (The certainly
reflects what I see.)

> which do not ship the glibc or GCC manual for licensing
> policy reasons, so the GNU manuals are not installed locally.

I hadn't quite clicked to this point. So, Debian (and thus
Ubuntu) do not ship the glibc manual because of GNU FDL. That's 
unfortunate. (Many years ago, IIRC, there were still one of
two GNU FDL licensed pages in man-pages, and I rewrote / removed
the pages to eliminate the problem for Debian--and I was happy also
at the same time to reduce the number of licenses in man-pages.)

>> PS. Have you ever tried to use __int128 in real code? I have, to my
>> regret. It's a portability and bug minefield and should not be used
>> unless you really know what you're doing, which most people do not.
> 
> Doesn't this suggest we need improved documentation?

Well, yes. But I'm also not convinced man-pages is the right
place for it.

Thanks,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/