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
