man(7) <-> mdoc(7) (approximate) correspondence table?

[ Not subscribed to the linux-man list, so please cc me if replying there. ]

Hi all,

As someone who's much more familiar with mdoc(7) than man(7), is there an approximate 'correspondence table' somewhere that gives at least a rough sense of which man(7) macros to use when, in an mdoc(7) context, one would use a given mdoc(7) macro? Such a table might look something like (to use some obvious probable correspondences):

| mdoc(7) | man(7) | Notes
+---------+--------+-------
| Lk      | UR     |
| Op      | OP     |
| Sh      | SH     |
| Ss      | SS     |
| ⋮       | ⋮      | 

i recognise that there's no bijection in general, and that specific mappings might differ between projects (e.g. the Linux man-pages project might use a certain man(7) macro where a different project uses another), but even a project-specific table would be helpful to me.

i thought there might be such a table in either groff_man(7) or groff_man_style(7), but nothing leapt out ....

Alexis.

Hi Alexis,

I have similar problems when writing mdoc(7). What I tend to do is look at good (e.g., OpenBSD) mdoc(7) pages' output, and then look at their source to see what they use.

I can only recommend you look at pages in the Linux man-pages project, and follow what you see (you can ask me if a page is a good reference). I try to have them all with perfect source, but there are too many of them.

It would be interesting if there would exist such a thing.

Have a lovely weekend!
Alex

<https://www.alejandro-colomar.es/>

Hi Alejandro,

Thanks for your reply! Responses inline.

i'm actually not currently writing (or needing to write) a man(7) page. It's just that i'd be more inclined to potentially help with Linux-oriented man pages (and the man-pages project in particular) if there was such a table, to allow me to potentially do small/quick corrections, additions, etc. - i run two OpenBSD servers, but my daily driver is Gentoo.

i already have a lot of volunteer FOSS stuff on my plate, and i have to regularly make an active effort to not take on more / overcommit, so anything that can smooth the path for me to make quick changes as i notice them is appreciated.

Yes, off the top of my head, it seems like a number of people might find it useful ....

Alexis.

