Thomas Adam <tho...@fvwm.org> [2014-08-23 23:40:17 +0100]:
> On Sat, Aug 23, 2014 at 09:36:38PM +0100, Michael Treibton wrote:
> > On 23 August 2014 17:30, Thomas Adam <tho...@fvwm.org> wrote:
> > > On Sat, Aug 23, 2014 at 04:36:47PM +0100, Michael Treibton wrote:
> > >> Hi,
> > >>
> > >> taking a look at the mvwm repository, i notice that the documentation
> > >> is using xml. is this still the case? it looks like some of the
> > >> documentation hasn't changed given some changes to the functionality
> > >> in mvwm???
> > >
> > > Have a read of this thread:
> > >
> > > http://thread.gmane.org/gmane.comp.window-managers.fvwm.devel/5886
> >
> > so i have to learn this 'roff' is it? why not use asciidoc which means
> > you can use plain language - theres a lot of syntax markup with
> > mdoc/groff - that makes writing documentation harder.
>
> So, I think the point here is to fundamentally appreciate the difference
> between the roff family (groff, nroff, and troff) and what mdoc
> provides.
>
> Back in the '60s, roff (RUNOFF) came about as a means of a
> typesetter---a way of formatting text. Fast forward some forty years
> and the essence of that survives, in terms of the GNU implementation of
> roff (groff). nroff (new-roff) and troff (AT&T-derived formatting;
> includes things like eqn, tbl, etc.) are all variants/extensions of the
> same thing. In fact, in terms of troff, TeX actually stole some of
> those techniques (c.f. eqn for instance).
>
> What mdoc provides is a sort of subset of roff---it's designed from the
> ground-up, and focuses on the ability to write man pages in it
> (BSD-licenced; OpenBSD has been using it for the last four years). It's
> not as feature-rich as roff, and I've heard some dyed-in-the-wool types
> moan that for GNU/Linux this has some impact in terms of what's rendered
> in man pages, etc., although I personally consider that a red-herring.
> I've yet to come across a man page where there's a reliance on some
> troff extensions, for example.
>
> So with mdoc you have at your disposal a well-engineered back-end system
> which can be used to create just man pages, with the added bonus of
> rendering out other types as well (including (X)HTML/stylesheets). I
> was only on the periphery of the work done by Scott Smedley when Docbook
> was introduced, but even since that point, the way in which
> documentation culminates is horrendous. It's horrific and I for one
> never want to work with it again. I know I'm not alone in thinking
> that; and that's not to imply the work done by those to introduce
> docbook was ever in vain; far from it. It's just something where there
> was not enough discussion and the benefits didn't outweigh the
> replacement, unfortunately.
>
> Of course since that point, there's been an explosion of
> markup/markdown/hidden-markup type things where you can try and write
> all these things in plainer-looking English and hope the parser can
> render it down appropriately. That's what Asciidoc claims to do, and a
> few years ago, I started to define a switch to it, to try and alleviate
> a need to know shitty XML. As it happens, although that kind of worked,
> Asciidoc itself is not stable, in my opinion, and you're left at the
> mercy of things changing too frequently, not to mention a sizeable
> build dependency.
>
> So when you come down to it, the benefits to not writing in *roff are:
>
> * Can be abstracted away; the syntax is irrelevant;
> * Lower learning-curve as the text can be written more in "plain
> English"
>
> But the downsides are:
>
> * Inflexibility with the abstraction not providing the lower-level
> macros for text-formatting;
> * Larger dependencies to compile a document;
> * Sometimes an overhead to learning the abstracted syntax
>
> When you put this on-balance, along with the documentation's history to
> date, going back to the wire, and enforcing mdoc (roff) as a markup
> language brings more benefits to my eyes, than anything else. It's
> verbose, sure, but for a reason. It is what it is, and requires no
> additional packages, etc. It's the lowest common denominator.
>
> > That seems wasteful to me
>
> See above. Anything else I can do for you, let me know.
>
> -- Thomas Adam
Fwiw: As a guy who started at Bell Labs in 1979 (now retired) and wrote gawd
knows how many hundreds of documents in troff [-mm, -man, -metc etc] I heartily
agree with every point Thomas has made. Imo, his brief overview above should
be required reading for anyone contemplating a large doc project.
The learning curve, though somewhat (but not terribly) steeper than the various
more modern "plain English" markups, is well worth the trouble. Even today,
when I write the occasional paper (-mm) or man page (-man), it's invariably in
troff. Ancient perhaps, but even today, nothing beats it, IMO. (The TeX/latex
family seems to be the only serious competitor, and colleagues over the years
familiar with with both seem to like them about equally.)
I would offer the following encouragement to Michael: Every person (without
exception that I recall) who over the years I've badgered, browbeaten,
encouraged, or required to use *roff has been very happy that they took the
plunge. You may laugh that it's 40+ years old, but so are cat, ls, od, sort,
uniq, ........
OK, I'll stop rambling now, with a relevant (and only half-joking) quote
attributed to Henry Spencer:
"Those who do not understand Unix are condemned to reinvent it, poorly."
HTH.
Regards,
Glenn
