[PATCH] man7/: ffix

[PATCH] man7/: ffix

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx@kernel.org>
---

Hi Branden,

Should I apply this patch?  I'm not sure if the variable part should be
bold because it's part of a heading or roman because it's variable part
within italics.  How would you format it?

Thanks,

Alex


 man7/time_namespaces.7 | 2 +-
 man7/user_namespaces.7 | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/man7/time_namespaces.7 b/man7/time_namespaces.7
index 708099934..8c31b5f95 100644
--- a/man7/time_namespaces.7
+++ b/man7/time_namespaces.7
@@ -56,7 +56,7 @@ .SH DESCRIPTION
 .BR setns (2)
 in order to move into the namespace.)
 .\"
-.SS /proc/\fIpid\fP/timens_offsets
+.SS \fI/proc/\fPpid\fI/timens_offsets\fP
 Associated with each time namespace are offsets,
 expressed with respect to the initial time namespace,
 that define the values of the monotonic and
diff --git a/man7/user_namespaces.7 b/man7/user_namespaces.7
index 6647b02bf..737dd54ad 100644
--- a/man7/user_namespaces.7
+++ b/man7/user_namespaces.7
@@ -739,7 +739,7 @@ .SS Interaction with system calls that change process UIDs or GIDs
 .\"
 .\" ============================================================
 .\"
-.SS The /proc/\fIpid\fP/setgroups file
+.SS The \fI/proc/\fPpid\fI/setgroups\fP file
 .\"
 .\" commit 9cc46516ddf497ea16e8d7cb986ae03a0f6b92f8
 .\" commit 66d2f338ee4c449396b6f99f5e75cd18eb6df272
-- 
2.39.2

Re: [PATCH] man7/: ffix

[G. Branden Robinson]

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

Hi Alex,

Short answer: take the patch.  :)

At 2023-03-12T12:02:04+0100, Alejandro Colomar wrote:
> Should I apply this patch?  I'm not sure if the variable part should
> be bold because it's part of a heading or roman because it's variable
> part within italics.  How would you format it?

> diff --git a/man7/time_namespaces.7 b/man7/time_namespaces.7
> index 708099934..8c31b5f95 100644
> --- a/man7/time_namespaces.7
> +++ b/man7/time_namespaces.7
[...]
> -.SS /proc/\fIpid\fP/timens_offsets
> +.SS \fI/proc/\fPpid\fI/timens_offsets\fP
[...]
> diff --git a/man7/user_namespaces.7 b/man7/user_namespaces.7
> index 6647b02bf..737dd54ad 100644
> --- a/man7/user_namespaces.7
> +++ b/man7/user_namespaces.7
[...]
> -.SS The /proc/\fIpid\fP/setgroups file
> +.SS The \fI/proc/\fPpid\fI/setgroups\fP file

Long answer:

This is one of those cases where man(7) isn't expressive enough to suit
me, for precisely the reason you identify.  Because we largely don't
have semantic tags, we can't mark "pid" semantically and let the context
determine the styling.

