[systemd-devel] [PATCH] systemctl: Implement "info" and "doc" commands, similar to "man"

[Gergely Nagy]

Lennart Poettering <lennart at poettering.net> writes:

>> Nevertheless, I was thinking that 3 different commands to display docs
>> might be a bit too much. Perhaps it could be condensed into a single
>> "doc" command, with --info, --man and --http or similar flags to select
>> what kind of documentation to display? (And by default, will prefer http
>> over info over man)
>> 
>> I can probably cook that up in a lunch break or so, but would rather
>> have other opinions before I do that, to see if it's worth the effort.
>
> Yes, I definitely would like to have one command only for this. I
> intended this to be "systemctl man" even though it admittedly might be a
> bit misleading in that it also starts info pages.

A'ight, I'll post an update later (time permitting) that pulls it all
together into a single command (I'd prefer 'doc' or 'docs').

> I am not convinced we should try doing this for http/https
> though. Firstly, all terminal programs recognize these kinds of URLs,
> so it's probably easier to just have people click on them, and have
> the right thing happen?

Most do, yes. I hate clicking, though, so I'd much prefer a command to
open it for me. It's far easier for me to type systemctl doc --html
blah.service than systemctl status blah.service and then click the
appropriate link.

> So I'd claim that man pages you actually want to read on the
> host that you are inspecting while web sites you want to browse on the
> client machine you are logging in from.

True enough. The http-opening thingy would be most useful when used
locally (or when no other documentation exists [eg, the man page is so
poor it's not worth listing in Documentation=, and it'd be too much
effort to write a proper man page]).

> Or in other words: if I log in
> remotely I don't want to end up with lynx in the ssh window to read
> documentation, and I'd be annoyed if that happens just because I tried
> to find the man page for a service.

That's fair enough, if you want the manpage. I'm often happy with lynx
too, but I suppose that if I manage to convince you that supporting
http(s) is worth it, then it'd prefer man and info over online docs.

> Thirdly, the semantics of xdg-open
> really are too losely defined: is it synchronous or is it async? We'd
> want synchronous operation here (i.e. wait until the user closed the
> documentation before we show the next page), but it tends to be async
> (i.e. the script just tells the running firefox to open the new page and
> immediately returns) -- and that for a reason: sync behaviour would be
> kinda broken with modern browsers. Summary: I myself would be really
> annoyed if "systemctl man" would try to open web sites, regardless if
> locally on the client or remote on the SSH host. So I'd just skip
> http/https handling in "systemctl man". People can just click on the
> links in "systemctl status" and more likely the right thing happens.

...actually, while I hate clicking, I can always add a small shell
script that wraps systemctl status $foo, and opens the http doc for
me. So nevermind all of the above!

> I am happy to add info support to "systemctl man" though, as that this
> really is the same thing mostly as man pages.

I'll prepare a patch that supports info too. Should it prefer man over
info, or the other way around? Or open both in turn? Or make it
selectable (while still preferring one over the other)?

Also, should it support stuff like:

 Documentation=info:blah#section name

Or only info:blah ?

> I'd be open to rename "systemctl man" to "systemctl doc" too, if people
> want this, if we make it cover both man and info. Not sure I like "doc"
> too much though. Maybe we can find another name? Suggestions? The reason
> I picked "man" in the first place is that it is kinda an obvious choice
> and man is much more ubiquititous than info.

unit-doc comes to mind..

"doc" in itself is too generic, and man opening info pages feels a bit
weird.

-- 
|8]