[Top][All Lists]

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

Re: [groff] 03/04: doc/groff.texi: Drop most "man" documentation.

From: Ingo Schwarze
Subject: Re: [groff] 03/04: doc/groff.texi: Drop most "man" documentation.
Date: Sun, 23 Dec 2018 23:51:21 +0100
User-agent: Mutt/1.8.0 (2017-02-23)

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
 - 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*.


reply via email to

[Prev in Thread] Current Thread [Next in Thread]