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.
Created attachment 5184 [details] [review] Proposed patch, updating the manual page for koha-create This patch is an update for the already existing manual page for koha-create. It's my first attempt at editing a manual page, so please don't be kind to it. The best trick I have found for viewing it is: nroff -man debian/scripts/koha-create.8 | less Note: All the other commands provided by koha-common still lack manual pages, and there should probably be one for koha-common itself too.
Created attachment 5196 [details] [review] Bug 4877 - Update man page for koha-create Signed-off-by: Robin Sheat <robin@catalyst.net.nz> (to be followed by another patch that I think helps too)
Created attachment 5197 [details] [review] Bug 4877 - more man page improvements
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.
Created attachment 5205 [details] [review] Signed off Robin's followup patch Signing off on Robin's patch.
Man pages for scripts provided by packages, pushed please test
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.
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.
What the heck is a man page?
(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 :-)
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.
Sounds good to me. Where should we put the XML files? I can split up my "big" file and do an initial patch.
Maybe make a debian/docs directory and put them in there?
Created attachment 5413 [details] [review] Proposed patch This patch - deletes debian/scripts/koha-create.8 - adds debian/docs/koha-create.xml and koha-remove.xml To test: Check that something like this: xsltproc /usr/share/xml/docbook/stylesheet/docbook-xsl/manpages/docbook.xsl koha-*.xml produces sensible output. The output from koha-create.xml should be very similar to the old koha-create.8.
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 :)
I'll see what I can do, but if anyone wants to beat me to it, feel free... ;-)
I might take a bit of a look
Created attachment 5433 [details] [review] Bug 4877 - install generated man pages with build process This uses the docbook source files to generate the man pages, and installs them to their correct location when the packages are being built. This will make it easier for people to write man pages, thereby ensuring that people join in keeping documentation up to date. Note: adds docbook-xsl and xsltproc to the dependencies. Note2: applies on top of Magnus' other patch on this ticket.
Created attachment 5434 [details] [review] Bug 4877 [ENH] Use DocBook for koha-common manual pages This patch - deletes debian/scripts/koha-create.8 - adds debian/docs/koha-create.xml and koha-remove.xml Signed-off-by: Robin Sheat <robin@catalyst.net.nz>
Created attachment 5435 [details] [review] Signed off Robin's followup patch - Applied Robin's patch on a branch off current master - Built packages with build-git-snapshot - Installed koha-common on a fresh VM - "man koha-create" and "man koha-remove" produced the expected output. Signing off!
If these two patches get pushed, status should be reset - there are lots more manual pages that need to be created.
Pushed, and status reset
Created attachment 5527 [details] [review] Bug 4877 - note that the create-db (or related) options are required Also fix the example so that it is there.
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)
Pushed
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.
Created attachment 5920 [details] [review] Bug 4877 - Add DocBook for missing manual pages Add DocBook manual pages for commands that do not have a manual page yet. Also add a page for koha-common itself, listing all the available commands.
* 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.
Created attachment 6003 [details] [review] Bug 4877 - Add DocBook for missing manual pages Add DocBook manual pages for commands that do not have a manual page yet. Also add a page for koha-common itself, listing all the available commands. Signed-off-by: Robin Sheat <robin@catalyst.net.nz> Minor change: I fixed a typo I spotted
Please remove the patch-sent and signed-off statuses when this is applied, there's still more stuff to do with these.
Updating version : This ENH could be in Koha 3.8
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)
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.
The latest patch here is only signed off and has not been pushed yet. Please don't close until it has been pushed.
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.
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 on attachment 6003 [details] [review] Bug 4877 - Add DocBook for missing manual pages this patch has been pushed
The warning is ok, not exactly sure what causes it, but it doesn't adversely effect anything.
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.
(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.