Closed sten0 closed 2 years ago
What do you mean documentation key? The purpose of the refresh service is documented in the README.
Hi,
On Tue, 11 Aug 2020 at 02:40, kdave notifications@github.com 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
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
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: https://github.com/systemd/systemd/issues/21369
If rejected, the only workaround that I can think of is generating a man page from README.md.
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.
btrfsmaintenance-refresh.service is missing a documentation key. Please consider adding one.