man7/: ffix

---

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(-)

index 708099934..8c31b5f95 100644
@@ -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

index 6647b02bf..737dd54ad 100644
@@ -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

Hi Alex,

Short answer: take the patch. :)

[...]

[...]

[...]

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/

Hi Branden,

I pushed it earlier today. :)

[...]

[...]

Good.

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

[...]

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

[...]

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?

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.

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

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

Hi Alex,

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...

...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.

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.

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.

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.)

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).

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

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

Hey Branden!

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.

Yep.

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.

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.

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. :-)

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