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
--
"Deep in my heart I wish I was wrong. But deep in my heart I know I am
not." -- Morrissey ("Girl Least Likely To" -- off of Viva Hate.)
