Request: add information on cross-platform mdoc about guides HOT 10 CLOSED

Hmm, okay. Well, we've at least confirmed that mdoc files can be handled OOTB on macOS, so i've listed it in the Appendix A table, with "?" under the "man system" column.

On the basis of the various changes i've made to the document, i feel i can now close this issue. Thanks for your feedback and input!

from guides.

Hmm, it seems i definitely need to add some clarifying text! Whether one writes man pages via the man(7) macros or the mdoc(7) macros, there's no 'compiling' that needs to be done; the source is rendered on-the-fly via the system's man command. On OpenBSD, and Linux systems that use mandoc as the default man system like Void and Alpine, the man command indeed calls mandoc; but on OSes where man-db is the default man system, such as Debian, Arch, Fedora and Gentoo, downloading the raw mdoc-examples.7 file from this repo and running:

$ man ./mdoc-examples.7

should render that man page just fine, because it's not mandoc that's needed, it's the ability to interpret mdoc(7) macros, and man-db can indeed do that without any special configuration on the part of the user.

My daily driver is Gentoo, and i've set mandoc as the system man, but i recently confirmed in a Debian VM that man-db's man rendered mdoc(7) source without issues. i don't have access to macOS, so have no idea how things are set up there - all i can tell, based on the man-db home page, is that man-db is not the default man system - and i don't have a FreeBSD system to hand either. Do you have access to those OSes, to check what happens when one runs the above command?

from guides.

i've just made a number of changes to the guide, which i hope now clarifies and explains things better.

from guides.

man ./mdoc-examples.7 seems pretty reasonable on my Mac, except where it uses an en dash instead of an em dash in the NAME section:

MDOC-EXAMPLES(7)             Miscellaneous Information Manual             MDOC-EXAMPLES(7)

NAME
     mdoc-examples – print example mdoc source to stdout

SYNOPSIS
     mdoc-examples [-v | -h]

DESCRIPTION
     mdoc-examples prints some example mdoc(7) source to stdout.

OPTIONS
     -v
        Print version information to stdout.

     -h
        Print usage information to stdout.

EXIT STATUS
     If mdoc-examples is able to print the examples, it exits with status code 0.
     Otherwise, it exits with status code -1.

SEE ALSO
     mandoc(1), mdoc(7), roff(7)

AUTHORS
     Alexis

macOS 12.3                            January 1, 2020                           macOS 12.3

Ditto on my FreeBSD machine (right down to the en-dash nitpick):

MDOC-EXAMPLES(7)   FreeBSD Miscellaneous Information Manual   MDOC-EXAMPLES(7)

NAME
     mdoc-examples – print example mdoc source to stdout

SYNOPSIS
     mdoc-examples [-v | -h]

DESCRIPTION
     mdoc-examples prints some example mdoc(7) source to stdout.

OPTIONS
     -v
        Print version information to stdout.

     -h
        Print usage information to stdout.

EXIT STATUS
     If mdoc-examples is able to print the examples, it exits with status code
     0.  Otherwise, it exits with status code -1.

SEE ALSO
     mandoc(1), mdoc(7), roff(7)

AUTHORS
     Alexis

FreeBSD 13.0-RELEASE-p4         January 1, 2020        FreeBSD 13.0-RELEASE-p4

When I widen my Terminal windows to ridiculous widths like 166 columns, things wrap as they should. Nothing's limited to 80 columns.

So if I generate a .7 (or .1…, or…) file (what's the format of these, again? Something that ends in "ff"?), It seems like all the capital-F Free unixalikes, plus macOS, can handle these things just fine, unless there are other macros that are mdoc-only or something. That's good news, however tentative.

I'd check whether my Mac and FreeBSD machines are actually running mandoc or man-db or something else, but I ran man man on my Mac and couldn't figure out which it was, if it was either.

from guides.

It's an en dash on my system also.

Technically these files are roff files. Although there are similarities between the two macro sets (man .SH, mdoc .Sh; man .SS, mdoc .Ss), there are also clashes (e.g. man .DT and mdoc .Dt do two very different things). So the mdoc-examples.7 isn't displayed (mostly) okay because there's a common subset of the two macro packages being used; it's because the opening line indicates whether the page uses the man(7) macros or the mdoc(7) macros[1], and the both the man(7) macros and the mdoc(7) macros are understood by both groff and mandoc.

A system running mandoc should, of course, have mandoc(1) available - is that the case on either of the machines you mentioned?

[1] A man(7) page will (should!) have .TH at the start of its first line, an mdoc(7) page will (should!) have .Dd.

from guides.

A system running mandoc should, of course, have mandoc(1) available - is that the case on either of the machines you mentioned?

which mandoc gives me /usr/bin/mandoc on both macOS 12.3 Monterey and FreeBSD 13.

from guides.

Okay, that certainly gels with this table i found, which suggests that mandoc became FreeBSD's default formatter of man pages in November 2014 - not sure what version of FreeBSD that was? However, in terms of macOS, that table doesn't list anything more than when a mandoc package became available for it.

Another possible way of finding which man system is in use might be to examine the HISTORY section of the man(1) man page - the man-db version has

31st March 2001 – present day: Colin Watson [email protected] is now developing and maintaining man-db.

as its final para, whereas the mandoc version has

The -w option first appeared in Version 7 AT&T UNIX; -f and -k in 4BSD; -M in 4.3BSD; -a in 4.3BSD-Tahoe; -c and -m in 4.3BSD-Reno; -h in 4.3BSD-Net/2; -C in NetBSD 1.0; -s and -S in OpenBSD 2.3; and -I, -K, -l, -O, and -W in OpenBSD 5.7. The -T option first appeared in AT&T System III UNIX and was also added in OpenBSD 5.7.

from guides.

All we have is AUTHOR in Apple land for man man:

AUTHOR
       John W. Eaton was the original author of man.  Zeyd M. Ben-Halim released man 1.2,
       and Andries Brouwer followed up with versions 1.3 thru 1.5p.  Federico Lucifredi
       <[email protected]> is the current maintainer.

from guides.

Is groff available on that system? If not, i would guess mandoc is probably the underlying formatter.

from guides.

Seems built-in to me:

> which groff
/usr/bin/groff

from guides.