Non-namespaced docbook-xsl is needed to generate man pages correctly

[Xi Ruoyao]

For example, the generated man pages of systemd, polkit, bubblewrap, and glib are all buggy.

I initially thought I'd done something wrong, but then I found that the pre-built systemd man pages in LFS (​http://anduin.linuxfromscratch.org/LFS/systemd-man-pages-240.tar.xz) are also broken.

In ​this comment Bob said:

I have one idea of what might have caused this. Versions 1.79.1 and 1.79.2 should be functionally equivalent. The difference is that we switched the source from non-namespaced XML to namespaced XML, and now build the non-namespaced XML. And we renamed the packages. So docbook-xsl-nons-1.79.2 is equivalent to docbook-xsl-1.79.1, and docbook-xsl-1.79.2 is equivalent to docbook-xsl-ns-1.79.1. So see if the whitespace issue still persists if you switch the package.

[Bruce Dubbs]

I took a look at this and can't say for sure why it is happening. However I was able to post-process the generated man pages and improve them, although it may not be perfect.

In a man page, the formatting is done with a 'dot' command like .PP

The dot must be in column 1 and in the problem pages, many are preceded by white space.

Post processing polkit.8 with:

sed -i -r 's/^{\s+\././' polkit.8}

seemed to fix that man page.

The processing is done with docbook-xsl 1.79.2. I do note that Arch has one patch to that packege at ​https://git.archlinux.org/svntogit/packages.git/tree/trunk/765567_non-recursive_string_subst.patch?h=packages/docbook-xsl

I don't see how that affects man pages, but it might.

[Xi Ruoyao]

I don't think this patch is revelent to man pages. But Arch is still using docbook-xml-4.1.2 and "fake" it as docbook-4.{2..5}.

[Xi Ruoyao]

​macports#56354 seems like the same issue.

[Xi Ruoyao]

See ​Ryan's comment.

I installed docbook-xsl-nons-1.79.2 from ​https://github.com/docbook/xslt10-stylesheets/releases/download/release%2F1.79.2/docbook-xsl-nons-1.79.2.tar.bz2. Then I changed the command in "Configuration Information" section to use docbook-xsl-nons instead of docbook-xsl. That fixed systemd man pages.

[Xi Ruoyao]

Should we simply change docbook-xsl package to use docbook-xsl-nons tarballs, or add a new package named "docbook-xsl-nons"?

[Bruce Dubbs]

It is unclear to me what instructions you used when installing and configuring the -nons version of the package. Can you be more specific please.

[Xi Ruoyao]

1. Download docbook-xsl-nons-1.79.2.tar.bz2 package.

2. tar -xf docbook-xsl-nons-1.79.2.tar.bz2; cd docbook-xsl-nons-1.79.2.

3. Install the package:

install -v -m755 -d /usr/share/xml/docbook/xsl-stylesheets-nons-1.79.2 &&

cp -v -R VERSION assembly common eclipse epub epub3 extensions fo        \
         highlighting html htmlhelp images javahelp lib manpages params  \
         profiling roundtrip slides template tests tools webhelp website \
         xhtml xhtml-1_1 xhtml5                                          \
    /usr/share/xml/docbook/xsl-stylesheets-nons-1.79.2 &&

ln -s VERSION /usr/share/xml/docbook/xsl-stylesheets-nons-1.79.2/VERSION.xsl &&

install -v -m644 -D README \
                    /usr/share/doc/docbook-xsl-nons-1.79.2/README.txt &&
install -v -m644    RELEASE-NOTES* NEWS* \
                    /usr/share/doc/docbook-xsl-nons-1.79.2

4. Update XML catalog:

if [ ! -d /etc/xml ]; then install -v -m755 -d /etc/xml; fi &&
if [ ! -f /etc/xml/catalog ]; then
    xmlcatalog --noout --create /etc/xml/catalog
fi &&

xmlcatalog --noout --add "rewriteSystem" \
           "https://cdn.docbook.org/release/xsl-nons/1.79.2" \
           "/usr/share/xml/docbook/xsl-stylesheets-nons-1.79.2" \
    /etc/xml/catalog &&

xmlcatalog --noout --add "rewriteURI" \
           "https://cdn.docbook.org/release/xsl-nons/1.79.2" \
           "/usr/share/xml/docbook/xsl-stylesheets-nons-1.79.2" \
    /etc/xml/catalog &&

