Re: net/samba manpages are broken.
On Wed, Feb 16, 2011 at 01:57:18AM +0100, Ingo Schwarze wrote: 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. That's really funny, considering who is responsible both for docbook parsers and groff...
Re: net/samba manpages are broken.
On 2011/02/16 01:57, Ingo Schwarze wrote:
In the samba tarball, specifically, generated man(7) pages exist
in two versions each, for example samba.7 and samba.7.crap.
see /usr/ports/net/samba/Makefile; samba.7 is copied to samba.7.crap
and then some expressions that groff-1.15 can't handle are removed
with sed to generate the samba.7 version.
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.
when groff is updated, this diff can be applied.
Index: Makefile
===
RCS file: /cvs/ports/net/samba/Makefile,v
retrieving revision 1.132
diff -u -p -r1.132 Makefile
--- Makefile17 Jan 2011 17:58:03 - 1.132
+++ Makefile16 Feb 2011 09:01:44 -
@@ -161,15 +161,6 @@ pre-configure:
post-extract:
@cp ${FILESDIR}/krb5-config ${WRKDIR}/bin
@chmod a+x ${WRKDIR}/bin/krb5-config
- @for file in ${SAMBA_MANPAGES}/*; do \
-if [ -f $$file ]; then \
- cp $$file $$file.crap; \
- sed -e 's:\\FC::g' -e 's:\\F\[\]::g' -e 's:\.\\\:\ \\\:g' \
- -e 's:SH-xref:Sx:g' -e 's:\\m\[\]::g' -e 's:toupper:tu:g' \
- -e 's:\.\.\\\:\\\:g' -e 's:^.tu :\\:g' -e's:\\m\[blue\]::g' \
- -e's:\\m\[\]::g' $$file.crap $$file; \
-fi; \
- done
post-install:
${INSTALL_DATA_DIR} ${PREFIX}/share/doc/samba/pdf
Re: net/samba manpages are broken.
On 16/02/2011 8:03 PM, Stuart Henderson wrote:
On 2011/02/16 01:57, Ingo Schwarze wrote:
In the samba tarball, specifically, generated man(7) pages exist
in two versions each, for example samba.7 and samba.7.crap.
see /usr/ports/net/samba/Makefile; samba.7 is copied to samba.7.crap
and then some expressions that groff-1.15 can't handle are removed
with sed to generate the samba.7 version.
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.
when groff is updated, this diff can be applied.
Index: Makefile
===
RCS file: /cvs/ports/net/samba/Makefile,v
retrieving revision 1.132
diff -u -p -r1.132 Makefile
--- Makefile17 Jan 2011 17:58:03 - 1.132
+++ Makefile16 Feb 2011 09:01:44 -
@@ -161,15 +161,6 @@ pre-configure:
post-extract:
@cp ${FILESDIR}/krb5-config ${WRKDIR}/bin
@chmod a+x ${WRKDIR}/bin/krb5-config
- @for file in ${SAMBA_MANPAGES}/*; do \
-if [ -f $$file ]; then \
- cp $$file $$file.crap; \
- sed -e 's:\\FC::g' -e 's:\\F\[\]::g' -e 's:\.\\\:\ \\\:g' \
- -e 's:SH-xref:Sx:g' -e 's:\\m\[\]::g' -e 's:toupper:tu:g' \
- -e 's:\.\.\\\:\\\:g' -e 's:^.tu :\\:g' -e's:\\m\[blue\]::g' \
- -e's:\\m\[\]::g' $$file.crap $$file; \
-fi; \
- done
post-install:
${INSTALL_DATA_DIR} ${PREFIX}/share/doc/samba/pdf
Umm, yeah the .crap files are my doing. Historically the samba man pages
caused this nice error
fatal error: input stack limit exceeded (probable infinite loop)
and as such we had no man pages. The above was added to make them work with our
old
intree groff before removal. It's needs revisiting
Ian McWilliam
Re: net/samba manpages are broken.
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.20mandoc samba.7readable,garbled outputgarbled 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
