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

[John Gardner]

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>

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

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 <https://www.w3.org/TR/xml/#sec-entity-decl> and processor
directives <https://www.w3.org/TR/xml/#entproc> 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 <schwarze@usta.de> 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:
>
>   https://undeadly.org/cgi?action=article&sid=20190419101505
>
> > 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
>
>