Bug 27315 - The man pages for the command line utilities do not display properly
Summary: The man pages for the command line utilities do not display properly
Status: RESOLVED FIXED
Alias: None
Product: Koha
Classification: Unclassified
Component: Documentation (show other bugs)
Version: master
Hardware: All All
: P5 - low minor (vote)
Assignee: Andreas Roussos
QA Contact: Katrin Fischer
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2020-12-30 07:40 UTC by Andreas Roussos
Modified: 2023-12-28 20:44 UTC (History)
7 users (show)

See Also:
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


Attachments
problem with koha-list man page (23.04 KB, image/png)
2020-12-30 07:40 UTC, Andreas Roussos
Details
Bug 27315: use the namespace-aware docbook stylesheet (2.04 KB, patch)
2022-10-11 06:54 UTC, Andreas Roussos
Details | Diff | Splinter Review
Bug 27315: use the namespace-aware docbook stylesheet (2.09 KB, patch)
2022-10-11 22:36 UTC, David Nind
Details | Diff | Splinter Review
Bug 27315: use the namespace-aware docbook stylesheet (2.15 KB, patch)
2022-10-15 19:32 UTC, Katrin Fischer
Details | Diff | Splinter Review

Note You need to log in before you can comment on or make changes to this bug.
Description Andreas Roussos 2020-12-30 07:40:17 UTC
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.
Comment 1 David Cook 2021-01-04 01:22:58 UTC
You might want to email the koha-devel listserv about this one too, since someone there might know more about why this is happening.
Comment 2 Magnus Enger 2021-01-04 08:30:50 UTC
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.
Comment 3 Jonathan Druart 2021-01-04 09:37:32 UTC
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.
Comment 4 Andreas Roussos 2022-07-23 15:31:46 UTC
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).
Comment 5 Katrin Fischer 2022-10-08 10:40:22 UTC
(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?
Comment 6 Andreas Roussos 2022-10-11 06:54:27 UTC
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
Comment 7 Andreas Roussos 2022-10-11 07:02:11 UTC
(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.
Comment 8 Katrin Fischer 2022-10-11 09:56:03 UTC
Thanks a lot! I'll leave this for a moment in hope someone will sign-off to make this go into the QA queue :)
Comment 9 David Nind 2022-10-11 22:36:10 UTC
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>
Comment 10 David Nind 2022-10-11 22:39:28 UTC
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.
Comment 11 Katrin Fischer 2022-10-15 19:30:41 UTC
> 
> 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 :)
Comment 12 Katrin Fischer 2022-10-15 19:32:15 UTC
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>
Comment 13 Tomás Cohen Arazi 2022-10-18 00:15:24 UTC
Pushed to master for 22.11.

Nice work everyone, thanks!
Comment 14 Lucas Gass 2022-12-05 20:38:47 UTC
Backported to 22.05.x for upcoming 22.05.08
Comment 15 Arthur Suzuki 2022-12-16 13:30:23 UTC
applied to 21.11 for 21.11.15
Comment 16 wainuiwitikapark 2023-03-15 00:57:18 UTC
Not backported to 21.05.x