'\" t
.
.\" SPDX-FileCopyrightText: 2024 Lennart Jablonka <[email protected]> .\" SPDX-LicenseIdentifier: BlueOak-1.0.0
.\" https://blueoakcouncil.org/license/1.0.0
.
.Dd April 27, 2024
.Dt MDOC-MAN-CMP 7
.Os
.Sh NAME
.Nm mdoc-man-cmp
.Nd a little comparison of \-mdoc and \-man macros
.Sh DESCRIPTION
This table shows a non-injective map of \-mdoc macros to \-man macros and conventions.
It does contain opinions of mine, not explicitly marked as such. .Pp
.\" note: mandoc's mdoc(7) uses Ic for troff macro names; I don't, .\" following what 4.4BSD's mdoc(7) does
.TS
center;
lb lb
_ _
l l.
\-mdoc \-man
T{
.Li \&Dd ,
.Li \&Dt ,
.Li \&Os
T} T{
.Li TH
T}
T{
.Li \&Nm
T} T{
in the
.Sq NAME
section, roman, as-is;
in the synopsis,
.Li \&B ;
elsewhere,
per preference roman or
.Li \&I
(but some people make it bold)
T}
T{
.Li \&Nd
T} T{
the whole
.Sq NAME
section should be of the form
.D1 Ar name Ns [, Ar name No .\|.\|.] Li \e\- Ar description T}
T{
.Li \&Sh
T} T{
.Li \&SH
T}
T{
.Li \&Ss
T} T{
.Li \&SS
T}
T{
.Li \&Xr
T} T{
if targetting Groff\~1.23.0 or newer,
.Li \&MR ;
otherwise, make the title italic and the parenthesized chapter roman; e.g., do
.Dl ".IR man (7)"
T}
T{
.Li \&Tg
T} T{
There is no replacement as of now, but I hear Branden\~G.\~Robinson plans to introduce something of that sort to Groff's \-man.
You might want to take a look at the
.Li \&IX
macro emitted by Perl's
.Xr pod2man 1 .
T}
T{
.Li \&Pp
T} T{
The perfectly fine macro for this is
.Li \&PP .
There are also the synonymous
.Li \&LP ,
as well as the synonymous extension
.Li \&P .
Some people like those better.
T}
T{
.Li \&Bd ,
.Li \&Ed ,
.Li \&D1 ,
.Li \&Dl
T} T{
There is
.Li \&RS Ns / Ns Li \&RE
for indenting and the extension
.Li \&EX Ns / Ns Li \&EE
for non-filled fixed-width type.
Further, you can use troff requests such as, for example, .Li \&nf Ns / Ns Li \&fi
to control the finer details.
T}
T{
.Li \&Ql
T} T{
Plan\~9's \-man has
.Li \&L ,
which uses single quotes for
.Nm nroff
and the
.Dq literal
(fixed-width) font for
.Nm troff .
Other \-mans don't have an equivalent.
Other \-mans also don't have a standardized way of using a fixed-width font beside
.Li \&EX .
Use bold type, roman type enclosed in quotes, or simply use roman type.
T}
T{
.Li \&Bl ,
.Li \&El ,
.Li \&It ,
.Li \&Ta
T} T{
a combination of
.Li \&IP ,
.Li \&TP ,
.Li \&TQ ,
.Li \&HP ,
.Li \&PD ,
.Nm troff Ap s
tab mechanism,
and
.Xr tbl 1
T}
T{
.Li \&Rs ,
.Li \&%* ,
.Li \&Re
T} T{
Sadly, \-man isn't integrated with
.Xr refer 1 .
Simply write the whole reference manually using font-changing macros.
T}
T{
.Li \&Pf ,
.Li \&Ns ,
.Li \&Sm
T} T{
no replacement needed
T}
T{
.Li \&Bk ,
.Li \&Ek
T} T{
A common extension is the adjustable non-breakable space, .Li \e\(ti .
Traditionally, you'd use a non-adjustable non-breakable space, either by prefixing a space with the escape character, or by translating a different character to the space character using .Li \&tr .
If using the latter option, do take care to remove the character translation before the end of the man page, lest it cause unexpected behavior in following man pages when running them off concatenated.
T}
T{
.Li \&Fl
T} T{
.\" TODO: Did V9 switch to -o and \fL already?
On a 10th Edition Unix or Plan\~9 system, simply write the option
.Fl o
as
.Ql \-o
in the literal font
.Pf ( Li .B ) .
Otherwise, instead of using a hyphen, use a
.Do minus sign Dc Ns / Ns Do Unix dash Dc
in the bold font:
.Dl ".B \e\-o"
T}
T{
.Li \&Cm
T} T{
.Li \&B
T}
T{
.Li \&Ar
T} T{
.Li \&I
T}
T{
.Li \&Op ,
.Li \&Oo ,
.Li \&Oc
T} T{
[ ]
T}
T{
.Li \&Ic
T} T{
.Li \&B
T}
T{
.Li \&Pa
T} T{
just roman or perhaps italic
T}
T{
.Li \&Lb ,
.Li \&In ,
.Li \&Fd ,
.Li \&Ft ,
.Li \&Fo ,
.Li \&Fc ,
.Li \&Fn ,
.Li \&Fa ,
.Li \&Vt ,
.Li \&Va ,
.Li \&Dv ,
.Li \&Er ,
.Li \&Ev
.Li \&Cd ,
.Li \&Ad ,
T} T{
perhaps italic, perhaps roman, perhaps bold, perhaps small .Pf ( Li SM ) ,
perhaps a combination
T}
T{
.Li \&An
T} T{
roman
T}
T{
.Li \&Lk
T} T{
the
.Li \&UR Ns / Ns Li \&UE
extension
T}
T{
.Li \&Mt
T} T{
the
.Li \&MT Ns / Ns Li \&ME
extension
T}
T{
.Li \&Ms
T} T{
If you want to typeset math, use
.Xr eqn 1 .
If you want to write the name of a mathematical symbol, write the name.
T}
T{
.Li \&Em ,
.Li \&Sy
T} T{
To emphasize something or to use get italic type for some other reason, use
.Li \&I .
To use boldface, use
.Li \&B .
I'm not sure what exactly the \-mdoc manuals mean by .Dq "symbolic (traditional English)" .
T}
T{
.Li \&No
T} T{
no replacement needed
T}
T{
.Li \&Bf ,
.Li \&Ef
T} T{
.Li \&ft
T}
T{
.Li \&Dq ,
.Li \&Do ,
.Li \&Dc
T} T{
For double quotes, the traditional
.Nm troff
usage is
.Dl \(ga\(ga \(aq\(aq
and the modern Groff
usage is
.Dl \e(lq \e(rq Ns .
Groff (1.23.0) misrenders
.Li \(ga\(ga \(aq\(aq Ns \(emor
rather, improves upon the traditional rendering of
.Li \(ga\(ga \(aq\(aq
by adding
.Li \e(lq \e(rq
and not improving the looks of
.Li \(ga\(ga \(aq\(aq
itself as well.
T}
T{
.Li \&Qq ,
.Li \&Qo ,
.Li \&Qc
T} T{
Simply use the ASCII double-quote\~\c
.Li \&\(dq .
Quote and double it when passing it to a macro:
.Dl ".B """""""""
T}
T{
.Li \&Ap ,
.Li \&Sq ,
.Li \&So ,
.Li \&Sc
T} T{
.Li \(ga \(aq
T}
T{
.Li \&Pq ,
.Li \&Po ,
.Li \&Pc ,
.Li \&Bq ,
.Li \&Bo ,
.Li \&Bc ,
.Li \&Brq ,
.Li \&Bro ,
.Li \&Brc ,
.Li \&Aq ,
.Li \&Ao ,
.Li \&Ac ,
.Li \&Eo ,
.Li \&Ec
T} T{
Simply write the enclosing characters directly.
Do note the existence of
.Li \ec .
T}
T{
.Li \&Ex ,
.Li \&Rv ,
.Li \&St ,
.Li \&At ,
.Li \&Bx ,
.Li \&Bsx ,
.Li \&Nx ,
.Li \&Fx ,
.Li \&Ox ,
.Li \&Dx
T} T{
Write the strings directly.
T}
.TE
.Sh "SEE ALSO"
.Xr eqn 1 ,
.Xr refer 1 ,
.Xr tbl 1 ,
.Xr man 7 ,
.Xr mdoc 7
.Rs
.%A Joseph F. Ossanna
.%A Brian W. Kernighan
.%I AT&T Bell Laboratories
.%T Troff User's Manual
.%R Computing Science Technical Report
.%N 54
.%C Murray Hill, New Jersey
.%D 1976 and 1992
.%U http://www.kohala.com/start/troff/cstr54.ps
.Re

Wonderful, thank you! Much appreciated. 🙂

Alexis.

Hi,

Alejandro Colomar wrote on Sat, Apr 27, 2024 at 10:41:44AM +0200:

If you are familiar with the C programming language, you might be able to use

https://cvsweb.bsd.lv/~checkout~/mandoc/mdoc_man.c?rev=HEAD

which is a fully automatic mdoc-to-man translator and only 39 kB of code.

Caveat: some tasks are harder to do fully automatically than with the human mind. Consequently, that translator for example does not use the man(7) font macros (like .B and .BR) but uses font escapes instead, like \fB and \fR.

However, it does produce these, where appropriate:

HP PD PP RE RS SH SS TE TH TP TS

And the code is ordered according to the mdoc(7) macros, so you can look up an mdoc(7) macro in the mdoc_man_acts[] table at the top, then look at what its one, two, or three handler functions do. If all three handler functions are NULL, no man(7) macro is needed, just put the plain text on a text line in the man(7) file.

Not a bad idea.

In addition, the following alpabetic index may be useful for people who try to write or maintain mdoc(7) documents:

https://mandoc.bsd.lv/mdoc/appendix/markup.html

Once you identified a candidate macro in that list, look at

https://man.openbsd.org/mdoc.7

to learn how to use it.

That sounds quite reasonable, too.

Yours,
Ingo