[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]
Re: pkg/55123: libxslt's man pages are unreadable
The following reply was made to PR pkg/55123; it has been noted by GNATS.
From: Ingo Schwarze <schwarze%usta.de@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:
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.
Main Index |
Thread Index |