> 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 <[email protected]> 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 > >
