Opened 3 years ago

Closed 3 years ago

#11559 closed enhancement (fixed)

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

Reported by: Xi Ruoyao Owned by: Bruce Dubbs
Priority: normal Milestone: 8.4
Component: BOOK Version: SVN
Severity: normal Keywords:
Cc:

Description (last modified by 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.

Change History (28)

comment:1 by Bruce Dubbs, 3 years ago

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.

Last edited 3 years ago by Xi Ruoyao (previous) (diff)

comment:2 by Xi Ruoyao, 3 years ago

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}.

Last edited 3 years ago by Xi Ruoyao (previous) (diff)

comment:3 by Xi Ruoyao, 3 years ago

macports#56354 seems like the same issue.

comment:4 by Xi Ruoyao, 3 years ago

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.

Last edited 3 years ago by Xi Ruoyao (previous) (diff)

comment:5 by Xi Ruoyao, 3 years ago

Description: modified (diff)
Summary: xsltproc (with docbook-{xml,xsl}) generates buggy man pagesNon-namespaced docbook-xsl is needed to generate man pages correctly

comment:6 by Xi Ruoyao, 3 years ago

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

comment:7 by Bruce Dubbs, 3 years ago

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.

comment:8 by Xi Ruoyao, 3 years ago

  1. Download docbook-xsl-nons-1.79.2.tar.bz2 package.
  1. tar -xf docbook-xsl-nons-1.79.2.tar.bz2; cd docbook-xsl-nons-1.79.2.
  1. 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
  1. 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
  1. Reinstall polkit, systemd, etc. to fix man pages.

in reply to:  7 comment:9 by Pierre Labastie, 3 years ago

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.

comment:10 by Bruce Dubbs, 3 years ago

Owner: changed from blfs-book to Bruce Dubbs
Status: newassigned

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

in reply to:  10 ; comment:11 by Pierre Labastie, 3 years ago

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

comment:12 by Pierre Labastie, 3 years ago

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

comment:13 by Pierre Labastie, 3 years ago

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

in reply to:  11 comment:14 by Pierre Labastie, 3 years ago

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!!!

comment:15 by Bruce Dubbs, 3 years ago

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.

comment:16 by Pierre Labastie, 3 years ago

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.

comment:17 by ken@…, 3 years ago

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.

comment:18 by Bruce Dubbs, 3 years ago

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

in reply to:  18 ; comment:19 by Pierre Labastie, 3 years ago

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.

comment:20 by Pierre Labastie, 3 years ago

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

in reply to:  19 comment:21 by Xi Ruoyao, 3 years ago

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.

in reply to:  20 comment:22 by Pierre Labastie, 3 years ago

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?

comment:23 by Pierre Labastie, 3 years ago

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 (?)

comment:24 by Bruce Dubbs, 3 years ago

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.

comment:25 by Pierre Labastie, 3 years ago

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...

comment:26 by Douglas R. Reno, 3 years ago

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.

comment:27 by Pierre Labastie, 3 years ago

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.

comment:28 by Douglas R. Reno, 3 years ago

Resolution: fixed
Status: assignedclosed

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

Note: See TracTickets for help on using tickets.