Provide man pages for commands
ieugen opened this issue · comments
A lot of Unix distrubutions reccommend (need) man pages for commands. Debian is one of them.
The man page format is not very friendly to write but there are tools to convert from friendlier formats to man page.
One of these is asciidoc. It has a man page mode that can create man pages. It can also create html pages from those documents and Github supports asciidoc.
My recommendation is to split the README.md into one asciidoc file per command and link them back.
Since a2x command is available on most distributions this should be ok.
[1] http://www.methods.co.nz/asciidoc/chunked/ch24.html
[2] http://www.methods.co.nz/asciidoc/asciidoc.1.txt
Asciidoc is ok. I'm not sure how do you want to do the split. The readme could contain the overall info, and eg. a btrfsmaintenance page the configuration and tuning.
I'm considering using markdown as source instead of asciidoc. There are converters md->man (one in ruby gh://sunaku/md2man, one in go go-md2man).
At first, I found another md2man converter implemented in ruby: https://rtomayko.github.io/ronn/
What do you, kdave, think should be the procedure of writing manpages and converting them?
- Having a markdown source and a converted manpage in the repository?
Or 2. only a markdown source and conversion should be done during package building?
The latter has disadvantages for distributions where every user build packages on its own (Gentoo and derivates) - that creates the dependency of installing a large converter just to build the small btrfsmaintenance package.
So I would prefer 1.
Option 1 sounds better.
Actually, what's the reason to provide manual pages? This tool does not provide any commands, installed in bin directories. A md2man transformation of README.md is ok, but I don't understand the point about the commands.
The manpages are required for distributing the sofware in Debian or other distributions. They require man pages.
But for what exacly? The only script installed into sbin is rcbtrfsmaintenance-refresh, that would be one. Then a manual page for 'btrfsmaintenance' somewhere in category 5. What else? Not the individual scripts, that wouldn't make any sense to me.
It's just a policy. You need to have a man page for a system command that explains what the command does and how to use it. Otherwise, you expect people to just know about it and that does not happen.
The end goal is to make the sowftware usable by other people.
You need to have a man page for a system command that explains what the command does and how to use it.
So I'm asking about a list of the system commands.
Why are those scripts not geared as system commands in the first place? I could have btrfs filesystems on removable devices that are never connected when cron runs, so there should be an official way to run those scripts manually from a shell.
Hi,
Lintian is the Debian QA tool that would warn if it was an issue that a manpage was missing for a binary. Here is the relevant output v2.5.54 (current version):
I: btrfsmaintenance: systemd-service-file-missing-documentation-key lib/systemd/system/btrfsmaintenance-refresh.service
W: btrfsmaintenance: script-not-executable usr/share/btrfsmaintenance/btrfsmaintenance-functions
If a missing man page was an issue it would have issued multiple:
W: btrfsmaintenance: binary-without-manpage path/of/binary
Script-not-executable needs to be overridden in Debian packaging, because it is a false alarm. Alternatively, btrfsmaintenance might be modifiable so the #!/bin/bash line can be dropped from btrfsmaintenance-functions.
Systemd-service-file-missing-documentation-key can be fixed easily enough. I was happy to see that #36 has them; although, I think that it would be better if they pointed to a specific section of a btrfsmaintenance man/info page. If you want to reference a manpage, I personally think that a single "man:btrfsmaintenance" in btrfsmaintenance-refresh.service would be fine. That man page would document how the components fit together, how the software is non-interactive, and how any interaction is meant to happen through the config file and systemd unit[s]. eg: that it's not designed to be run against arbitrary paths or removable devices. Personally I think such a collection of general-purpose convenience scripts should be part of a "btrfs-progs-extras" package rather than btrfsmaintenance, which I believe is designed to be a "configure once and then forget about it" solution. I'm not sure if manpages can have links like info pages do, but whatever the method, I think that users can be referred to btrfs-progs documentation for further reading.
https://lintian.debian.org/tags/systemd-service-file-missing-documentation-key.html
I recently had the pleasure of writing a man page in rst (ReStructuredText); this was very easy and the format is elegant. The most surprising thing was how much white space (new lines) the format requires. Rst2man is part of docutils ( docutils.sourceforge.net ) and has both python2 and python3 variants. Whatever the format, Debian packages must always generate documentation from source, whenever source is available.
I just used sed, go-md2man, and a minor shell script to generates a btrfsmaintenance.8 (section for various sysadmin stuff) from README.md, and uploaded this in Debian's 0.5-2 btrfsmaintenance package, thus @ieugen's issue is solved. @kdave, I did this because upstream systemd exclusively supports man pages in the Documentation key for services, and it seems that this is becoming the default first-contact point of documentation for new sysadmins--thus worth supporting.
Thanks.
I will close the issue then.
I'm not using btrfs lately but following it.