Re: The goal of the Linux man-pages project

["Arsen Arsenović" <arsen@aarsen.me>]

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

Hi Alex,

Alejandro Colomar <alx@kernel.org> writes:

>> >     man/man3/: Put first <string.h> in SYNOPSIS, then comment about <memory.h>
>> >     
>> >     This is a compromise between the fact that <string.h> is the standard
>> >     header and (only slightly) most portable header file for these
>> >     functions, while hinting at the fact that it might be more appropriate
>> >     to use <memory.h> where possible.
>> >     
>> >     Remove the STANDARDS and NOTES about this, since now the SYNOPSIS
>> >     contains all the necessary information.  The extra info is in
>> >     memory.h(3head), which is linked to in the SYNOPSIS.
>> >
>> > What do you think?
>> 
>> Why, though?
>
> To help guide programmers to understand these APIs, and consequentially
> be able to write better code.  That's the goal of this project.  It's
> the Linux Programmer's Manual, and its purpose is that programmers on
> a Linux system are able to write correct programs.

First of, this doesn't answer the question I asked.  Why should this
change, even the "compromise", be done?

But, ignoring that this doesn't answer the question posed, how exactly
is hinting that it's "more appropriate to use <memory.h> where possible"
accomplishing the goals of the project you've stated there?

It seems to me to just sow confusion.

I think the references to <memory.h> should be confined to a single page
that documents what it is, memory.h(3head) or whatever, which should be
honest and say only:

  <memory.h> is an obsolete header.  It exists for compatibility with
  older programs, and is implemented as an alias of <string.h>.

This makes it clear that the header is never useful, and that it's
strictly redundant with <string.h>, in a way that still lets someone
reading old code discover it.

The latter, of course, being much more widely used, and standardized.
The former being used only to placate pre-standard programs.

It seems to me that your intent was also to standardize memory.h.  In
this I also see no benefit.  string.h can't be split at this point, nor
can the real memory.h installed by libcs be shrunk by removing str* from
it.

I'll skip the rest of the philosophizing about the purpose of the
man-pages project, but I will add that if the Linux man-pages project
starts diverging from harmless standard practice to promote
idiosyncrasies, I'll have no choice but to caution against relying on
it.

>> I think that, in the thread, it was already demonstrated (by Bionic
>> having an empty memory.h for a time) that nobody includes <memory.h> on
>> its own and expects to see these functions.
>
> This is part of 'factual information', which is only a secondary goal
> of this documentation project, as stated above.
>
> The purpose of this change is to help form a mental model of how these
> memory and string functions relate to each other, and how they behave.

The mental model is certainly not helped by prominently featuring a
long-dead headers which may (or may not!  as seen above) contain
declarations from <string.h> (which is a header you consequently have to
include anyway).

>> (not that Bionic is that
>> widely-used; a better test would be checking something like Debian
>> codesearch)
>> 
>> As I've noted before, what header provides what declaration is also
>> largely inconsequential.
>
> If it is largely inconsequential, I expect this change shouldn't be as
> controversial as it seemed to be.

It is largely inconsequential how a declaration is obtained from the
perspective of a programmer for reasons I've stated before.

The act of *documenting* a long dead non-standard header as a header
that provides some function has a consequence, that consequence being
that now a long-dead non-standard header gets included far more
frequently.

This means that its only effect is a detriment.

I think it's a far better idea to start emitting a warning when it is
included, to indicate that it's an obsolete non-standard header.

>> So, the only effect of this can be to create new cases where <memory.h>
>> is included, for no gain.
>
> I don't agree with the 'for no gain' claim.  But yes, the first part of
> the sentence is certainly true.

There is no gain, the programmer can't tell where a declaration comes
from, and this include is strictly redundant with string.h even on all
the various Linux systems.

>> It doesn't really matter that memory.h is only slightly less portable,
>> IMO.  It is unused, to the point where Autoconf recommends not using it,
>> and no longer bothers checking whether 'mem*' functions are also present
>> in string.h.
>
> It doesn't really matter that it is unused.  What matters is that it can
> be used just fine, [...]

Can it?  I don't accept that premise.  It's a non-standard header.

> [...] and will help --IMO-- understand these functions better.

I don't accept that either: I see no way in which understanding benefits
from this change.

>> Is suddenly reviving a dead header to copy a few declarations of
>> functions well known to be part of string.h into it not just unneeded
>> churn?  Especially as program code would (nearly?) always need to do:
>> 
>>   #include <string.h>
>>   #ifdef HAVE_MEMORY_H
>>   # include <memory.h>
>>   #endif
>
> Are there any systems without <memory.h>?  We've been seeing in this
> thread that most systems have it.  Even Microsoft has it.  I bet most
> programs can live without that conditional.
>
> I'd say most programs would be portable enough with this:
>
> 	#include <string.h>
> 	#include <memory.h>

And even more of them can live with:

  #include <string.h>

That said, I imagine that many systems do have it.  After all, it is
quite cheap to run the following during an install step:

  echo '#include <string.h>' > $(DESTDIR)$(includedir)/memory.h

... but, I also would not fault a system for not having it.

We could check what systems have it and whether any do anything besides
including string.h.

Or we could just avoid prominently featuring a long-dead non-standard
header.
-- 
Arsen Arsenović

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