Hi Branden,
i don't feel very strongly about what exactly is said in the texinfo
manual, but i thought a brief comment might make sense anyway.
G. Branden Robinson wrote on Sun, Dec 23, 2018 at 02:33:39PM -0500:
> +The @code{man} macro package is the most widely-used
That is probably true.
> +and probably the most important ever developed for @code{troff}.
That is a matter of opinion. You can argue that the most widely used
is the most important. Then again, by that definition, Microsoft
Windows has been the most important operating system for decades.
Besides, if both terms are defined to mean the same, why say both?
I'd argue that mdoc(7) is more important for a number of reasons,
for example:
1. Regarding theoretical importance:
mdoc(7) applied the concept of semantic markup and of separation
of content and presentation at about the same time as HTML was
developed, whereas the basic concepts of man(7) are still stuck
in a paradigm of markup that faded away in the 1980ies.
2. Regarding practical importance:
mdoc(7) supports vastly superior concepts helping everyday users:
semantic searching, better hyperlinking, style sheet support and
so on, and without excessive complication like texinfo or docbook.
3. So whatever comes after will almost certainly learn more from
mdoc(7) than from man(7).
> It is easy to use,
That's a blatant lie.
- Every user has to painfully learn which kind of content has to be
marked up in which fonts, and there is very little documentation
to help with that. Existing practice is often erratic.
- The syntax of the font alternating macros needs quite some
getting used to because it forces the author to organize bits
and pieces onto input lines by intended typographical effect
rather than by logical function.
- Combining three fonts requires either arcane tricks (\c)
or resorting to low-level roff escapes (\f).
- It is not unusual that existing pages mix up to three different
approaches for the same thing (.B, .ft B, and \fB), so its quite
hard to learn from examples.
- Some important macros like .EX are of limited portability and there
is lots of conflicting and bad advice around regarding how to deal
with that, and none of the options is completely convincing.
Even the experienced user is likely to make bad choices in this
respect.
- Looking at practical manual pages, the man(7) language does not
appear to be self-contained. Most real-world manual pages written
in man(7) use at least some low-level roff requests and escapes
because the macro language is not exactly complete feature-wise.
Yes, very experienced and disciplined writers can almost (but not
completely) avoid that, but that's certainly not easy.
- Reading existing man(7) code is often quite hard because it
often contains custom macro definition, so understanding real
manual page source code often requires detailed understanding
of at least some low-level roff programming syntax, which is
not exactly the easiest programming language for beginners.
- One could probably go on...
Writing good man(7) pages is *hard*.
Yours,
Ingo
