groff
[Top][All Lists]
Advanced

[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
>
>


reply via email to

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