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

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

[Alexis]

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

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

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1671 bytes --]

Hi Alexis,

On Sat, Apr 27, 2024 at 04:17:28PM +1000, Alexis wrote:
> [ 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 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.

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

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

> Alexis.

Have a lovely weekend!
Alex

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

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

[Alexis]

Hi Alejandro,

Thanks for your reply! Responses inline.

Alejandro Colomar <alx@kernel.org> writes:

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

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.

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

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


Alexis.

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

[Ingo Schwarze]

Hi,

Alejandro Colomar wrote on Sat, Apr 27, 2024 at 10:41:44AM +0200:
> On Sat, Apr 27, 2024 at 04:17:28PM +1000, Alexis wrote:

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

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.


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

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.

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

That sounds quite reasonable, too.

Yours,
  Ingo

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

[Lennart Jablonka]

'\" t
.
.\" SPDX-FileCopyrightText: 2024 Lennart Jablonka <humm@ljabl.com>
.\" 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

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

[Alexis]

Lennart Jablonka <humm@ljabl.com> writes:

> [snip mdoc-man-cmp.7 source] 

Wonderful, thank you! Much appreciated. 🙂


Alexis.