Re: pkg/55123: libxslt's man pages are unreadable

[Ingo Schwarze <schwarze%usta.de@localhost>]

The following reply was made to PR pkg/55123; it has been noted by GNATS.

From: Ingo Schwarze <schwarze%usta.de@localhost>
To: gnats-bugs%netbsd.org@localhost
Cc: Thomas Klausner <tk%giga.or.at@localhost>
Subject: Re: pkg/55123: libxslt's man pages are unreadable
Date: Sat, 28 Mar 2020 23:18:56 +0100

 As wiz@ observed, the xsltproc(1) manual page contains leading
 whitespace, even on macro lines, and large amounts of blank lines.
 Both aren't valid roff(7) syntax.  In other words, that manual page
 is totally broken upstream.
 
 The rule "garbage in - garbage out" applies.  Output generated from
 that totally broken input is very similar with groff(1) and with
 mandoc(1), so this doesn't indicate bugs or missing features in
 mandoc or in groff.  When installing from the OpenBSD ports tree,
 the manual page is totally broken, too, in about the same way, so
 this isn't a NetBSD or pkgsrc problem either.
 
 Please report the broken documentation upstream to xmlsoft.org.
 
 In general, it is an extremely bad idea to use any kind of XML for
 documentation, and DocBook in particular must be avoided at all
 cost.  DocBook is notorious for being very fragile, always generating
 extremely low quality manual pages, and very often generating output
 that is totally unusable and very hard to fix.  Tell upstream to
 switch to some sane input format for maintaining their documentation
 that does *mot* involve XML.  The best formats available are, in
 decreasing order:  1. mdoc(7), 2. perlpod(1), 3. man(7).  Anything
 else is quite bad, but DocBook is by far the worst of all options.
 
 Even though DocBook is very frequently broken (i get several reports
 about it being broken every year, even though i have nothing to do
 with the DocBook project), new ways in which it is broken keep
 showing up; i have no idea what the people maintining it are doing.
 So when dealing with DocBook stuff, there is no easy solution.
 If you want to design a stopgap, you have to look at the individual
 case and hand-roll whatever workaround is needed.
 
 One option may be to completely avoid the usual DocBook toolchain
 in the NetBSD port and instead convert DocBook to manual pages with:
   https://mandoc.bsd.lv/docbook2mdoc/
 That may work for some manual pages, but many DocBook features are
 not yet implemented in docbook2mdoc, so it may not work (yet) for
 others.  I have no idea how easy or hard using that program would
 be from a porting perspective.