Summary: | The man pages for the command line utilities do not display properly | ||
---|---|---|---|
Product: | Koha | Reporter: | Andreas Roussos <a.roussos> |
Component: | Documentation | Assignee: | Bugs List <koha-bugs> |
Status: | CLOSED FIXED | QA Contact: | Testopia <testopia> |
Severity: | minor | ||
Priority: | P5 - low | CC: | arthur.suzuki, david, dcook, jonathan.druart, lucas, magnus, wainuiwitikapark |
Version: | Main | ||
Hardware: | All | ||
OS: | All | ||
See Also: | https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=4877 | ||
Change sponsored?: | --- | Patch complexity: | Trivial patch |
Documentation contact: | Documentation submission: | ||
Text to go in the release notes: | Version(s) released in: |
22.11.00, 22.05.08, 21.11.15
|
|
Circulation function: | |||
Attachments: |
problem with koha-list man page
Bug 27315: use the namespace-aware docbook stylesheet Bug 27315: use the namespace-aware docbook stylesheet Bug 27315: use the namespace-aware docbook stylesheet |
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 |
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.