Description of problem: Few thoughts on.. "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)." First lets support the same syntax as in "Environment" as in multiple entries in the same line secondly I think we should rethink this a bit and split it up as in... ProjectsHome=www.example.com ( refers to upstream ) ProjectsDocs=www.example.com/$docs ( refers to online docs ) File=foo=bar Info=foo=bar Man=foo=bar So instead of having things looking like this in the status output Loaded: loaded Active: inactive Docs: man:test1 man:test2 Main PID: 1148 CGroup: name= We would have this... Project Home: www.example.com Online Documentation: www.example.com/$docs File: foo bar Info: foo bar Man: foo bar Loaded: loaded Active: inactive Main PID: 1148 CGroup: name= Notice how i put the documentation stuffa above Loaded and Active and since we are on the status output topic we probably should also have a field at the end that says Latest Journal Entries ( or Log entries ) instead of that empty line and the latest logs for the service from Journal ) Version-Release number of selected component (if applicable): How reproducible: Steps to Reproduce: 1. 2. 3. Actual results: Expected results: Additional info:
(In reply to comment #0) > First lets support the same syntax as in "Environment" as in multiple > entries in the same line I haven't checked, but doesn't this already work? > secondly I think we should rethink this a bit and > split it up as in... > > ProjectsHome=www.example.com ( refers to upstream ) > ProjectsDocs=www.example.com/$docs ( refers to online docs ) > File=foo=bar > Info=foo=bar > Man=foo=bar The type of documentation is already distinguishable using the URI scheme (man:, info:,...). I don't find the possibility to distinguish between different kinds of http URIs very valuable. > Notice how i put the documentation stuffa above Loaded and Active Hm, yes, this looks like a better ordering. This way the Active state is followed immediately by the process and cgroup information.
(In reply to comment #1) > (In reply to comment #0) > > First lets support the same syntax as in "Environment" as in multiple > > entries in the same line > > I haven't checked, but doesn't this already work? Nope Line like this Documentation=man:test1=man:test2 Results in this Docs: man:test1=man:test2 > > > secondly I think we should rethink this a bit and > > split it up as in... > > > > ProjectsHome=www.example.com ( refers to upstream ) > > ProjectsDocs=www.example.com/$docs ( refers to online docs ) > > File=foo=bar > > Info=foo=bar > > Man=foo=bar > > The type of documentation is already distinguishable using the URI scheme > (man:, info:,...). True but doing it like this result in that you dont have to write and know the uri scheme just the file/info/man page and you could have a separated descriptive line for the output as it did in the sample. As in you might only want to include only the man and the projects home reference but not the file and info ones. Just add several Documentation line and you quickly realize that Docs line in the status output is poorly formatted hence the suggestion for the new layout > I don't find the possibility to distinguish between different kinds of http > URIs very valuable. The reason why I added both ProjectsHome and ProjectsDocs is because downstream distribution might want to point to it's own documentation instead of the upstream one. personally I am not very found of using/allow to be used web based URL since there are several problems with allowing http and https url in general as in they have a tendency to change quite often and be too long and not end in a very descriptive manner like docs.html I think it's best to explain what I'm getting at with an sample. So in the [Unit] section with the proposed layout it would look like this for cross distributable output for the vsftpd service The current method... Documentation=https://security.appspot.com/vsftpd.html # Upstream Documentation=https://security.appspot.com/vsftpd.html#docs # Fedora based URL would be... # Documentation=http://docs.fedoraproject.org/en-US/Fedora/16/html/System_Administrators_Guide/s1-FTP.html Documentation=man:vsftpd Documentation=man:vsftpd.conf Which results in output like this vsftpd.service - Vsftpd ftp daemon Loaded: loaded (/etc/systemd/system/vsftpd.service; disabled) Active: active (running) since Wed, 23 May 2012 11:16:45 +0000; 3s ago Docs: https://security.appspot.com/vsftpd.html https://security.appspot.com/vsftpd.html#docs man:vsftpd man:vsftpd.conf Process: 4468 ExecStart=/usr/sbin/vsftpd /etc/vsftpd/vsftpd.conf (code=exited, status=0/SUCCESS) Main PID: 4469 (vsftpd) CGroup: name=systemd:/system/vsftpd.service └ 4469 /usr/sbin/vsftpd /etc/vsftpd/vsftpd.conf Note that the web URL can be not very descriptive ( it just happens to be in this particular case that vsftp upstream doc url ends in #docs ) ProjectsHome=https://security.appspot.com/vsftpd.html ProjectsDocs=https://security.appspot.com/vsftpd.html#docs Man=vsftpd=vsftpd.conf which would result in this with more descriptive lines for the documentation vsftpd.service - Vsftpd ftp daemon Project Home: https://security.appspot.com/vsftpd.html Online Documentation: https://security.appspot.com/vsftpd.html#docs Man: vsftpd vsftpd.conf Loaded: loaded (/etc/systemd/system/vsftpd.service; disabled) Active: active (running) since Wed, 23 May 2012 11:16:45 +0000; 3s ago Process: 4468 ExecStart=/usr/sbin/vsftpd /etc/vsftpd/vsftpd.conf (code=exited, status=0/SUCCESS) Main PID: 4469 (vsftpd) CGroup: name=systemd:/system/vsftpd.service └ 4469 /usr/sbin/vsftpd /etc/vsftpd/vsftpd.conf Now I'm not sure if you noticed but the good old vsftpd.beasts.org <-- is not being used anymore so the homepage for vsftpd has changed and see how long the url would be if we would point to our own distribution documentation. Two classic nuances of having http and https URL
Weird I somehow ended up setting needinfo on myself
(In reply to comment #0) > Description of problem: > > Few thoughts on.. > > "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)." > > First lets support the same syntax as in "Environment" as in multiple > entries in the same line secondly I think we should rethink this a bit and > split it up as in... You can actually set multiple documentation urls in one setting, separated by spaces: Documentation=man:foo(1) man:bar(7) http://microsoft.com/ man:waldo(5) > ProjectsHome=www.example.com ( refers to upstream ) > ProjectsDocs=www.example.com/$docs ( refers to online docs ) > File=foo=bar > Info=foo=bar > Man=foo=bar The latter three we already have via the standard URI syntax, no? I mean, file://, info: and man: URI prefixes already implement that. Yes, we thought about adding Homepage= and Vendor= or so settings, but since there is no immediate use of that and we could get into an inflation of this kind of meta settings I am trying to be conservative in adding them. > So instead of having things looking like this in the status output > > Loaded: loaded > Active: inactive > Docs: man:test1 > man:test2 > Main PID: 1148 > CGroup: name= > > We would have this... > > Project Home: www.example.com > Online Documentation: www.example.com/$docs > File: foo bar > Info: foo bar > Man: foo bar > Loaded: loaded > Active: inactive > Main PID: 1148 > CGroup: name= So the big benefit of the URI syntax is that the terminal can detect this and make it clickable. In fact I filed a couple of bugs to make sure that GNOME terminal can decode man URIs. This is really nice then, since you can just invoke systemctl status and click on the URLs printed to get to the documentation for it. Reformatting the URLs into individual fields would really make this impossible, hence I am strongly for taking and printing URLs in favour of any other format.
(In reply to comment #2) > (In reply to comment #1) > > (In reply to comment #0) > > > First lets support the same syntax as in "Environment" as in multiple > > > entries in the same line > > > > I haven't checked, but doesn't this already work? > > Nope > > Line like this > Documentation=man:test1=man:test2 > Results in this > Docs: man:test1=man:test2 Hmm? Why the "="? Use spaces to separate the URIs. > > I don't find the possibility to distinguish between different kinds of http > > URIs very valuable. > > The reason why I added both ProjectsHome and ProjectsDocs is because > downstream distribution might want to point to it's own documentation > instead of the upstream one. I think downstream distros should patch the unit files as part of the packaging process overriding if they want to redirect these things.
(In reply to comment #4) > (In reply to comment #0) > > Description of problem: > > You can actually set multiple documentation urls in one setting, separated > by spaces: > > Documentation=man:foo(1) man:bar(7) http://microsoft.com/ man:waldo(5) Did not know that... > > > ProjectsHome=www.example.com ( refers to upstream ) > > ProjectsDocs=www.example.com/$docs ( refers to online docs ) > > File=foo=bar > > Info=foo=bar > > Man=foo=bar > > The latter three we already have via the standard URI syntax, no? I mean, > file://, info: and man: URI prefixes already implement that. > > Yes, we thought about adding Homepage= and Vendor= or so settings, but since > there is no immediate use of that and we could get into an inflation of this > kind of meta settings I am trying to be conservative in adding them. > > > So instead of having things looking like this in the status output > > > > Loaded: loaded > > Active: inactive > > Docs: man:test1 > > man:test2 > > Main PID: 1148 > > CGroup: name= > > > > We would have this... > > > > Project Home: www.example.com > > Online Documentation: www.example.com/$docs > > File: foo bar > > Info: foo bar > > Man: foo bar > > Loaded: loaded > > Active: inactive > > Main PID: 1148 > > CGroup: name= > > So the big benefit of the URI syntax is that the terminal can detect this > and make it clickable. In fact I filed a couple of bugs to make sure that > GNOME terminal can decode man URIs. This is really nice then, since you can > just invoke systemctl status and click on the URLs printed to get to the > documentation for it. Reformatting the URLs into individual fields would > really make this impossible, hence I am strongly for taking and printing > URLs in favour of any other format. I'm more thinking about how we display this to the end user for easy readability while not having this information clutter what values the most to administrator so to keep the best of both worlds is there something preventing us keeping the URI syntax and the proposed status output and drop the proposed online documentation field since it should be sufficient enough to point to the upstream web url as in Project Home: www.example.com File: file:foo Info: info:bar Man: man:foo(1) man:bar(7) Basically we would keep the "Documentation=" as is but filter it based on the URI syntax into their own line in the status output as http:// and https:// would go in the Project Home:, file: into File:, info: to Info: and man: to Man: I think it's better for readability than stuffing everything under in the order they are put into the Documentation= as in Docs: foo bar zeta I also think we should put information underneath the Description field and above Loaded: in the status output rather than having this beneath Active:
To have an reference sample let's convert systemd-hostnamed.service to the proposed output. The three existing Documentation fields would be put into one for simplicity sake Documentation=http://www.freedesktop.org/wiki/Software/systemd man:hostname(5) man:machine-info(5) and the status output would go from this... systemd-hostnamed.service - Hostname Service Loaded: loaded (/usr/lib/systemd/system/systemd-hostnamed.service; static) Active: inactive (dead) Docs: man:hostname(5) man:machine-info(5) http://www.freedesktop.org/wiki/Software/systemd CGroup: name=systemd:/system/systemd-hostnamed.service To this... systemd-hostnamed.service - Hostname Service Project Home: http://www.freedesktop.org/wiki/Software/systemd Man: man:hostname(5) man:machine-info(5) Loaded: loaded (/usr/lib/systemd/system/systemd-hostnamed.service; static) Active: inactive (dead) CGroup: name=systemd:/system/systemd-hostnamed.service And probably for all none systemd upstream shipped units we would automatically add all the default man pages that required to modify units to the Man: field so that administrator would have all the man pages relevant to their daemon along with all the man pages relevant to modify an existing unit displayed to them.
Man: man:foo(5) is a little redundant - if we're having a separate 'Man:' entry, perhaps: Man: hostname(5) machine-info(5) or perhaps: Manual: ...
(In reply to comment #8) > Man: man:foo(5) is a little redundant - if we're having a separate 'Man:' > entry, > perhaps: > > Man: hostname(5) machine-info(5) We have to keep the uri syntax hence man:foo(5) so that the terminal can detect this and make it click-able > > or perhaps: > > Manual: ... Manual: man:foo(5) might work Got anything better for Info and File so they don't turn out to be redundant as well?
Aside from the snarky comment that "no one reads info files", not really. I guess I don't really trust the dingus support in the terminal to work right.
I would think man pages and it's uri syntax would suffice and a link to the project website to find and read on any further documentation. Failures of daemons and related error code should probably be handled with "HINT" section in Journal logging. So I personally dont think we should bother with supporting "file" and "info" at least I dont see the benefits of doing so.
So can we sort out if the middle ground proposed in comment 7 is doable so I can start making the "feature" page for this and start updating existing units ( Goes without saying I will add this to any unit I migrate during the F18 development cycle )?
Are you referring to... > The three existing Documentation fields would be put into one for > simplicity sake ? It does not matter if they're on separate lines or all on one line. Both ways are interpreted the same. Unit file writers can choose one style or the other. As for the presentation of the fields in the output of systemctl status... We can improve it along the lines you suggested (though I don't like the assumption that a http link is "Project Home"), but that we can do at any time. There's no need to put the adding of Documentation= fields to units on hold for that.
(In reply to comment #13) > Are you referring to... > > The three existing Documentation fields would be put into one for > > simplicity sake > ? > > It does not matter if they're on separate lines or all on one line. Both > ways are interpreted the same. Unit file writers can choose one style or the > other. Yes I know that's how they are in the native systemd units I just "merged" it into on line in the example well to simplify it. From my perspective we should keep all upstream units as lean as possible because people look at units also as an example how do things and if we start to bloat units with license text/comments + split things into multiple lines instead of keeping them compact in a single line as in having two Before=, three After=, four Documentation=, etc we gradually are growing the units to the size of what legacy sysv are and in the end have lost one of systemd selling points simplicity. > > As for the presentation of the fields in the output of systemctl status... > We can improve it along the lines you suggested (though I don't like the > assumption that a http link is "Project Home"), but that we can do at any > time. There's no need to put the adding of Documentation= fields to units on > hold for that. Pointing http and https url to something other then strictly the projects fqdn makes no sense ( to me at least ) but i'm interested in knowing what benefits you guys think it might bring. We ofcourse could call it something other than "Project's Home". There is one thing I mentioned as in that we should automatically add to all non strictly systemd related units, the man pages relevant to modifying a unit. I could manually add those but that would mean that we would have to mass change unit files each time if we would like to present a new systemd man page to administrators something I personally want to try to avoid.
Created that Feature page [1] which includes these unit changes amongst few other we should be doing. Feel free to add yourself to that page if you have the time and the will to help out. 1.https://fedoraproject.org/wiki/Features/Systemd-unit-cleanup
Hmm, so what is precisely requested in this RFE now? As I understand #7 only that we should replace "Docs:" by "Manuals:", "Info:", "Project Home" in the pretty "systemctl status" output? Regarding "Project Home" I'd side with Michal here: we should keep this generic, and the way you get to a doc should not imply that it's purpose is that of being the project homepage. Quite a few units in systemd actually refer to web sites with further documentation. For example, logind points to the multi-seat wiki pages and stuff like that, and it is good that way, but that wiki page is definitely not the "project home". Regarding the general idea of using different field names for the rest of the docs: Currently, the idea is that documentation is ordered by relevance in the unit file: the most relevant documentation is mentioned first, broadly related documentation more at the end of the list. If we'd split things up on display and show a "Manuals:" field before "Info:", before "Web:" then suddenly the way to access documentation decides the order in which we display it, which I think is suboptimal. In addition, the information would be kinda redundant, since the URL scheme would already include the "man:", "info:", and suchlike, so we probably shouldn't mention that a second time. So I fail to see what the big benefit would be. I think the way how documentation is accessed should really be secondary, and primarily an choice of tools of the documenter, it should not be exposed to the admin more than it is done already via the URI scheme. So, I guess I am against changing anything here. Closing this now. Feel free to reopen if I missed anything.
You missed the ordering of things in the status output. Docs should be beneath the first line to not clutter the output and you could introduce Project's home since it's really beneficial to administrators to know the relevant upstream url systemd-logind.service - Login Service Docs: man:systemd-logind.service(7) man:systemd-logind.conf(5) http://www.freedesktop.org/wiki/Software /systemd/multiseat Loaded: loaded (/usr/lib/systemd/system/systemd-logind.service; static) Active: active (running) since Mon, 29 Oct 2012 17:42:24 +0000; 1 d Main PID: 416 (systemd-logind) CGroup: name=systemd:/system/systemd-logind.service └ 416 /usr/lib/systemd/systemd-logind With project home... systemd-hostnamed.service - Hostname Service Project Home: http://www.freedesktop.org/wiki/Software/systemd Docs: man:hostname(5) man:machine-info(5) .....
Hmm, so what is this bug about now? You want Docs= move up a bit in the output? And you want ProjectHome= as new field in addition to Documentation=? Anything else?
I would propose the following: Documentation[<what>]=.... Documentation[Project Home]=https://security.appspot.com/vsftpd.html Documentation[Upstream]=https://security.appspot.com/vsftpd.html#docs Documentation[Fedora Guide]=http://docs.fedoraproject.org/en-US/Fedora/16/html/System_Administrators_Guide/s1-FTP.html Documentation[Execution]=man:vsftpd Documentation[Configuration]=man:vsftpd.conf or, if you don't want to screw with the ini-file parser: Documentation=[Project Home]https://security.appspot.com/vsftpd.html Documentation=[Upstream]https://security.appspot.com/vsftpd.html#docs Documentation=[Fedora Guide]http://docs.fedoraproject.org/en-US/Fedora/16/html/System_Administrators_Guide/s1-FTP.html Documentation=[Execution]man:vsftpd Documentation=[Configuration]man:vsftpd.conf with an output: vsftpd.service - Vsftpd ftp daemon Loaded: loaded (/usr/lib/systemd/system/vsftpd.service; enabled) Active: inactive (dead) Docs: Project Home: https://security.appspot.com/vsftpd.html Upstream: https://security.appspot.com/vsftpd.html#docs Fedora Guide: http://docs.fedoraproject.org/en-US/Fedora/16/html/System_Administrators_Guide/s1-FTP.html Execution: man:vsftpd Configuration: man:vsftpd.conf
Given that the Red Hat bugzilla administrators aren't competent enough to exclude RFE's from their processes and have started to spam me with this bug as well as the fact it is 511 days old and arguably too late to change at this point closing... I argue against adding any distribution spesific documentation path as Harald suggest with "Fedora Guide" as well as project home and upstream should be one and the same from my point of view. It's a fact that one of the side effects of unification of the core/baseOS layer in the long run is that distribution will stop producing local documentation and do that work in a centrally maintained location either directly upstream for each given component or under some distribution agnostic domain for all components. Once that bridge has been crossed in the unification, unit files should support and point to either of those documentation location.