In the Linux man-pages project we completely avoid both \fC and \f[CR]. We use either italics or bold.

Rationale: most of the time, the manual page is read in the terminal, where everything is monospaced, so marking some identifier as Courier (monospaced) doesn't help the reader at all. It helps on the PDF, but few people read manual pages as PDF these days.

@flatcap do you have any opinions on whether to keep the CR or change to something else? Maybe bold and italic? What do you use on kernel's documentation in this case @alejandro-colomar?

I have no strong opinions on this one and used CR to keep the same behaviour as before but in a compatible way (both troff and groff support it). After all, I think this predates neomutt by a lot (6cd98f2) so I think it was mainly not touched for a while and just existed on the codebase.

most of the time, the manual page is read in the terminal, where everything is monospaced

Oh yeah :-)

do you have any opinions on whether to keep the CR or change to something else?

I think bold would be a reasonable choice for highlighting keywords, functions, etc.
(but I don't feel too strongly about it).

there are actually rules for that: https://man7.org/linux/man-pages/man7/groff_man_style.7.html, section "Font style macros"

Indeed, we have style rules for this in groff_man_style(7). Here's the rules that @ossilator mentions:

       .B [text]
              Set text in bold.  If no argument is given, a one‐line input trap
              is planted; text on the next line, which can be further formatted
              with a macro, is set in bold.

              Use  bold  for  literal portions of syntax synopses, for command‐
              line options in running text, and for  literals  that  are  major
              topics  of  the  subject under discussion; for example, this page
              uses bold for macro, string, and register names.  In  an  .EX/.EE
              example  of  interactive  I/O (such as a shell session), set only
              user input in bold.

       .I [text]
              Set text in an italic or oblique face.  If no argument is  given,
              a  one‐line  input  trap is planted; text on the next line, which
              can be further formatted with a macro, is set  in  an  italic  or
              oblique face.

              Use  italics  for file and path names, for environment variables,
              for C data types, for enumeration or preprocessor constants in C,
              for variant (user‐replaceable) portions of syntax  synopses,  for
              the  first  occurrence (only) of a technical concept being intro‐
              duced, for names of journals and of literary works longer than an
              article, and anywhere a parameter requiring  replacement  by  the
              user  is  encountered.   An  exception involves variant text in a
              context already typeset in italics, such as file  or  path  names
              with replaceable components; in such cases, follow the convention
              of  mathematical typography: set the file or path name in italics
              as usual but use roman for the variant part (see .IR and .RI  be‐
              low),  and  italics again in running roman text when referring to
              the variant material.

A rough TL;DR would be: function and variable names and placeholders in italics, and literals in bold. Inline examples of commands, expressions, etc., in italics. Use of bold should be minimal (think of it like uppercase; abusing it is considered rude).

Heh! Have a lovely new year! If your thesis allows... :-)

Inline examples of commands, expressions, etc., in italics.

