Hello Ingo, thank you for your detailed response.
On Sun Feb 9, 2025 at 7:38 PM CET, Ingo Schwarze wrote: > onf wrote on Sat, Feb 08, 2025 at 01:35:31AM +0100: > [...] > > 1. Escape sequences in the sense of inline commands, i.e. how to mark > > up syntax like \f[font]? Does it fit under Cm? > > The roff(7) language is a language using rather unusual syntax, > compared to other languages. That makes applying good mdoc(7) style > to it relatively difficult; certainly more difficult than using mdoc(7) > for example for C or sh code. troff's \f escape sequence was just the one I was most interested in, but the same question could apply e.g. to C's \x escape. > That said, i don't like using .Cm for \f[font] because that's for fixed > strings that serve as arguments for commands or directives, and i see no > command or directive here that this could be an argument of. For the "\f" > itself, the .Ic macro seems more appropriate because it serves the > function of a stand-alone command. [...] Agreed, that was a mistake on my part; I meant to say Ic. > So, consider this a good example - it's slightly modified text > pilfered from the roff(7) manual page in the mandoc package: > > The > .Ic \ef Ns Bq Ar font > escape sequence switches to the specified > .Ar font. > [...] It seems we ended up agreeing on this, after all :) $ grep -FA2 '\ef' man/neatroff.7 [...] -- .It Ic \ef Ns Bq Ar font See .Ic ft . > Even for this appendix, marking up roff(7) syntax is arguably a somewhat > niche topic. [...] As noted above, although my primary interest lies in markup for roff escapes (that's what I'm writing about), the question was aimed at escapes in general. > > 2. stdin, stdout, stderr without the /dev/; do those fit under Pa? > > Practice among mdoc documents seems inconsistent.[1] > > If you are talking about the FILE pointers declared in <stdio.h>, > no, absolutely not .Pa. [...] > > The constant symbols stdin, stdout, and stderr seem exessively > specific to explicitly mention them in the appendix, so i'm not > sure what to do about that. > > [...] > > If you want to talk about the general concepts (and not about any > specific syntax element), use the plain English words "standard > input", "standard output", and "standard error output" rather than > the cryptic abbreviations stdin, stdout, and stderr. I was talking about them in the sense of "write message to stderr". I will switch to "write message to standard error" as suggested at the end. Although stdin/stdout/stderr are indeed quite specific, they are used frequently, especially in the meaning I had mind. > > 3. Displaying " as a literal character. Sq is suggested for displaying > > single characters, but it seems to be a poor match for ". I am > > currently using Sy. > > The > .Xr ascii 7 > double quote character > .Pq Sq \&" > > does not look that bad to me and is certainly rigorous. It does not look so bad within those parentheses, but it looks pretty bad without them, in my opinion. > Then again, if you want to use > > .Pq Sy \&" > > for that specific case, i wouldn't get upset about that, either. > Does that need mentioning in the appendix? Not so sure, that > sounds excessively specific, too. Conceded. > [...] > > [1] Querying mdoc manuals installed on my machine: > > bsdtar(1): stdout without markup > > That wouldn't be ideal, but the tar(1) manual in OpenBSD does not > contain the string "std" at all, so i cannot fix anything there. > [...] > > bsdunzip(1): Va stderr, stdout without markup > > That's the third-party project https://www.libarchive.org/ . > Some BSD developers appear to be involved, more from FreeBSD > than OpenBSD, so reporting should go upstream. > [...] I would like to clarify that it wasn't my intention to report those uses as bugs. I merely included that listing to support my claim that markup for stdin/stderr/stdout seems inconsistent in existing mdoc manuals. I admit I didn't think too much about the fact that those identifiers can have several meanings. The bsdtar installed on my machine is in fact from libarchive as well, so it indeed isn't OpenBSD-specific. ~ onf