xmlcatalog --noout --add "rewriteSystem" \
           "https://cdn.docbook.org/release/xsl-nons/current" \
           "/usr/share/xml/docbook/xsl-stylesheets-nons-1.79.2" \
    /etc/xml/catalog &&

xmlcatalog --noout --add "rewriteURI" \
           "https://cdn.docbook.org/release/xsl-nons/current" \
           "/usr/share/xml/docbook/xsl-stylesheets-nons-1.79.2" \
    /etc/xml/catalog &&

xmlcatalog --noout --add "rewriteSystem" \
           "http://docbook.sourceforge.net/release/xsl/current" \
           "/usr/share/xml/docbook/xsl-stylesheets-nons-1.79.2" \
    /etc/xml/catalog &&

xmlcatalog --noout --add "rewriteURI" \
           "http://docbook.sourceforge.net/release/xsl/current" \
           "/usr/share/xml/docbook/xsl-stylesheets-nons-1.79.2" \
    /etc/xml/catalog

5. Reinstall polkit, systemd, etc. to fix man pages.

[Pierre Labastie]

Replying to bdubbs:

It is unclear to me what instructions you used when installing and configuring the -nons version of the package. Can you be more specific please.

IIUC, up to 1.79.1, there were two docbook-xsl packages:

docbook-xsl-1.79.1.tar.bz2
docbook-xsl-ns-1.79.1.tar.bz2

so that we were using the non-namespaced version of the stylecheets.

Now there are still two docbook-xsl packages, but the default has been switched:

docbook-xsl-nons-1.79.2.tar.bz2
docbook-xsl-1.79.2.tar.bz2

so that we are currently installing the namespaced version...

I think xry111's proposition is to use the nons tarball.

[Bruce Dubbs]

OK, I'll test it out (not expecting any problems) and update the book later today.

[Pierre Labastie]

Replying to bdubbs:

OK, I'll test it out (not expecting any problems) and update the book later today.

BTW, I think the patch is not needed anymore: it has been included in 1.79.2

[Pierre Labastie]

Also, I think the page should be renamed docbook-xsl-nons: it makes it clearer for readers what is on the page.

[Pierre Labastie]

Note that the namespaced version is for docbook-xml-5.

[Pierre Labastie]

Replying to pierre.labastie:

Replying to bdubbs:

OK, I'll test it out (not expecting any problems) and update the book later today.

BTW, I think the patch is not needed anymore: it has been included in 1.79.2

Ah no, sorry, it is not in the nons version!!!

[Bruce Dubbs]

I'll leave the patch in. So far things look OK, but I'll add a note about removing previous rewrite commands from the catalog file.

[Pierre Labastie]

FWIIW, here are the man pages which seem malformed on a recently build system:

/usr/share/man/man7/drm-kms.7
/usr/share/man/man7/drm.7
/usr/share/man/man7/drm-memory.7
/usr/share/man/man3/drmAvailable.3
/usr/share/man/man3/drmHandleEvent.3
/usr/share/man/man3/drmModeGetResources.3
/usr/share/man/man1/gio-querymodules.1
/usr/share/man/man1/xdg-mime.1
/usr/share/man/man1/glib-compile-schemas.1
/usr/share/man/man1/gio.1
/usr/share/man/man1/gdbus-codegen.1
/usr/share/man/man1/xdg-settings.1
/usr/share/man/man1/xdg-email.1
/usr/share/man/man1/xdg-desktop-icon.1
/usr/share/man/man1/xdg-icon-resource.1
/usr/share/man/man1/gdbus.1
/usr/share/man/man1/xdg-open.1
/usr/share/man/man1/gtester.1
/usr/share/man/man1/gsettings.1
/usr/share/man/man1/gresource.1
/usr/share/man/man1/gapplication.1
/usr/share/man/man1/glib-compile-resources.1
/usr/share/man/man1/xdg-screensaver.1
/usr/share/man/man1/xdg-desktop-menu.1

and also polkit pages, which I had already fixed. In addition to glib, libdrm and xdg-utils are affected too.

Note that I have built about one fourth of the book.

[ken@…]

