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:
OpenPGP_signature
Description: OpenPGP digital signature
