search

kdave / btrfsmaintenance

Scripts for btrfs maintenance tasks like periodic scrub, balance, trim or defrag on selected mountpoints or directories.
GNU General Public License v2.0
897 stars 79 forks source link

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

Closed sten0 closed 2 years ago

sten0 commented 4 years ago

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

kdave commented 4 years ago

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

sten0 commented 4 years ago

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

sten0 commented 3 years ago

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 commented 2 years ago

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.

kdave commented 2 years ago

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.