Bug 4877

Summary: Create and update the manual pages for the koha-* scripts.
Product: Koha Reporter: Lars Wirzenius <lars>
Component: PackagingAssignee: Magnus Enger <magnus>
Status: CLOSED FIXED QA Contact: Bugs List <koha-bugs>
Severity: normal    
Priority: P3 CC: chris, koha.sekjal, magnus, nengard, paul.poulain, robin
Version: 3.8   
Hardware: All   
OS: All   
See Also: https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=27315
Change sponsored?: --- Patch complexity: ---
Documentation contact: Documentation submission:
Text to go in the release notes:
Version(s) released in:
Bug Depends on:    
Bug Blocks: 2509    
Attachments: Proposed patch, updating the manual page for koha-create
Bug 4877 - Update man page for koha-create
Bug 4877 - more man page improvements
Signed off Robin's followup patch
Proposed patch
Bug 4877 - install generated man pages with build process
Bug 4877 [ENH] Use DocBook for koha-common manual pages
Signed off Robin's followup patch
Bug 4877 - note that the create-db (or related) options are required
Bug 4877 - Add DocBook for missing manual pages
Bug 4877 - Add DocBook for missing manual pages

Description Lars Wirzenius 2010-06-10 01:40:06 UTC
The Debian packaging contains scripts in debian/scripts. Most of those scripts do not have manual pages. Since they are generally useful command line tools for Koha instances, they should have manual page.

There is one page, for koha-create, which could be used as a basis for the others.
Comment 1 Magnus Enger 2011-08-28 13:06:27 UTC Comment hidden (obsolete)
Comment 2 Robin Sheat 2011-08-29 00:23:59 UTC Comment hidden (obsolete)
Comment 3 Robin Sheat 2011-08-29 00:25:23 UTC Comment hidden (obsolete)
Comment 4 Robin Sheat 2011-08-29 00:28:44 UTC
It's a good start, and I made a few additions that I think should help it. BTW, 'man -l koha-create.8' is what I use to view it.

