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

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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




[Index of Archives]     [Kernel Documentation]     [Netdev]     [Linux Ethernet Bridging]     [Linux Wireless]     [Kernel Newbies]     [Security]     [Linux for Hams]     [Netfilter]     [Bugtraq]     [Yosemite News]     [MIPS Linux]     [ARM Linux]     [Linux RAID]     [Linux Admin]     [Samba]

  Powered by Linux