Created attachment 114741 [details] problem with koha-list man page When viewing the man page for the `koha-list` command, the output does not appear correctly: there appears to be a "staircase" like effect on the text. The same is true for all other man pages, actually. Oddly enough, on an older Koha install of mine (19.11.03) the man page for `koha-list` displays fine. I attach a screenshot which displays the problem.
You might want to email the koha-devel listserv about this one too, since someone there might know more about why this is happening.
I see this problem with Koha 19.11.11, on Debian 9.13. It looks like this affects all our man pages, but I don't think we changed anything in all of them? I suspect the problem is how the man pages are generated from our DocBook files.
It's coming from the spaces between the start of the line and the XML tags. However I have no idea why this problem appeared recently. I have tried with the example at https://tdg.docbook.org/tdg/5.2/refentry.html and I see the same problem.
I'm revisiting this as it's still valid in 22.05.02. Thanks to the comments posted at the following GitHub issue I believe I've found what's causing the broken man pages: https://github.com/docbook/xslt10-stylesheets/issues/123 The source XML files for our man pages have the following namespace declaration at the top: xmlns='http://docbook.org/ns/docbook'. That means they are DocBook V5.0 documents and should be processed by namespace-aware DocBook XSL stylesheets. However, the Stylesheet that generates the man pages from the DocBook XML source files is currently part of the docbook-xsl package. I think we should be using the Stylesheet from the docbook-xsl-ns package instead (I've actually tested this on Debian 9/10/11 and it worked just fine -- the generated man pages did not have any issues).
(In reply to Andreas Roussos from comment #4) > I'm revisiting this as it's still valid in 22.05.02. > > Thanks to the comments posted at the following GitHub issue > I believe I've found what's causing the broken man pages: > https://github.com/docbook/xslt10-stylesheets/issues/123 > > The source XML files for our man pages have the following namespace > declaration at the top: xmlns='http://docbook.org/ns/docbook'. That > means they are DocBook V5.0 documents and should be processed by > namespace-aware DocBook XSL stylesheets. > > However, the Stylesheet that generates the man pages from the DocBook > XML source files is currently part of the docbook-xsl package. > I think we should be using the Stylesheet from the docbook-xsl-ns > package instead (I've actually tested this on Debian 9/10/11 and it > worked just fine -- the generated man pages did not have any issues). I Andreas, I just ran into this issue testing bug 17379. Could you share a patch with your solution?
Created attachment 141594 [details] [review] Bug 27315: use the namespace-aware docbook stylesheet When viewing the man page for the `koha-list` command, the output does not appear correctly: there appears to be a "staircase"-like effect on the text. The same is true for all other man pages. The source XML files for our man pages have the following namespace declaration at the top: xmlns='http://docbook.org/ns/docbook', which means they are DocBook V5.0 documents and should be processed by namespace-aware DocBook XSL stylesheets. This patch fixes that by using the DocBook-to-man-page transformation stylesheet from the docbook-xsl-ns package (note the "-ns" suffix). Test plan: 1) Apply the patch 2) Build and install new package 3) Confirm the man pages display correctly
(In reply to Katrin Fischer from comment #5) > I Andreas, I just ran into this issue testing bug 17379. Could you share a > patch with your solution? Hi Katrin! Sorry for the delay in replying and for taking so long to prepare a patch for this bug report. I've now attached a patch, and wrote a simple test plan which will hopefully be adequate. Please note: instead of replacing `docbook-xsl` in `debian/control.in` with `docbook-xsl-ns`, I opted for *adding* `docbook-xsl-ns` as an extra package in order to avoid any breakage that might occur in case someone was already using the non-namespace-aware variant.
Thanks a lot! I'll leave this for a moment in hope someone will sign-off to make this go into the QA queue :)
Created attachment 141626 [details] [review] Bug 27315: use the namespace-aware docbook stylesheet When viewing the man page for the `koha-list` command, the output does not appear correctly: there appears to be a "staircase"-like effect on the text. The same is true for all other man pages. The source XML files for our man pages have the following namespace declaration at the top: xmlns='http://docbook.org/ns/docbook', which means they are DocBook V5.0 documents and should be processed by namespace-aware DocBook XSL stylesheets. This patch fixes that by using the DocBook-to-man-page transformation stylesheet from the docbook-xsl-ns package (note the "-ns" suffix). Test plan: 1) Apply the patch 2) Build and install new package 3) Confirm the man pages display correctly Signed-off-by: David Nind <david@davidnind.com>
Testing notes (using koha-testing-docker): 1. To replicate the problem: (a) Install man-db: apt-get install man-db (b) man koha-list (or any package command) 2. I wasn't sure how to do step 2 in the test plan, so I: (a) applied the patch (b) installed dockbook-xsl-ns: apt-get install docbook-xsl-ns (c) xsltproc --output /tmp/koha-docs/ /usr/share/xml/docbook/stylesheet/docbook-xsl-ns/manpages/docbook.xsl /kohadevbox/koha/debian/docs/*.xml (d) change to the /tmp/koha-docs directory (e) man -l koha-list.8 (or any package command) (f) gzip -k * (-k = keep source xml files) (g) cp -R *.gz /usr/share/man/man8 (h) man koha-list (or any package command) * 3. Have signed off, as I'm assuming that the build process will now take care of correctly producing the man pages once the change is pushed to master.
> > 3. Have signed off, as I'm assuming that the build process will now take > care of correctly producing the man pages once the change is pushed to > master. Thx for the notes and I'll hope the same :)
Created attachment 141930 [details] [review] Bug 27315: use the namespace-aware docbook stylesheet When viewing the man page for the `koha-list` command, the output does not appear correctly: there appears to be a "staircase"-like effect on the text. The same is true for all other man pages. The source XML files for our man pages have the following namespace declaration at the top: xmlns='http://docbook.org/ns/docbook', which means they are DocBook V5.0 documents and should be processed by namespace-aware DocBook XSL stylesheets. This patch fixes that by using the DocBook-to-man-page transformation stylesheet from the docbook-xsl-ns package (note the "-ns" suffix). Test plan: 1) Apply the patch 2) Build and install new package 3) Confirm the man pages display correctly Signed-off-by: David Nind <david@davidnind.com> Signed-off-by: Katrin Fischer <katrin.fischer.83@web.de>
Pushed to master for 22.11. Nice work everyone, thanks!
Backported to 22.05.x for upcoming 22.05.08
applied to 21.11 for 21.11.15
Not backported to 21.05.x