Hi Pascal,
Pascal Stumpf wrote on Tue, Feb 15, 2011 at 11:58:17PM +0100:
> dunno if you???re already aware of this, but it seems pretty much all of
> the manpages in net/samba are somewhat broken. Each one of them starts
> with three blank pages, so one has to hit space three times for the
> actual text to appear. Is that reproducable for anyone?
Oh well, here we go, DocBook once again.
Among the various man(7) code generators out there,
in my experience, DocBook tends to be the one generating
the crappiest and least portable output. Often, DocBook
output portability is so bad that it doesn't even work well
with groff. On top of that, I have seen DocBook bugs
leading to completely garbled syntax of the generated code.
When writing documentation and having a choice, avoid
DocBook completely. Instead, use mdoc(7) directly.
In the samba tarball, specifically, generated man(7) pages exist
in two versions each, for example samba.7 and samba.7.crap.
Both are rather similar, but the *.crap version seems to have
slightly better code quality. So far, I fail to find information
in the tarball what the difference is supposed to be, how they
are generated, and how they are supposed to be processed.
My build just finished, but the build log doesn't tell us much:
the nroff commands seem to be hidden with @ in the Makefiles.
Brilliant, isn't it?
However, here are the results of processing these pages manually
with the ports groff (groff-1.15) and with newest upstream groff
(groff-1.20):
groff-1.15 groff-1.20 mandoc
samba.7 readable, garbled output garbled output
but leading
blank lines
samba.7.crap empty output output is ok garbled output
This situation is typical for DocBook generated man(7) code:
Not being portable even between different versions of groff.
There is no way to fix this quickly. We will have to update
our ports groff to groff-1.20 post-release, which i intend to
do anyway, then check whether the samba build system picks up
the right version ("samba.7.crap") that works with latest,
shiniest groff. Don't ask me about the nomenclature.
You are very welcome to watch the ports@ list, and when you
see the groff-1.20 commit (probably in one or two months
from now) to retest samba. Very probably, we will have to
hack up the build system to somehow make it use the higher
quality *.crap version - in the test build i just ran with
groff-1.20, it still picked up samba.7, producing even
worse output than with groff-1.15, essentially omitting
lots of section headings from the text...
Thanks for reporting,
Ingo