I don't think that's part of the advice in groff_man_style(7).

     Use italics for emphasis rarely, and bold almost never.  Brief
     specimens of literal text, such as article titles, mentions of
     individual characters or short strings, and (sub)section headings
     in man pages, are suitable objects for quotation; see the \(lq,
     \(rq, \(oq, and \(cq escape sequences in subsection “Portability”
     below.

Inline examples of commands, expressions, etc., in italics.

I don't think that's part of the advice in groff_man_style(7).

     Use italics for emphasis rarely, and bold almost never.  Brief
     specimens of literal text, such as article titles, mentions of
     individual characters or short strings, and (sub)section headings
     in man pages, are suitable objects for quotation; see the \(lq,
     \(rq, \(oq, and \(cq escape sequences in subsection “Portability”
     below.

Sorry, that part is from man-pages(7).

OK, italics it is.

@flatcap I've been looking at this right now and realized a small problem. We generate all html documentation from these using docs/makedoc.c. If we change \fC to \fI, \fB or else, we are loosing the code blocks on html. I think you generate the website documentation the same way right? Like the reference, all code blocks would become italics or bold.

So I'm a bit in doubt about loosing the code blocks on html in order to make the manpages compliant to groff_man_style(7). Using \fCR would keep things as is.

Right now I see the two options above, maybe you guys can give a better and different one.

Uhm... I have an idea starting to form on my head - to be continued tomorrow

(apparently all I needed was to stop typing and go to shower)

Since "alpha" is a literal, I'd make it bold.

This is a literal, so I'd use bold, I think. It's not a clear case, I think, though.

As a bit of off-topic English style advice...

1. The Latin abbreviation "i.e." should be followed by a comma, since id est roughly means "that is".
2. The Latin abbreviation remains subject to the capitalization rules of English sentences, thus "I.e.,".
3. I would avoid the use of Latin abbreviations except in a conventional scholarly context anyway. In man pages I favor English words over Latin abbreviations. This also avoids the common embarrassment of using "cf." incorrectly to mean "see", when it abbreviates Latin confere, which roughly means "compare" (or, more precisely, "contrast"; it is used to draw the reader's attention to a distinction or difference).

For command-line flags, you should use bold.

cmd flag bold

@g-branden-robinson What would you use here? Bold, italics, or roman? I don't know.

Holy blap, I've been blitzed.

Uh, okay, I'll work through these callouts one by one.

That, I would quote. We really need to stop fearing quotation in our man(7) documents.

** Controls the decoding of complex MIME messages into \[lq]text/plain\[rq] when

Holy blap, I've been blitzed.

:-)

Uh, okay, I'll work through these callouts one by one.

That, I would quote. We really need to stop fearing quotation in our man(7) documents.

** Controls the decoding of complex MIME messages into \[lq]text/plain\[rq] when

Hmmm, true. I now think I have seen some of those in the Linux man-pages project.

However, since this string is usually quoted in code, I might use vertical quotes, as if it was a string. What do you think?

Thanks!

I'd only use neutral quotes if they were a necessary part of the example. I would not use them to perform quotation itself in the man page itself.

YES: Consider the declaration \[lq]const char foo[] = "bar";\[rq] next.
NO: We wanted "bar" to be null-terminated.

I'd only use neutral quotes if they were a necessary part of the example. I would not use them to perform quotation itself in the man page itself.

YES: Consider the declaration \[lq]const char foo[] = "bar";\[rq] next. NO: We wanted "foobar" to be null-terminated.

Hmmm, I disagree here. "foobar" is a C string, and I think that writing it as it would be written in a C program, with vertical quotes, aids readability.

In my opinion, you are then implying the C string literal \"foobar\" (as I would spell it in source code; the object in memory of course has no backslashes).

My view is that C syntax and English syntax differ greatly and should not be intermixed.

Moreover, in man pages we often have occasion to discuss programming or configuration language syntaxes that are not C. Aggressively using C-correct utterances in those contexts can cause confusion, or outright error on the part of the user.

i'm not sure what you're arguing here at this point. :}

i'd write:

Consider the declaration \[lq]const char foo[] = \[dq]bar\[dq];\[rq] next.
We wanted \[lq]bar\[rq] to be null-terminated.

it is my understanding that literal quotes should never be used, as their rendering varies in undesirable ways.

quotes aside, inlining a whole line of c code is a bad idea; i'd write it like that instead:

.RS 8
.nf
const char foo[] = \[dq]bar\[dq];
.fi
.RE
.IP

i'm not sure what you're arguing here at this point. :}

i'd write:

Consider the declaration [lq]const char foo[] = [dq]bar[dq];[rq] next.
We wanted [lq]bar[rq] to be null-terminated.

it is my understanding that literal quotes should never be used,
as their rendering varies in undesirable ways.

"Never" is, technically, too strong, but pretty close. There are two different problems.

• " is interpreted as delimiting a macro argument, but only when used in a macro call. It's "safe" on text lines, but if someone inattentively grabs a phrase from a text line and stuffs it into a macro call, they likely will not get the formatted output they expect. Unfortunately, \[dq] (or even \(dq) isn't perfectly portable; see below.

• Single quotes have gotten progressively more problematic.

• • The grave accent (I can't get this Markdown to format it inline correctly) and apostrophe/neutral single quote ' traditionally were perfectly reliable ways of getting directional single quotes, if they existed at all on the output device. When the Bell Labs CSRC developed nroff and troff, these characters looked on their Teletype Corporation Model 37s much as depicted in ANSI X3.4-1977.
• • In the 1980s, ISO 8859 disambiguated the apostrophe from the acute accent, rendering the former neutral (vertical) in orientation, which also removed it from consideration as a candidate directional single quotation mark.
• • Starting about 15 years ago, it became fashionable to have one's groff man package remap the grave accent and apostrophe to "themselves". That created a problem.

As a forthcoming commit of mine to groff_man_style(7) puts it:

       Historically, man pages used ` and ' exclusively for directional
       single quotation marks.  However, in recent years, some
       distributors of groff have chosen to override the meanings of
       these characters in man pages, remapping them to their Unicode
       Basic Latin code points.  Unfortunately, ` and ' are the only
       reliable means of obtaining directional single quotation marks in
       AT&T troff; in that implementation, often no special character
       escape sequences exist to obtain them.  Further, in AT&T troff,
       the glyph repertoire, like the set of supported font names, is
       device‐specific.  To achieve quotation portably in man pages
       rendered both by AT&T and more modern troffs, consider adding a
       preamble to your page after the .TH call as follows.

              .ie \n(.g \{\
              .  ds oq \(oq
              .  ds cq \(cq
              .\}
              .el \{\
              .  ds oq `
              .  ds cq '
              .\}

       You must then use the \* escape sequence to interpolate the
       quotation mark strings.

              The command
              .RB \*(oq "while ! git pull; do sleep 10; done" \*(cq
              retries an update from our repository until it succeeds.

       If this procedure seems complex, petition your distributor to
       revert their remapping of the ` and ' characters.

Since old troffs don't reliably support all of the special character escape sequences for obtaining quotation marks that groff supports, if you need portability to those formatters, you can't say "never".

quotes aside, inlining a whole line of c code is a bad idea; i'd write it like that instead:

.RS 8
.nf
const char foo[] = [dq]bar[dq];
.fi
.RE
.IP

I won't argue with your suggestion to display such an example instead of inlining it. But I would:

1. ...not supply arguments to the RS request unless necessary. The relative inset amount is configurable at formatting time via the IN register, and the user's selection should be respected. Where necessary, multiple RS insets can be nested.
2. ...use EX and EE inboard of the nf and fi requests if you need portability to formatters that don't support EX and EE, and instead of the requests if you don't. This gets you a monospaced font family (Courier) on typesetters, which in turn makes ASCII art possible on those devices. Traditional troffs silently ignore calls of macro names they don't recognize, groff supports them, and so does mandoc since its 1.12.2 release over 10 years ago.

In my opinion, you are then implying the C string literal \"foobar\" (as I would spell it in source code; the object in memory of course has no backslashes).

My view is that C syntax and English syntax differ greatly and should not be intermixed.

Moreover, in man pages we often have occasion to discuss programming or configuration language syntaxes that are not C. Aggressively using C-correct utterances in those contexts can cause confusion, or outright error on the part of the user.

Hmmmm, maybe it depends on the context. I don't fully agree, but don't strongly disagree either.

I would consider this a literal, so bold, I think. Also, since the config should include the quotes, I'd also make them bold.

cmd flag bold

Similar question, @g-branden-robinson.

Quotation marks again.

These are literals, and should be bold, I think.

@g-branden-robinson

Quotation marks again.

gbr

Quotation marks again.

This is an interesting one.

The [] should be roman, since they are not variable. They convey meanining by saying that the enclosed text is optional.

Also, some parts are literal (:, @), and they should be bold. This is one of the most complex cases you'll find in a man(7) document, and involves 3 fonts in a single input line.

So, I'd use

.RB [[ s ] news:// ][ \fIusername\fP [ :\fIpassword\fP ] @ ] \fIserver\fP [ :\fIport\fP ]

using man(7) macros (plus some escapes where necessary). Or the following equivalent fully with escapes:

[[\fBs\fP]\fBnews://\fP][\fIusername\fP[\fB:\fP\fIpassword\fP]\fB@\fP]\fIserver\fP[\fB:\fP\fIport\fP]

Strictly speaking, it's not necessary to select the previous font with \fP immediately prior to changing it again, as with \fP\fI. But it can make a lengthy run of font-dancing easier to follow. There's a tradeoff between length and comprehensibility, in the sense of how much state you have to track in your brain.

This is also a situation where \c can ride to your rescue.

.RB [[ s ] news:// ]\c
.RI [ username\c
.RB [ :\c
.IR password ]\c
.BR @ ]\c
.IR server [\c
.BI : port\c
]

Strictly speaking, it's not necessary to select the previous font with \fP immediately prior to changing it again, as with \fP\fI. But it can make a lengthy run of font-dancing easier to follow. There's a tradeoff between length and comprehensibility, in the sense of how much state you have to track in your brain.

I'm never sure if \fI\fB\fP returns to the I or to the font prior to it, which is why I prefer keeping a stack of 1. That way I'm sure of the behavior.

And if someone said \fC, the identity of the previous font may be implementation-dependent. 😮

gbr

Quotation marks again.

This is a command line option, and should be bold.

BTW, it is missing the leading --.

on a related note, all literal dashes need to be \-escaped.

@ossilator: Agreed. That argues for bold or quotation marks, in my view.

I wasn't going to mention them for now, to not confuse too much. :)
But yeah, we need to fix the - afterwards.

Leading -- is missing.

As a cmd flag, this should be bold.

gbr

Quotation marks again.

gbr

Quotation marks again.

@g-branden-robinson what do you think of this one? I would make it bold, but I'm not entirely sure.

I certainly wouldn't use straight double quotes unless those are part of the literal.

I'd probably use both quotation marks and bold.

If this variable is
.IR set , \" is emphasis necessary here?
NeoMutt will try to use the
.RB \[lq] LAST \[rq]
POP command

Why lq and rq? I think bold should be enough, no?

I often add quotes (in roman) when a boldfaced literal comprises multiple words, so that when copying and pasting man page content, the boundaries of the literal are still visible. But yes, that's not necessary here. I don't think it's wrong in this scenario to omit or retain the quotation marks; that's more a question of style for the page author (or project style guide).

Hmmm, I haven't checked the others. The (1) (or (N)) part should be roman. The \fI\fP should enclose only the name of the page, and not the parenthesized number. Please check all such occurences.

well, actually, these should use the .MR macro.

That's still not portable enough for neomutt(1).

@alejandro-colomar : Hey, don't wave him off! If neomutt wants to help usher in the MR revolution, I'm all for it! 😀

But a frank word about its portability is in order.

mandoc(1) added support for MR in its CVS over a year ago but has not done a release in 3 years. I'd expect Heirloom Doctools to update their copy of our extensions at some point, but at present its pace of development is pretty slow.

Hmmm, it seems there's a mix of style. This one is good.

@g-branden-robinson Any opinion on these?