[wishlist] Please add documentation key to btrfsmaintenance-refresh.service

[sten0]

btrfsmaintenance-refresh.service is missing a documentation key. Please consider adding one.

[kdave]

What do you mean documentation key? The purpose of the refresh service is documented in the README.

[sten0]

Hi,

On Tue, 11 Aug 2020 at 02:40, kdave ***@***.***> wrote: What do you mean documentation key? The purpose of the refresh service is documented in the README.

Documentation for systemd service files can be viewed using `systemctl help servicename` if this field is present. From SYSTEMD.UNIT(5): ``` Documentation= A space-separated list of URIs referencing documentation for this unit or its configuration. Accepted are only URIs of the types "http://", "https://", "file:", "info:", "man:". For more information about the syntax of these URIs, see uri(7). The URIs should be listed in order of relevance, starting with the most relevant. It is a good idea to first reference documentation that explains what the unit's purpose is, followed by how it is configured, followed by any other related documentation. This option may be specified more than once, in which case the specified list of URIs is merged. If the empty string is assigned to this option, the list is reset and all prior assignments will have no effect. ``` I attempted to use "file:/path/to/README.md", but it appears systemd 241 has broken "file:" URI support. That said, I've confirmed "man:page_name(section)" works correctly. How do you feel about making modifications to README.md to make it a more suitable source for man page export? With this we could ship a man page for btrfsmaintance, and it would allow `systemctl help servicename` to function correctly on older SLED systems. IIRC the modifications are limited to metadata/pseudoheader hints for title, section, and group, plus a couple of restrictions on the use of more esoteric/advanced/pretty-html-output markdown grammar. Given that veteran admins use man, and newer ones may use "systemctl help" it seems like a good thing all-around :-) Thanks, Nicholas

[sten0]

Oh, and I've received confirmation that users/sysadmins actually use this feature. Unfortunately that confirmation was an Ubuntu bug that was my fault because I added my patch without adjusting it to use Debian/Ubuntu /etc/default. Yes, facepalm! Lesson learned :-) https://bugs.launchpad.net/ubuntu/+source/btrfsmaintenance/+bug/1918000

[sten0]

Hi @kdave, Sorry for the unreasonably long delay--I missed your commit
3641063 during holidays. It was a good idea to apply it to the devel branch, because it seems like systemd upstream (and Debian, and derivatives like Ubuntu) don't have support for anything but man page docs yet...despite what freedesktop.org maintains. I wonder if SUSE has a patched version? At any rate, I opened this upstream issue: systemd/systemd#21369

If rejected, the only workaround that I can think of is generating a man page from README.md.

[kdave]

No, systemctl help behaves the same. Reading just the documentation of Documentation in systemd.unit does not hint that the files are not displayed, that confused me too, though systemctl help says it opens only manual pages. Right now it will print "Can't show file: ...", it's not friendly but at least something.

Tools to generate manual page from markdown exist, go-md2man produces some weird artifacts but it could be fixed. I'll add it to git and replace the links for the Documentation.