Bug 824344 - RFE: some improvements to Documentation=
RFE: some improvements to Documentation=
Status: CLOSED NOTABUG
Product: Fedora
Classification: Fedora
Component: systemd (Show other bugs)
rawhide
Unspecified Unspecified
unspecified Severity unspecified
: ---
: ---
Assigned To: systemd-maint
Fedora Extras Quality Assurance
: Reopened
Depends On:
Blocks: systemd-RFE
  Show dependency treegraph
 
Reported: 2012-05-23 06:16 EDT by Jóhann B. Guðmundsson
Modified: 2014-06-10 05:20 EDT (History)
8 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2014-06-10 05:20:12 EDT
Type: Bug
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)

  None (edit)
Description Jóhann B. Guðmundsson 2012-05-23 06:16:33 EDT
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:
Comment 1 Michal Schmidt 2012-05-23 06:30:21 EDT
(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.
Comment 2 Jóhann B. Guðmundsson 2012-05-23 07:54:44 EDT
(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
Comment 3 Jóhann B. Guðmundsson 2012-05-23 08:07:29 EDT
Weird I somehow ended up setting needinfo on myself
Comment 4 Lennart Poettering 2012-05-23 08:14:40 EDT
(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.
Comment 5 Lennart Poettering 2012-05-23 08:18:26 EDT
(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.
Comment 6 Jóhann B. Guðmundsson 2012-05-23 08:58:44 EDT
(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:
Comment 7 Jóhann B. Guðmundsson 2012-05-23 09:11:42 EDT
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.
Comment 8 Bill Nottingham 2012-05-23 10:07:34 EDT
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: ...
Comment 9 Jóhann B. Guðmundsson 2012-05-23 10:21:39 EDT
(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?
Comment 10 Bill Nottingham 2012-05-23 12:15:23 EDT
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.
Comment 11 Jóhann B. Guðmundsson 2012-05-23 13:09:47 EDT
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.
Comment 12 Jóhann B. Guðmundsson 2012-05-29 15:33:06 EDT
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 )?
Comment 13 Michal Schmidt 2012-05-30 02:49:20 EDT
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.
Comment 14 Jóhann B. Guðmundsson 2012-05-30 03:53:08 EDT
(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.
Comment 15 Jóhann B. Guðmundsson 2012-06-05 16:14:16 EDT
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
Comment 16 Lennart Poettering 2012-10-30 17:35:38 EDT
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.
Comment 17 Jóhann B. Guðmundsson 2012-10-30 19:26:08 EDT
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)
 .....
Comment 18 Lennart Poettering 2013-01-14 15:51:00 EST
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?
Comment 19 Harald Hoyer 2013-04-10 06:05:24 EDT
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
Comment 20 Jóhann B. Guðmundsson 2014-06-10 05:20:12 EDT
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.

Note You need to log in before you can comment on or make changes to this bug.