doc: something about vanished /etc/inittab should be added

Here's a patch to add an initctl man page saying that it is deprecated and has been replaced with the event.d directory. It points the reader to the getting started document on the Upstart website.

Suggested changelog entry:
 * util/man/inittab.5: new inittab man page mentioning that inittab has been replaced with /etc/event.d
 * util/Makefile.am (dist_man_MANS): added inittab.5

Oops, forgot to add the patch

i was just about to submit a similar bug, so i'll just augment this one. given that upstart is now completely central to the operation of the system, the documentation really needs to be more complete.

in particular:

* in addition to the above inittab(5) man page (which is not for "initctl", as its name implies :-), both it and the existing init(8) stub should also point at /usr/share/docs/README.debian (or perhaps the same content under a different name -- one that doesn't need decompressing in order to read it).

* there should be an upstart(8) man page, which fully documents the format
of the event.d entries. i couldn't find a definitive document on the system or on the wiki (and it should be on the system).

* initctl(8) needs to fully explain the output of "initctl list"

Heh, oops. I didn't mean to call the patch initctl.5, the actual patch doesn't touch that file ;)

Rejecting the upstream task of this bug, since I do not believe the upstream Upstart source code needs to document configuration files of other init systems.

The Ubuntu task remains, because Ubuntu should document the change better.

I disagree with the statement made by ``Scott James Remnant`` in comment 5.
Let me explain why: The /etc/inittab approach is very widely used on all Unices:
The traditional init system is practically the only one, that has been used.
As I understand the upstart project has goal to replace init on Linux.
To get acceptance by other vendors the project should try to
make the move to upstart as painless as possible. This not only applies
to Ubuntu but also to Debian. I strongly suggest to add a stub
/etc/inittab file to the upstart package containing comments
pointing to documentation.

You're right, upstart-compat-sysv should at least include something saying that inittab isn't used; since that's for compatibility with original sysv

Bug moved to Upstream

or just support inittab (maybe)

This has been fixed in Upstart 0.6.0.

0.6.0 2009-07-09 "How appropriate, you fight like a cow"

 * The licence for Upstart has been changed back to version 2 of the
   GNU GPL.

 * D-Bus 1.2.15 is now required, this is the current GIT HEAD
   pending a 1.2.16 release.

 * Configuration paths have changed. Global configuration now
   resides in "/etc/init.conf" while jobs are now configured in
   "/etc/init"

 * Job configuration filenames must now end in ".conf"

 * Default configuration files are now supplied in the "conf"
   sub-directory of the source, and installed into "/etc/init".

   These match the Debian/Ubuntu sysvinit configuration so may
   require some tweaking for other distributions, but provide an
   excellent base.

   The old example-jobs tarballs are deprecated.

 * The D-Bus interface remains unstable, to reflect this the current
   interface name has changed to "com.ubuntu.Upstart0_6" and the
   name of the job and instance interfaces have changed to match.

 * The "EmitEvent" D-Bus method gains a wait argument, when given
   as TRUE (the recommended setting) the method call will be blocked
   until all effects of the event have finished. When FALSE the
   method call will return once the event has been queued.

 * The "Start", "Stop" and "Restart" D-Bus methods of jobs and
   instances gain a similar wait argument.

 * The Upstart D-Bus object now has "version" and "log_priority"
   properties. The former is to obtain the version of the init daemon,
   the latter allows you to obtain and change the logging priority.

 * Job D-Bus objects now have "name", "description", "author" and
   "version" properties to obtain the job name and the contents of
   the equivalent job file fields for the others.

 * Instance D-Bus objects now have "name", "goal", "state" and
   "processes" properties to obtain the instance name, goal, state
   and list of running processes and their pids respectively.

 * The default D-Bus security policy now permits use of the "Get"
   methods by all users, including obtaining values of properties.

 * initctl has been rewritten with functionality more along the
   lines of Upstart 0.3.x than before; since many distributions are
   still shipping 0.3.x the summary of changes for the tool reflects
   both changes from 0.3.x and 0.5.x

 * The global "-p"/"--pid" argument has been dropped, since
   communication is over D-Bus. New "--system" and "--dest" arguments
   have been added to force communication over the system bus, and
   specify the destination, instead of using the private socket (this
   is the default when run as non-root to permit "list" and "status"
   to work for ordinary users).

 * The "-i"/"--id" and "--show-ids" options to commands have been
   dropped since jobs no longer have ids.

 * Since instances may now have names, these will be displayed in
   brackets after the job name when one is present. The output of
   the goal and state are now expressed as "start/running" instead
   of "(start) running" to disambiguate.

 * initctl "start" and "stop" now only output the final state of
   the job, not inte...

This bug was fixed in the package upstart - 0.6.0-1

---------------
upstart (0.6.0-1) karmic; urgency=low

  * New upstream release ("How appropriate, you fight like a cow")
    - my customary changes list since pointless, it's basically a
      complete rewrite.
    - Handles /bin/sh symlink disappearing. LP: #65024.
    - Boot parameters may be passed to init scripts. LP: #74664.
    - reboot implies --force during shutdown. LP: #388738.
    - reboot no longer iterates /proc/ide. LP: #92685.
    - much improved documentation. LP: #60429, #72058, #388715.

  * Merge the various upstart packages into a single package, it makes
    little sense to have it all spread out.

 -- Scott James Remnant <email address hidden> Wed, 08 Jul 2009 23:12:03 +0100