[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: (off topic?) Docbook? Re: manlint?

From: John Gardner
Subject: Re: (off topic?) Docbook? Re: manlint?
Date: Tue, 15 Sep 2020 20:42:26 +1000

XML is verbose, cumbersome to read and write, and has two different ways to
express data structures:

<doc title="My stupid document" enabled="true"></doc>

    <title>My stupid document</title>
    <enabled />

Conversely, JSON is more concise and predictable:

{ "title": "My stupid document", "enabled": true }

XML isn't an easy format to (correctly) parse, either: stuff like entity
declarations <> and processor
directives <> need to be dealt with on
top of DTD, XSLT, and correct element nesting.

Unless data can be adequately expressed as tab- and newline-delimited
lists, JSON is a *hell* of a lot easier to work with than XML.

On Tue, 15 Sep 2020 at 19:14, Ingo Schwarze <> wrote:

> Hi Marc,
> Marc Chantreux wrote on Tue, Sep 15, 2020 at 08:07:39AM +0200:
> > I loved the docbook structure and metainfos
> Then you only had a very superficial look at DocBook.
> In fact, the design of the DocBook markup language
> is of extremely poor quality.  For details, see:
> > but ran away because of xml.
> It is true that XML is a vastly overengineered, heavy-weight,
> and very cumbersome markup language framework.
> But the many specific ways in which DocBook is ill-designed
> are much worse than the fact that it uses XML.
> It would almost certainly be possible to design an XML-based
> markup language that would be good enough for practical use in
> software documentation, but that's not DocBook.  Then again,
> there is no need to do that work because both the roff(7)
> and the TeX markup language frameworks are clearly superior
> to XML.
> [...]
> > the combo pug/docbook would be nice to me but i have the feeling
> > that xml (and its well deserved decay) killed docbook.
> I never heard about pug, but in view of the many terrible mistakes
> made in DocBook language design, blaming XML feels like a distortion
> to me.
> > is the docbook community still active?
> I'm not convinced a "community" ever existed.  IIUC, it was a
> design-by-committee large-corporation project from the start.
> > are the tools maintained?
> It doesn't matter much.  The toolchain is of such abysmal quality
> that it's besically useless even if it were maintained.  The man(7)
> output of the standard DocBook toolchain is by far the worst man(7)
> code you can find anywhere.  It is precisely the opposite of what
> esr@ is doing with doclifter: that output is full of blatant roff(7)
> syntax errors, full of abuse of non-portable and poorly understood
> low-level roff(7) features, and usually causing severe misformatting.
> On top of that, the concept of using XSLT is very fragile for
> generating roff(7) output because XSLT is best suited for output
> languages where line breaks and spaces are syntactically equivalent
> and where blank lines and indentation are syntactically insignificant.
> Using XSLT to generate output in a language like roff(7) where line
> breaks, blank lines, indentation, and strings of multiple space
> characters are all syntactically significant is very difficult and
> very fragile.
> So even if someone would try to maintain this mess, decent
> results could not be expected.
> Yours,
>   Ingo

reply via email to

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