If you can mark this as signed off (assuming that's correct :) so that the patches go in, but when they actually do go through , we should remove the patch-sent status, so it remains open for the other pages.
Comment 5 Magnus Enger 2011-08-29 07:11:22 UTC Comment hidden (obsolete)
Comment 6 Chris Cormack 2011-09-04 08:24:42 UTC
Man pages for scripts provided by packages, pushed please test
Comment 7 Robin Sheat 2011-09-05 00:09:12 UTC
Looks good. Going to reset the status on this and mark the pushed stuff as obsolete so that it remains a place for any other ones we make.
Comment 8 Magnus Enger 2011-09-09 22:43:07 UTC
Editing the man page for koha-create directly was a less than pleasant experience. I'd like to propose that we maintain man pages in DocBook format and transform them to other formats as necessary. See http://wiki.koha-community.org/wiki/Maintaining_man_pages_for_koha-common_as_DocBook_RFC for details. 

I'm adding Nicole on the CC list, since having the opinion of the Documentation Manager on this feels appropriate.
Comment 9 Nicole C. Engard 2011-09-09 22:52:24 UTC
What the heck is a man page?
Comment 10 Magnus Enger 2011-09-09 22:56:51 UTC
(In reply to comment #9)
> What the heck is a man page?

It's what you see when you type "man somecommand" on the commandline. See e.g. http://en.wikipedia.org/wiki/Man_pages :-)
Comment 11 Robin Sheat 2011-09-10 14:02:09 UTC
I'm completely in favour of doing it as docbook, it'll make many things easier. I'm not sure that having one file for all of them is the way to go though, I don't think it'll gain us anything useful, but will cost us a bit of clarity when it comes to having people edit them.

I think generating them as part of the package build is the way to go. We can use a similar kind of process to generate them for the website should we want to (e.g. every week grab the latest copy from the repo and generate the HTML for it.)

Minimising the manual processing needed will ensure that they're always as up to date as possible.
Comment 12 Magnus Enger 2011-09-10 14:05:14 UTC
Sounds good to me. Where should we put the XML files? I can split up my "big" file and do an initial patch.
Comment 13 Robin Sheat 2011-09-11 01:56:02 UTC
Maybe make a debian/docs directory and put them in there?
Comment 14 Magnus Enger 2011-09-13 06:34:21 UTC Comment hidden (obsolete)
Comment 15 Robin Sheat 2011-09-13 23:22:57 UTC
It doesn't add the command to build the man page to the build rules which is something I'd like to have before it's signed off.

Other notes (for dependencies when packaging):
* xsltproc is provided by the package xsltproc
* /usr/share/xml/docbook/stylesheet/docbook-xsl/manpages/docbook.xsl is provided by docbook-xsl

I looked into using docbook-to-man, because (name-wise) it seems ideal for this, however that seems to have not been maintained since 1996 when docbook was just SGML, so I think the xsltproc method is the way to go here.

Finally, the man output appears exactly as I'd expect, so no quibbles there :)
Comment 16 Magnus Enger 2011-09-14 06:30:39 UTC
I'll see what I can do, but if anyone wants to beat me to it, feel free... ;-)
Comment 17 Robin Sheat 2011-09-14 06:48:59 UTC
I might take a bit of a look
Comment 18 Robin Sheat 2011-09-15 05:59:06 UTC Comment hidden (obsolete)
Comment 19 Robin Sheat 2011-09-15 06:00:07 UTC Comment hidden (obsolete)
Comment 20 Magnus Enger 2011-09-15 09:55:08 UTC Comment hidden (obsolete)
Comment 21 Magnus Enger 2011-09-15 09:56:59 UTC
If these two patches get pushed, status should be reset - there are lots more manual pages that need to be created.
Comment 22 Chris Cormack 2011-09-16 01:53:53 UTC
Pushed, and status reset
Comment 23 Robin Sheat 2011-09-22 02:38:43 UTC Comment hidden (obsolete)
Comment 24 Ian Walls 2011-09-22 12:03:19 UTC
Marking latest patch as both signed off and passed QA, since it's an XML-only change (adding an attribute and changing some text, neither of which is likely to cause any kind of regression)
Comment 25 Chris Cormack 2011-09-23 03:14:18 UTC
Pushed
Comment 26 Magnus Enger 2011-09-26 08:16:17 UTC
I turned http://wiki.koha-community.org/wiki/Commands_provided_by_the_Debian_packages into a CSV file and with a small script and a couple of templates turned that into DocBook files and .8 files. The results can be seen here: 

https://github.com/MagnusEnger/kohaman

The XML files are in the output/ folder, .8 files created from the XML are in the manpages/ folder. 

I have also created koha-common.xml, which lists all the commands provided by the packages.

I'll submit a proper patch for this of course, but if anyone can spot general changes that should be made to all the files, now would be a good time. I'll wait a few days before I submit the patch.
Comment 27 Magnus Enger 2011-10-17 10:26:26 UTC Comment hidden (obsolete)
Comment 28 Magnus Enger 2011-10-19 14:31:28 UTC
* To test that latest patch: 

- build packages with build-git-snapshot
- install koha-common
- check that "man <command>" produces sensible output for every command installed by koha-common

* Alternate test plan: 

Check that these provide sensible output: 

1. Generate manual pages (*.8 files)

$ cd debian/docs
$ xsltproc /usr/share/xml/docbook/stylesheet/docbook-xsl/manpages/docbook.xsl koha-*.xml

View generated pages with e.g. "man -l koha-remove.8"

2. Generate HTML

$ xsltproc /usr/share/xml/docbook/stylesheet/docbook-xsl/xhtml/docbook.xsl koha-*.xml > koha-common.html

view koha-common.html in a browser.
Comment 29 Robin Sheat 2011-10-20 06:32:30 UTC Comment hidden (obsolete)
Comment 30 Robin Sheat 2011-10-20 06:34:01 UTC
Please remove the patch-sent and signed-off statuses when this is applied, there's still more stuff to do with these.
Comment 31 Paul Poulain 2011-10-24 11:40:14 UTC
Updating version : This ENH could be in Koha 3.8
Comment 32 Paul Poulain 2011-10-25 15:05:49 UTC
Bug versionned for master. entries will be made against rel_3_8 once the patch has been applied (see thread about that on koha-devel yesterday)
Comment 33 Chris Nighswonger 2011-10-26 18:02:20 UTC
The fix for this bug was published in the 3.4.5 release. If you were the reporter of this bug, please take time to verify the fix and update the status of this bug report accordingly. If the bug is fixed to your satisfaction, please close this report.
Comment 34 Magnus Enger 2011-10-26 18:20:35 UTC
The latest patch here is only signed off and has not been pushed yet. Please don't close until it has been pushed.
Comment 35 Ian Walls 2011-11-19 15:54:42 UTC
Creates a bunch of XML files; while I cannot verify with 100% certainty that the content is correct, I can verify that the documentation does not lead to any regressions anywhere else in the system.  Marking as Passed QA.
Comment 36 Paul Poulain 2011-11-24 09:37:17 UTC
Patch pushed, please test

I played with the xslt as explained by magnus.

I get a warning:
WARNING: cannot add @xml:base to node set root element.  Relative paths may not work.


man -l xxx.8 works fine though, so pushing attachment 6003 [details] [review].

Please test, and, if there are still missing, remove the patch pushed
Comment 37 Paul Poulain 2011-11-24 09:54:40 UTC
Comment on attachment 6003 [details] [review]
Bug 4877 - Add DocBook for missing manual pages

this patch has been pushed
Comment 38 Robin Sheat 2011-11-24 10:10:10 UTC
The warning is ok, not exactly sure what causes it, but it doesn't adversely effect anything.
Comment 39 Magnus Enger 2012-01-10 17:11:28 UTC
The manual pages work in current master, but I can't find a manual page for koha-run-backups, so I'm resetting the status of this bug.
Comment 40 Magnus Enger 2012-09-30 08:05:34 UTC
(In reply to comment #39)
> The manual pages work in current master, but I can't find a manual page for
> koha-run-backups, so I'm resetting the status of this bug.

This is addressed by my patch for Bug 8568, so I'm marking this one as RESOLVED FIXED.