Interesting. AFAICS, we picked up what now turns out to be the namespaced version between BLFS-8.1 and BLFS-8.2. When I discovered in last July/August that creating gimp-help from git snapshots was no-longer picking up most images (and therefore was not at all helpful - see #11007), examination eventually showed that creating the help pages worked correctly in BLFS-8.1 but was broken by BLFS-8.2.

Oddly, the problem appeared to be specific to BLFS. Will need to take another look at that when this goes in.

[Bruce Dubbs]

I've updated the books at revision 21002, but will leave the ticket open for now. I request feedback for the page ​http://www.linuxfromscratch.org/blfs/view/svn/pst/docbook-xsl.html

[Pierre Labastie]

Replying to bdubbs:

I've updated the books at revision 21002, but will leave the ticket open for now. I request feedback for the page ​http://www.linuxfromscratch.org/blfs/view/svn/pst/docbook-xsl.html

 xmlcatalog --noout --add "rewriteSystem" \
-           "http://docbook.sourceforge.net/release/xsl/&docbook-xsl-version;" \
-           "/usr/share/xml/docbook/xsl-stylesheets-&docbook-xsl-version;" \
+           "https://cdn.docbook.org/release/xsl-nons/1.79.2" \
+           "/usr/share/xml/docbook/xsl-stylesheets-nons-1.79.2" \
+    /etc/xml/catalog &&

Looks like you have hardcoded the version (and at other places too). Is it intentional?

Otherwise, seems to work.

[Pierre Labastie]

The man pages for systemd on anduin should be regenerated too.

[Xi Ruoyao]

Replying to pierre.labastie:

Replying to bdubbs:

I've updated the books at revision 21002, but will leave the ticket open for now. I request feedback for the page ​http://www.linuxfromscratch.org/blfs/view/svn/pst/docbook-xsl.html

 xmlcatalog --noout --add "rewriteSystem" \
-           "http://docbook.sourceforge.net/release/xsl/&docbook-xsl-version;" \
-           "/usr/share/xml/docbook/xsl-stylesheets-&docbook-xsl-version;" \
+           "https://cdn.docbook.org/release/xsl-nons/1.79.2" \
+           "/usr/share/xml/docbook/xsl-stylesheets-nons-1.79.2" \
+    /etc/xml/catalog &&

Looks like you have hardcoded the version (and at other places too). Is it intentional?

I think it's a mistake... The HTML page LGTM.

[Pierre Labastie]

Replying to pierre.labastie:

The man pages for systemd on anduin should be regenerated too.

I can generate them, but compared to what is on anduin, a few pages are missing (because I do not have some optional dependencies):

crypttab.5
systemd-cryptsetup.8
systemd-cryptsetup-generator.8
systemd-cryptsetup@.service.8
systemd.directives.7
systemd.directives.xml
systemd-importd.8
systemd-importd.service.8
systemd.index.7
systemd.index.xml
systemd-veritysetup.8
systemd-veritysetup-generator.8
systemd-veritysetup@.service.8

I'm almost sure they are not needed for LFS anyway. Do we want to have those man pages?

[Pierre Labastie]

Well, we at least want the .index and .directives man pages, and I do not know how they are generated (there is no source)... Made some progress: lxml is needed for generating the directives and the index. Not noted as optional (?)

[Bruce Dubbs]

Hard coding 1.79.2 was an oversight. It won't affect anything until docbook-xsl releases a new version, but I'll update it later today.

As far as the systemd man pages go, I'll let Doug do the tarball update on anduin. The timing is not critical, so a day or two to get this done is no issue.

[Pierre Labastie]

I think I've done the man pages correctly now. I'll upload to anduin and fix the md5sum in the book (hopefully the size is the same).

Ah no, I can't, because the file does not have the group write attribute on anduin, and it belongs to renodr...

If anybody with the appropriate rights want to upload it, it is in my home dir on anduin...

[Douglas R. Reno]

I'm certain the missing manpages are going to cause problems. The reason why we have them pre-generated for LFS is because otherwise there is a hard dependency on libxslt, libxml2, docbook-*, and a few other packages as it will try to build the man pages unless they're pregenerated. We don't need that cruft in LFS, so we generate it and provide it as a separate download. Meson/Ninja is very picky about missing files, including man pages...

I'll give your tarball a shot in a few. Need to finish catching up first.

[Pierre Labastie]

The tarball in my home on anduin contains the same pages as the one in srv/www/LFS. There are no missing pages anymore. I've added lxml as an optional dependency for systemd (needed for generating the index).

All the missing man pages above (except index and directives) were missing because cryptsetup was not on my system. Now that it is, the man pages are generated.

[Douglas R. Reno]

Fixed at LFS r11501 (Bruce asked me to submit the updated man pages and close the ticket).