Opened 6 years ago
Closed 6 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 ) ¶
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:2 by , 6 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}.
comment:4 by , 6 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.
comment:5 by , 6 years ago
Description: | modified (diff) |
---|---|
Summary: | xsltproc (with docbook-{xml,xsl}) generates buggy man pages → Non-namespaced docbook-xsl is needed to generate man pages correctly |
comment:6 by , 6 years ago
Should we simply change docbook-xsl package to use docbook-xsl-nons tarballs, or add a new package named "docbook-xsl-nons"?
follow-up: 9 comment:7 by , 6 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 , 6 years ago
- Download
docbook-xsl-nons-1.79.2.tar.bz2
package.
tar -xf docbook-xsl-nons-1.79.2.tar.bz2; cd docbook-xsl-nons-1.79.2
.
- 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
- 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
- Reinstall polkit, systemd, etc. to fix man pages.
comment:9 by , 6 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.
follow-up: 11 comment:10 by , 6 years ago
Owner: | changed from | to
---|---|
Status: | new → assigned |
OK, I'll test it out (not expecting any problems) and update the book later today.
follow-up: 14 comment:11 by , 6 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 , 6 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:14 by , 6 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 , 6 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 , 6 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 , 6 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.
follow-up: 19 comment:18 by , 6 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
follow-up: 21 comment:19 by , 6 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.
follow-up: 22 comment:20 by , 6 years ago
The man pages for systemd on anduin should be regenerated too.
comment:21 by , 6 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.
comment:22 by , 6 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 , 6 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 , 6 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 , 6 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 , 6 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 , 6 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 , 6 years ago
Resolution: | → fixed |
---|---|
Status: | assigned → closed |
Fixed at LFS r11501 (Bruce asked me to submit the updated man pages and close the ticket).
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:
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.