I prefer the former to the latter, and would apply the patch.  In groff
1.23.0 (which still doesn't have its final tag :( ), the man(7) macro
package remaps the `I` (italic) style to `BI` (bold+italic) if it is
available and the font being used for (subsection) headings is
configured to be bold.  (The heading font has been configurable via the
`HF` string since groff 1.19, February 2004.)

So what will happen here, in groff 1.23 and the future, is that the file
name will be rendered mostly in bold italics, but the variable portion
will appear in upright bold.

However, if it were my man page, I might recast the headings entirely to
describe the files--or rather their purpose--in English, avoiding both
the use of escape sequences and concern with typeface changes.

.SS "Setting offsets in time name spaces" \" yes, name spaces (sic)
.SS "Enabling processes to change effective group membership" \" ?

But I will understand if you want to stick with the proposed patch, for
two reasons.

(1) Adopting my proposal means getting into another word-division fight
    with C programmers (perhaps influenced by C++ keywords) who port
    their identifier typography directly into English without
    alteration, as also discussed on linux-man in the past day or so;
    and

(2) I've inverted the discursive orientation of the material.
    Generally, I think (sub)section headings in a man page should be
    _broadly categorical_ or should address themselves to operations a
    user wants to perform, or tasks they want to achieve.  Another
    popular approach, seen here, is to use the man page as a sort of
    index for file system objects, so people reading the man page in
    full or trying to answer the question "what does this file do?" will
    be more readily enlightened.

    Both of these are legitimate purposes, and the latter is easier to
    write, which I think partly explains its popularity among those who
    are tasked by others with writing documentation and would prefer to
    get back to hacking.  If your new kernel subsystem creates
    /proc/$$/foo/{bar,baz,qux} for every process, you can proclaim your
    section 7 man page "done" once you've written a paragraph for each
    of these items.  Your manager will eagerly sign off so as to get you
    back to more "productive" work, like performance tuning so that they
    can in turn try to impress their own bosses with a chart on a
    PowerPoint slide.  (Bonus points if they characterize the shape of
    _any_ curve as "exponential".)

    And it is better than nothing.  But as a rule I think it is better
    to present a catalog in a tagged list, and spend time thinking about
    what it is that conceptually unifies that list.  Doing so tends to
    lead to an introductory paragraph preceding the list that makes it
    clear to everyone why the list is present and when people should
    care about it.  Observe how many man pages pass immediately from a
    (sub)section heading to one of these lists.[1]  This is often a
    tell-tale sign that the unifying thinking, the writer's craft of
    getting above the worm's-eye view of technical detail, has been
    omitted.  I won't claim that groff's own man pages are perfect in
    this respect.  They never will be, but maybe I can improve them
    further given another five years...

Regards,
Branden

[1] (groff war story)

    As I recall, a few years ago Ingo Schwarze once lobbied me to take
    out the "Options" sections of groff's section 1 man pages using a
    similar argument, claiming that options should be motivated and
    discussed within the "Description" section in a more organic manner.
    (And I did in fact change our nroff(1) page to do this, to test out
    his advice and because GNU nroff is a wrapper--nearly all its
    options are synonymous with groff(1) or troff(1) options).  He's not
    wrong, but because GNU programs tend to have many options (also a
    defect, in his view and others', like Rob Pike[2]) and because man
    pages are so frequently consulted to determine what a command option
    is for, I decided I could not dispense with them.

    Another reform to groff's man pages that I undertook was to begin
    shifting more discursive material earlier in the page.  A popular
    approach to man page organization for section 1 and 8 pages is to
    have a single paragraph of overview followed immediately by the
    "Options" section, which promptly starts referring to technical
    details, sometimes obscure ones, that the reader must already
    comprehend or which are not properly presented until later in the
    document.  As you may suspect, I dislike that.  Ingo felt that if I
    was going to have an Options section at all, I should keep it up
    high so it would at least start on the first pager screen--I think
    this was meant for the convenience of the expert reader.  But I
    think this approach sacrifices too much accessibility to the
    learner.  One should be able to read a man page linearly and feel
    one's understanding of the topic building.  Some people would retort
    that man pages are meant as a reference, not a tutorial.  My counter
    is that while they generally aren't tutorials, terming one's page a
    "reference" does not excuse one from covering the domain-specific
    knowledge that another needs to acquire to competently use the
    software at issue.  I think the boot(8) and crash(8) pages from the
    V7 Unix manual (1979) are examples, from an esteemed source, of how
    discursive--nigh-on tutorial--a man page of good reputation can get.

    My opinion is that the reader who is already familiar with the
    page's material can type "/Options" in their pager to navigate there
    if they are in a hurry.  Alternatively, thanks to Deri James, they
    can view man pages as PDFs, open up the navigation pane of their PDF
    viewer, and click on "Options".  A good conversion to HTML enables
    this, too.

[2] http://harmful.cat-v.org/cat-v/

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

Re: [PATCH] man7/: ffix

[Alejandro Colomar]

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

Hi Branden,

On 3/12/23 17:44, G. Branden Robinson wrote:
> Hi Alex,
> 
> Short answer: take the patch.  :)

I pushed it earlier today.  :)

> At 2023-03-12T12:02:04+0100, Alejandro Colomar wrote:
>> Should I apply this patch?  I'm not sure if the variable part should
>> be bold because it's part of a heading or roman because it's variable
>> part within italics.  How would you format it?

[...]

> Long answer:

[...]

