From: Ingo Schwarze <schwarze@usta.de>
To: Alexis <flexibeast@gmail.com>
Cc: Alejandro Colomar <alx@kernel.org>,
groff@gnu.org, linux-man@vger.kernel.org
Subject: Re: man(7) <-> mdoc(7) (approximate) correspondence table?
Date: Mon, 13 May 2024 01:49:59 +0200 [thread overview]
Message-ID: <ZkFVp1FAUlYw/eFr@asta-kit.de> (raw)
In-Reply-To: <Ziy6SLSeanPrcKaW@debian>
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
next prev parent reply other threads:[~2024-05-13 0:07 UTC|newest]
Thread overview: 6+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-04-27 6:17 man(7) <-> mdoc(7) (approximate) correspondence table? Alexis
2024-04-27 8:41 ` Alejandro Colomar
2024-04-27 9:41 ` Alexis
2024-05-12 23:49 ` Ingo Schwarze [this message]
2024-04-27 18:52 ` Lennart Jablonka
2024-04-28 4:46 ` Alexis
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=ZkFVp1FAUlYw/eFr@asta-kit.de \
--to=schwarze@usta.de \
--cc=alx@kernel.org \
--cc=flexibeast@gmail.com \
--cc=groff@gnu.org \
--cc=linux-man@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).