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

Question

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

sten0 opened this issue 4 years ago · comments

Nicholas D Steeves commented 4 years ago

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

kdave · Answer 1 · Tue Aug 11 2020 14:40:38 GMT+0800 (China Standard Time)

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

Nicholas D Steeves · Answer 2 · Fri Aug 14 2020 20:44:44 GMT+0800 (China Standard Time)

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

Nicholas D Steeves · Answer 3 · Sat Jun 19 2021 09:19:17 GMT+0800 (China Standard Time)

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

Nicholas D Steeves · Answer 4 · Mon Nov 15 2021 14:58:21 GMT+0800 (China Standard Time)

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 · Answer 5 · Tue Nov 30 2021 03:10:39 GMT+0800 (China Standard Time)

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.