> I prefer the former to the latter, and would apply the patch.

Good.

>  In groff
> 1.23.0 (which still doesn't have its final tag :( ), the man(7) macro
> package remaps the `I` (italic) style to `BI` (bold+italic) if it is
> available and the font being used for (subsection) headings is
> configured to be bold.

Yup, I tested it only with 1.23.0-rc3.  I assume 1.22.4 will do
something reasonable, but probably not so good.

[...]

> However, if it were my man page, I might recast the headings entirely to
> describe the files--or rather their purpose--in English, avoiding both
> the use of escape sequences and concern with typeface changes.

It doesn't itch me enough to do the work.  :)

[...]

> 
> [1] (groff war story)
> 
>     As I recall, a few years ago Ingo Schwarze once lobbied me to take
>     out the "Options" sections of groff's section 1 man pages using a
>     similar argument, claiming that options should be motivated and
>     discussed within the "Description" section in a more organic manner.
>     (And I did in fact change our nroff(1) page to do this, to test out
>     his advice and because GNU nroff is a wrapper--nearly all its
>     options are synonymous with groff(1) or troff(1) options).  He's not
>     wrong, but because GNU programs tend to have many options (also a
>     defect, in his view and others', like Rob Pike[2]) and because man
>     pages are so frequently consulted to determine what a command option
>     is for, I decided I could not dispense with them.

Heh, I remember having some problem related to this reading mandoc(1)
(or maybe it was mdoc(7)).  I don't remember which it was, but having
a quick look at mandoc(1), I found some flag insufficiently documented:
'-l'.  See the only mentions in his page:

       MANPAGER  Any  non‐empty  value  of  the  environment  variable
                 MANPAGER is used instead of the  standard  pagination
                 program,  less(1); see man(1) for details.  Only used
                 if -a or -l is specified.

       PAGER     Specifies the pagination program to use when MANPAGER
                 is not defined.  If neither PAGER nor MANPAGER is de‐
                 fined, less(1) is used.  Only used if  -a  or  -l  is
                 specified.

That's probably a glitch of not having a comprehensive list of options
and their description.

Going more into what concerns me, which is man3, I often miss an
ARGUMENTS (or PARAMETERS, to be more precise) section in the pages for
functions.  Sometimes it would be just one line per argument, but in
other cases it would help a lot have more organized information.  I'll
show you a few cases where I've used it, and where I think it made a
difference.

<https://github.com/shadow-maint/shadow/blob/master/lib/stpecpy.h>
<https://github.com/shadow-maint/shadow/blob/master/lib/stpeprintf.h>
<https://github.com/shadow-maint/shadow/blob/master/libmisc/agetpass.c>


 * SYNOPSIS
 *	char *_Nullable stpecpy(char *_Nullable dst, char end[0],
 *	                        const char *restrict src);
 *
 * ARGUMENTS
 *	dst	Destination buffer where to copy a string.
 *
 *	end	Pointer to one after the last element of the buffer
 *		pointed to by `dst`.  Usually, it should be calculated
 *		as `dst + NITEMS(dst)`.
 *
 *	src	Source string to be copied into dst.
 *
 * DESCRIPTION
 *	This function copies the string pointed to by src, into a string
 *	at the buffer pointed to by dst.  If the destination buffer,
 *	limited by a pointer to its end --one after its last element--,
 *	isn't large enough to hold the copy, the resulting string is
 *	truncated.
 *
 *	This function can be chained with calls to [v]stpeprintf().



 * SYNOPSIS
 *	[[gnu::format(printf, 3, 4)]]
 *	char *_Nullable stpeprintf(char *_Nullable dst, char end[0],
 *	                           const char *restrict fmt, ...);
 *
 *	[[gnu::format(printf, 3, 0)]]
 *	char *_Nullable vstpeprintf(char *_Nullable dst, char end[0],
 *	                           const char *restrict fmt, va_list ap);
 *
 *
 * ARGUMENTS
 *	dst	Destination buffer where to write a string.
 *
 *	end	Pointer to one after the last element of the buffer
 *		pointed to by `dst`.  Usually, it should be calculated
 *		as `dst + NITEMS(dst)`.
 *
 *	fmt	Format string
 *
 *	...
 *	ap	Variadic argument list
 *
 * DESCRIPTION
 *	These functions are very similar to [v]snprintf(3).
 *
 *	The destination buffer is limited by a pointer to its end --one
 *	after its last element-- instead of a size.  This allows
 *	chaining calls to it safely, unlike [v]snprintf(3), which is
 *	difficult to chain without invoking Undefined Behavior.



 * SYNOPSIS
 *	[[gnu::malloc(erase_pass)]]
 *	char *agetpass(const char *prompt);
 *
 *	void erase_pass(char *pass);
 *
 * ARGUMENTS
 *   agetpass()
 *	prompt	String to be printed before reading a password.
 *
 *   erase_pass()
 *	pass	password previously returned by agetpass().
 *
 * DESCRIPTION
 *   agetpass()
 *	This function is very similar to getpass(3).  It has several
 *	advantages compared to getpass(3):
 *
 *	- Instead of using a static buffer, agetpass() allocates memory
 *	  through malloc(3).  This makes the function thread-safe, and
 *	  also reduces the visibility of the buffer.
 *
 *	- agetpass() doesn't reallocate internally.  Some
 *	  implementations of getpass(3), such as glibc, do that, as a
 *	  consequence of calling getline(3).  That's a bug in glibc,
 *	  which allows leaking prefixes of passwords in freed memory.
 *
 *	- agetpass() doesn't overrun the output buffer.  If the input
 *	  password is too long, it simply fails.  Some implementations
 *	  of getpass(3), share the same bug that gets(3) has.
 *
 *	As soon as possible, the password obtained from agetpass() be
 *	erased by calling erase_pass(), to avoid possibly leaking the
 *	password.
 *
 *   erase_pass()
 *	This function first clears the password, by calling
 *	explicit_bzero(3) (or an equivalent call), and then frees the
 *	allocated memory by calling free(3).
 *
 *	NULL is a valid input pointer, and in such a case, this call is
 *	a no-op.


It's kind of a synopsis of the parameters.  Would it be better _after_
the description?  Maybe.  Is it better than having it all in the
description?  I think it is.  Will we see this in the Linux man-pages
some day?  Maybe.  What's your opinion?

>     Another reform to groff's man pages that I undertook was to begin
>     shifting more discursive material earlier in the page.  A popular
>     approach to man page organization for section 1 and 8 pages is to
>     have a single paragraph of overview followed immediately by the
>     "Options" section, which promptly starts referring to technical
>     details, sometimes obscure ones, that the reader must already
>     comprehend or which are not properly presented until later in the
>     document.  As you may suspect, I dislike that.  Ingo felt that if I
>     was going to have an Options section at all, I should keep it up
>     high so it would at least start on the first pager screen--I think
>     this was meant for the convenience of the expert reader.  But I
>     think this approach sacrifices too much accessibility to the
>     learner.  One should be able to read a man page linearly and feel
>     one's understanding of the topic building.  Some people would retort
>     that man pages are meant as a reference, not a tutorial.  My counter
>     is that while they generally aren't tutorials, terming one's page a
>     "reference" does not excuse one from covering the domain-specific
>     knowledge that another needs to acquire to competently use the
>     software at issue.

Yup, I think the man pages should serve as both (short) tutorials *and*
quick references.  If I need further info, I go to StackOverflow, but
I'd like to understand at least the basics of a function when reading
its page (and I've learnt many of the man3 functions by reading the
pages while maintaining them; for example, I didn't even know there was
a regex(3) function until I saw the page being mentioned in a ffix
patch by Michael; a few weeks later I needed it, and could use it by
just reading the manual; then I added the example program with
something close to what I did with it).

Something I do is first look at the synopsis, have a quick look at the
description searching for one line that describes each argument, and
then look at the example program to guess myself about the function.
Only after that is when I try to read the entire page to know the details.
But most of a function should be obvious already before reading the
description, or the design of the function would be dubious.

>  I think the boot(8) and crash(8) pages from the
>     V7 Unix manual (1979) are examples, from an esteemed source, of how
>     discursive--nigh-on tutorial--a man page of good reputation can get.
> 
>     My opinion is that the reader who is already familiar with the
>     page's material can type "/Options" in their pager to navigate there
>     if they are in a hurry.  Alternatively, thanks to Deri James, they
>     can view man pages as PDFs, open up the navigation pane of their PDF
>     viewer, and click on "Options".  A good conversion to HTML enables
>     this, too.

Which reminds me that when I move to 1.23.0 as a dependency, we should
have another look at Deri's script, and simplify it.

Cheers,

Alex

> 
> [2] http://harmful.cat-v.org/cat-v/

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

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

Re: [PATCH] man7/: ffix

[G. Branden Robinson]

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

Hi Alex,

At 2023-03-12T22:39:20+0100, Alejandro Colomar wrote:
> On 3/12/23 17:44, G. Branden Robinson wrote:
> > In groff 1.23.0 (which still doesn't have its final tag :( ), the
> > man(7) macro package remaps the `I` (italic) style to `BI`
> > (bold+italic) if it is available and the font being used for
> > (subsection) headings is configured to be bold.
> 
> Yup, I tested it only with 1.23.0-rc3.  I assume 1.22.4 will do
> something reasonable, but probably not so good.

groff 1.22.4 man(7) performs no font remapping in (sub)section headings,
so if you ask for font style `I` there, that is what you will get, at a
lighter stroke weight than the adjacent upright bold material.

Perhaps only typographers and nit-pickers will notice the difference...

> Heh, I remember having some problem related to this reading mandoc(1)
> (or maybe it was mdoc(7)).  I don't remember which it was, but having
> a quick look at mandoc(1), I found some flag insufficiently
> documented: '-l'.  See the only mentions in his page:
> 
>        MANPAGER  Any  non‐empty  value  of  the  environment  variable
>                  MANPAGER is used instead of the  standard  pagination
>                  program,  less(1); see man(1) for details.  Only used
>                  if -a or -l is specified.
> 
>        PAGER     Specifies the pagination program to use when MANPAGER
>                  is not defined.  If neither PAGER nor MANPAGER is de‐
>                  fined, less(1) is used.  Only used if  -a  or  -l  is
>                  specified.
> 
> That's probably a glitch of not having a comprehensive list of options
> and their description.

...or a glitch of not integrating discussion the `-l` option into the
narrative as Ingo suggested I do.  I further note that at least as of
mandoc 1.14.6 in Debian, `-l` is also not documented in its man page's
"Synopsis" section.

I can't hurl too many stones--there are groff man pages where I not only
do not practice what I preach, but where I haven't even gotten around to
recasting a former contributor's rambling asides and rather anguished
English.

> Going more into what concerns me, which is man3, I often miss an
> ARGUMENTS (or PARAMETERS, to be more precise) section in the pages for
> functions.  Sometimes it would be just one line per argument, but in
> other cases it would help a lot have more organized information.  I'll
> show you a few cases where I've used it, and where I think it made a
> difference.
> 
> <https://github.com/shadow-maint/shadow/blob/master/lib/stpecpy.h>
> <https://github.com/shadow-maint/shadow/blob/master/lib/stpeprintf.h>
> <https://github.com/shadow-maint/shadow/blob/master/libmisc/agetpass.c>

I don't have strong feelings about this.  A deeper principle I hold is
that functions shouldn't take a lot of arguments in the first place.  If
they do, it is a sign that

1. a data structure is called for, and a pointer to it should be passed;

and/or

2. the function is too complex, tries to do too much, and should be
   decomposed into orthogonal features.

The latter doesn't mean you can't also provide a convenience function to
handle common cases, or show the user how to implement one.  To recall
and old disagreement of ours, this is why I prefer memset() to bzero()
as a standard library function.  (Yes, memset() takes more arguments,
but it is also more _general_.  But I digress...)

On the TUHS list in the past year or so, someone posted, or shared a
link to, a reminiscence by a 1970s Bell Labs CSRC person that they
introduced the system call with the longest signature seen in Unix to
date (I think it was mmap(2)).  They expressed nervousness about it,
fearing cries of inelegance from their peers--perhaps even the figure
of Ken Thompson himself darkening the office doorway.

But it went in anyway, apparently, on the strength of the functionality.
Maybe the prospect of fighting Multics on its own ground was too
appealing to pass up.

> It's kind of a synopsis of the parameters.  Would it be better _after_
> the description?  Maybe.

Maybe not.  _If_ you're going to have an "Arguments" heading for
section 2 or 3 man page, placing it between "Synopsis" and "Description"
seems appropriate.

> Is it better than having it all in the description?  I think it is.
> Will we see this in the Linux man-pages some day?  Maybe.  What's your
> opinion?

I think you should collect more opinions.  Also consider going back to
the Unix Programmer's Manuals of the 1970s and see how they tackled the
issue.  The complications of history are not going to make _every_
simplification impossible.  And you may well find places where these
manuals were ill-written or the API badly designed.  (Inter-process
communication was not born elegant in Unix and still isn't to this day.)

> Yup, I think the man pages should serve as both (short) tutorials
> *and* quick references.  If I need further info, I go to
> StackOverflow, but I'd like to understand at least the basics of a
> function when reading its page (and I've learnt many of the man3
> functions by reading the pages while maintaining them; for example, I
> didn't even know there was a regex(3) function until I saw the page
> being mentioned in a ffix patch by Michael; a few weeks later I needed
> it, and could use it by just reading the manual; then I added the
> example program with something close to what I did with it).

I learned years ago that the only way I can truly learn anything that
isn't simple is to start rewriting its documentation, which usually
means conducting a lot of experiments.  In the 6 years or so I've been
contributing to groff I've amassed a set of 1,433 files in my
"EXPERIMENTS" subdirectory.  I've also thrown many experiments away.

Other people may have an easier time forming accurate models of
programming systems in their heads, but for me the right approach
appears to be radical skepticism combined with a record of findings
(i.e., expanding or correcting the documentation where appropriate).

> Something I do is first look at the synopsis, have a quick look at the
> description searching for one line that describes each argument, and
> then look at the example program to guess myself about the function.
> Only after that is when I try to read the entire page to know the
> details.  But most of a function should be obvious already before
> reading the description, or the design of the function would be
> dubious.

I broadly agree.  This is one reason naming things well is important.

> Which reminds me that when I move to 1.23.0 as a dependency, we should
> have another look at Deri's script, and simplify it.

I feel a powerful urge to simplify his "an:cln" macro to near
triviality by filling a feature gap in the formatter.

https://savannah.gnu.org/bugs/?62264

Assuming groff internals work the way my mental model says they do, and
the test of that will come with more experiments...

Regards,
Branden

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

Re: [PATCH] man7/: ffix

[Alejandro Colomar]

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

Hey Branden!

On 3/23/23 23:29, G. Branden Robinson wrote:
> 
>> Going more into what concerns me, which is man3, I often miss an
>> ARGUMENTS (or PARAMETERS, to be more precise) section in the pages for
>> functions.  Sometimes it would be just one line per argument, but in
>> other cases it would help a lot have more organized information.  I'll
>> show you a few cases where I've used it, and where I think it made a
>> difference.
>>
>> <https://github.com/shadow-maint/shadow/blob/master/lib/stpecpy.h>
>> <https://github.com/shadow-maint/shadow/blob/master/lib/stpeprintf.h>
>> <https://github.com/shadow-maint/shadow/blob/master/libmisc/agetpass.c>
> 
> I don't have strong feelings about this.  A deeper principle I hold is
> that functions shouldn't take a lot of arguments in the first place.  If
> they do, it is a sign that
> 
> 1. a data structure is called for, and a pointer to it should be passed;
> 
> and/or
> 
> 2. the function is too complex, tries to do too much, and should be
>    decomposed into orthogonal features.
> 
> The latter doesn't mean you can't also provide a convenience function to
> handle common cases, or show the user how to implement one.  To recall
> and old disagreement of ours, this is why I prefer memset() to bzero()
> as a standard library function.  (Yes, memset() takes more arguments,
> but it is also more _general_.  But I digress...)

While it is more general, I yet haven't been shown a list of uses for it.
I recall 1 use in my entire life (not too long, I know).  It was for
initializing an array of bitfields to all-bits-1.  I would expect that a
function that allows doing that would be something obscure that is rarely
used.

While bzero(3) and memset(3) are similar in the implementation,
they are rather different in the abstract semantics: one zeroes a buffer.
The other allows two uses (that I know): initializing to 1s, in the rare
case where you want all 1s; and initializing memory to some magic
pattern to be able to detect uses of invalid memory.

It would be nice if grepping for memset() would show these rare cases
only, rather than being needles in a huge haystack of zeroing.  A regex
might help, but still...

I would even go further and say that libc doesn't need memset(3).  It's
such a niche function, that we don't really need it in the most
essential library.  I mean, we still don't have strlcpy(3) in some libc
implementations, and it's quite useful.  Why don't we ask users to
implement their own loop for the rare case they want to initialize their
buffers to 0xF0?  Why not a memset32(3) to initialize arrays of
uint32_t?  What's so special about non-zero byte initialization?  If you
need memset(3) to be optimized, you can write libmemset and write it in
assembly...  Can anyone justify the existence of memset(3) in libc?
Apart from the obvious "because we already had it, so why remove it" or
"because ISO C says so".  If we had none of them in libc, and were
presented both bzero(3) and memset(3), I'd go for bzero(3) 10 out of 10
times, as it's essential, and would ask the interested in memset(3) to
write their own niche library.

> But it went in anyway, apparently, on the strength of the functionality.
> Maybe the prospect of fighting Multics on its own ground was too
> appealing to pass up.
> 
>> It's kind of a synopsis of the parameters.  Would it be better _after_
>> the description?  Maybe.
> 
> Maybe not.  _If_ you're going to have an "Arguments" heading for
> section 2 or 3 man page, placing it between "Synopsis" and "Description"
> seems appropriate.

Yep.

> 
>> Is it better than having it all in the description?  I think it is.
>> Will we see this in the Linux man-pages some day?  Maybe.  What's your
>> opinion?
> 
> I think you should collect more opinions.

Yeah, I don't have any plans for that now.  While I use that section
in other projects where I write man pages or man-page-like documentation
from scratch, here that we don't use it, it would be more work than I'm
willing to do for now.  Maybe in something like several years, I could
consider that, if other people want it.

>  Also consider going back to
> the Unix Programmer's Manuals of the 1970s and see how they tackled the
> issue.  The complications of history are not going to make _every_
> simplification impossible.  And you may well find places where these
> manuals were ill-written or the API badly designed.  (Inter-process
> communication was not born elegant in Unix and still isn't to this day.)
> 
>> Yup, I think the man pages should serve as both (short) tutorials
>> *and* quick references.  If I need further info, I go to
>> StackOverflow, but I'd like to understand at least the basics of a
>> function when reading its page (and I've learnt many of the man3
>> functions by reading the pages while maintaining them; for example, I
>> didn't even know there was a regex(3) function until I saw the page
>> being mentioned in a ffix patch by Michael; a few weeks later I needed
>> it, and could use it by just reading the manual; then I added the
>> example program with something close to what I did with it).
> 
> I learned years ago that the only way I can truly learn anything that
> isn't simple is to start rewriting its documentation, which usually
> means conducting a lot of experiments.  In the 6 years or so I've been
> contributing to groff I've amassed a set of 1,433 files in my
> "EXPERIMENTS" subdirectory.  I've also thrown many experiments away.

Heh, me too :).  Probably one of the most run commands in my terminals
is `cd ~/tmp`.  However, I discard them always (keep them maybe for a
week, until it grows too much and `rm -rf *` does its job); organizing
that mess of 10-liner programs is too much for me :p.

> 
> Other people may have an easier time forming accurate models of
> programming systems in their heads, but for me the right approach
> appears to be radical skepticism combined with a record of findings
> (i.e., expanding or correcting the documentation where appropriate).

Well, once I write the test, it at least gets into my brain so I can
discard it.  Cache misses of that kind don't seem a big issue in my
head, it seems.  I have good video memory.  :-)

> 
>> Something I do is first look at the synopsis, have a quick look at the
>> description searching for one line that describes each argument, and
>> then look at the example program to guess myself about the function.
>> Only after that is when I try to read the entire page to know the
>> details.  But most of a function should be obvious already before
>> reading the description, or the design of the function would be
>> dubious.
> 
> I broadly agree.  This is one reason naming things well is important.

Guess what's been the discussion of the day?  Why do we find bool more
readable than uint8_t (with a comment saying /* 1 bit */) for boolean
variables, and true/false vs 1/0.  lol.

Cheers,
Alex

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

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