help
is a bash command. It uses internal bash structures to store and retrieve information about bash commands.
man
is a macro set for the troff (via groff) processor. The output of processing a single file is sent to a pager by the man
command by default.
info
is a text-only viewer for archives in the info format output of Texinfo.
The hier
manual page has a long history that dates back to Unix Seventh Edition in 1979. The one in Linux operating systems is not the original Unix one, but a clone.
At the turn of the century, FreeBSD people documented existing long-standing practice, namely that system administrators adjust stuff for their own systems, and that a good system administrator changes that manual page to match the local adjustments.
Of course, Linux operating systems are notoriously bad when it comes to doco. The hier
manual page is rarely fully adjusted to the actual operating system by the distribution maintainers, if it is adjusted at all. Debian, for example, does not patch it at all, and simply provides the underlying generic hier
manual page from Michael Kerrisk's Linux Manpages Project as-is.
(The BSDs have a generally much stronger tradition of the people who are making changes to the operating system including changes to its doco in what they do. Their doco is better as a result. But it is itself still woefully outdated in some areas. For example: The FreeBSD manual for the ul
command has been missing large parts of the tool since 2.9BSD.)
So Lennart Poettering wrote his own manual page for systemd, file-hierarchy
, in 2014. As you can see, despite its claim it really is not "more minimal" than the hier
page. For starters, it documents a whole load of additional things about user home directories.
Thus there are two different manual pages from two different sets of people, none of whom are the distribution maintainers themselves, who actually decide this stuff.
The simple truth is that real Linux-based operating systems adhere to neither. There are distribution variations from vanilla systemd that don't get patched into the file-hierarchy
page by the distribution maintainers; and as mentioned the hier
page often does not get locally patched either.
They do not adhere to the Linux Filesystem Hierarchy Standard moreover. Several operating systems purposefully deviate from it, and a few of them document this. A few Linux operating systems intentionally do not reference it at all, such as GoboLinux. As you can see from the further reading, Arch Linux used to reference it but has since dropped it.
(I have a strong suspicion, albeit that I have done no rigorous survey, that Arch Linux dropping the FHS is the tipping point, and that adherence to the FHS is the exception rather than the norm for Linux operating systems now.)
For many Linux operating systems there simply is not a single manual page for this. The actual operating system will be an admixture of hier
, file-hierarchy
, the Linux Filesystem Hierarchy Standard, and individual operating system norms with varying degrees of documentation.
Further reading
Best Answer
man
is minimal and simplistic, having only bare-bones commands to define section headings, paragraphs, and subheadings. The package includes some basic formatting commands like.B
,.BI
, and not much else.mdoc
, on the other hand, is a full-featured DSL of its own, with dedicated markup commands for common manpage elements like switches, option and parameter lists, function types and return values, flags, command synopses, and virtually everything you'd expect a manpage markup language to have. Seemdoc(7)
for a complete reference.No.
mdoc
andman
are completely unrelated packages, sharing only a common ancestry and the same goal of marking up computer manual-pages.They don't share anything. It's possible that what you've seen are native Roff commands, which is the underlying typesetting language in which the
mdoc
andman
macros are written in. These tend to be used heavily in documents which useman
, but less so in those which usemdoc
.You can easily distinguish native Roff commands from macros by the way standard Roff packages capitalise their macro names. For
man
, each macro's name is uppercased, like.PP
,.TH
,.SH
, etc. Formdoc
, only the first letter is uppercased:.Pp
,.Dt
,.Sh
, etc.I don't think "predecessor" here was intended to mean anything more than "something similar which was being used before". :-)
The
mdoc
macros have been well-supported for a long time now, having first debuted in 4.4BSD and shipped with every Groff install by default. Both packages can be considered equally portable, unless you're preparing documents for antique terminals from the mid-70s. :)You're on the right track. Modern BSD systems use a program called
mandoc
to format and display manpages, which is a clean reimplementation ofmdoc
using natively-compiled C. It only supports a subset of the Roff language — enough so that legacy manpages display correctly.Mandoc isn't a true typesetting program the way Groff and Heirloom are. Its focus is specifically on computer manuals: and only documents authored with
mdoc
are guaranteed to render consistently and correctly on BSD-derived platforms. More detailed criticisms ofman
can be found inman(7)
.Kind of. Unless you're an experienced manpage author with a sound understanding of Roff grammar and the pipeline's mechanics, you really shouldn't be using anything other than
mdoc
for authoring your manual-pages. Veterantroff
users may findmdoc
to be needlessly verbose or restrictive, findingman
to be lighter and less intrusive. However, these authors are experienced enough to know damn well what they're doing ― so unless you're a grizzled veteran, just stick to usingmdoc
.Further info
If you're interested in learning more about Roff history, and this answer wasn't FMTEYEWTK already, here're some links to authoritative learning material:
mandoc
, which explains the reasoning forman
's obsolescence.