[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [groff] 03/04: doc/groff.texi: Drop most "man" documentation.
From: |
John Gardner |
Subject: |
Re: [groff] 03/04: doc/groff.texi: Drop most "man" documentation. |
Date: |
Mon, 24 Dec 2018 10:06:58 +1100 |
> 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
And yet, mdoc(7) is fundamentally useless for any language or convention
devised post-1990. Documenting an API with mdoc(7) which isn't C/C++ is
like pulling teeth.
Don't praise its semantics too hard.
On Mon, 24 Dec 2018 at 09:51, Ingo Schwarze <address@hidden> wrote:
> 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
>
>