doc: better define job, service & task

[Ian]

Binary package hint: upstart

Description: Ubuntu 9.10
Release: 9.10

man 5 init says:

       Each file defines a single service or task, with the name taken from
       its relative path within the directory without the extension. For
       example a job defined in /etc/init/rc-sysinit.conf is named rc-sysinit,
       while a job defined in /etc/init/net/apache.conf is named net/apache.

It is, perhaps, a small point, but I wonder whether "service", "task" and "job" are three terms for the same thing or whether they are three different things, somehow all related to the the files in the /etc/init directory in ways yet to be defined. If they are all the same it would be helpful to say so, then choose one term and use it consistently. If they are different things and important enough to bring up in the third paragraph of the description, then they should be better defined and distinguished.

I would offer a rewrite, but I don't know what is correct. I find the following, taken from http://upstart.ubuntu.com/getting-started.html to be clearer:

        Jobs are defined in files placed in /etc/init, the name of the job is the
        filename under this directory without the .conf extension.

But I suspect it would be as correct and less ambiguous to say:

        Jobs are defined by files in /etc/init. Each file defines a single job.
        The name of the job is the filename under this directory without
        the .conf extension.

Cheers,
Ian

[Ian (ian-goodacre)]

Putting the last and first examples together with a guess, maybe the paragraph would be better if it were changed to:

        Each file defines a single job. The name of the job is the filename under
        this directory without the .conf extension. For example a job defined in
        /etc/init/rc-sysinit.conf is named rc-sysinit, while a job defined in
        /etc/init/net/apache.conf is named net/apache. The terms service and
        task are also used. These are synonyms for job.

[Ian (ian-goodacre)]

A little further along, one finds:

       The primary use of jobs is to define services or tasks to be run by the
       init(8) daemon. Each job may have one or more different processes run
       as part of its lifecycle, with the most common known as the main
       process.

There is similar confusion here. Why introduce the primary use of jobs as the
definition of services or tasks, then continue to describe how jobs have one
or more processes, leaving one wondering and completely uninformed as to
how the jobs achieve their primary purpose. The section continues to describe
how the processes are defined in a coherent way.

It would be better to remove the first sentence of the first paragraph in the
Process Definition section. It is distracting, seemingly irrelevant to the section
and adds no value to the presentation of the topic.

If the primary purpose of a job is to define services or tasks, then a section
dedicated to this primary purpose, including a description of what services
and tasks are, and how they relate to jobs, beyond being defined by them,
would be quite appropriate, and this section should probably precede the
sections giving details of file format and process definition - it is the primary
purpose, after all.

[Clint Byrum (clint-fewbar)]

Adding upstream task as this man page is part of upstart upstream. Setting status in Ubuntu to Triaged as this has been forwarded upstream. Setting Importance to Low as it is a minor documentation clarification.