seeking "Brick #1" on the Upstart yellow-brick-road

[Saint DanBert]

Folks,
   I really REALLY want to help with upstart documentation, but I'm dashed if I
can find the first brick on the yellow-brick-road. I feel sure that somewhere in
the alphabetical list of details volume-G there is a "Getting Started" page and
that I'm too much of a noob to see it or find it.

Let me lay out some details.

1. I have a tablet-pc laptop running Ubuntu Karmic v9.10
2. I want to understand how it boots, what it boots, and how it runs.
3. In days of very olde, I could start reading in /etc/init.d and /etc/rc*.d and
eventually map out most of what is happening.
4. Today, things are different:

** man init tells me about 'upstart' and /etc/init.conf and /etc/init/*.conf
** man upstart and man 7 upstart takes me to the same page. Neither page tells
me in direct language that the upstart implementation of 'init' provides a new
program to replace the System-V 'init' with the same name.
** SURPRISE!! attempts to man init.conf say "noting found"
** DOUBLE SURPRISE!!  attempts to  less /etc/init.conf say "no such file"
** TRIPLE SURPRISE!!  attempts to locate init.conf   dutifully finds
rc-sysinit.conf from the upstart tar-ball. Otherwise, "no such file".
Is this an error in the man page or is my installation missing files?
How would I know? Where do I go to find out?  [grin -- I'm writing this.]
** what do I find in /etc/init/*.conf -- again, nothing named 'init.conf'
By The Way, there is nothing called README or similar either.

So I fetched the upstart-0.6.3 tar ball from http://upstart.ubuntu.com/. In
viewing various README and accompanying text files, I find lots of build and job
and task details but almost nothing about HOW DOES IT WORK...?...?...?...?...?

Some thoughts, but I'd really like to find the un-garbled and un-varnished word.
(Yes, I can mostly read the code, but is that my only choice?)

A.  I create some files on disk in the required places
Q1 -- what are those places?
Q2 -- what configuration detail(s) identify which files and which places?
Q3 -- where are these configuration detail(s)

B. Power on ... la, la, GRUB2, la,  la ... 'init' runs and it is the upstart
edition because that is the binary found through the boot loader processing.
Q4 -- are there parameters to the upstart edition of init at the command line?
Q5a -- specifically, are there logging or debug or event-trace options ?
Q5b -- how do I enable any logging or debug or event-trace options ?
(You don't learn anything from 'man init'.)

C. The upstart "pin ball wizard" begins to dance in response to events
Q6 -- some events are hardware and driver specific, right?
Q7 -- some events come from the kernel, right?
Q8 -- some events come from other events, right?
Q9 -- Having stated the obvious, how do I know which of these are (a) possible,
and (b) happening on my specific hardware and kernel?
Q10a -- where is configuration of the origins for this flood of events?
(If I understand, it is /etc/init/*.conf that configures what happens in
response or reaction to any given event, right?)
Q10b -- if a driver/module throws events for upstart, is there coordination so
that driver events don't interfere among themselves?
Q10c -- can I create or define my own driver level events or is there some sort
of "clearing house"?
Q10d -- repeat 10b and 10c for kernel internel events
Q10e -- repeat 10b and 10c for any other event creators

D. One upstart response causes ACPI and UDEV and HAL(deprecated?) and friends to
begin their own dances.
Q11 -- One pin-ball machine launches a second pin-ball machine... (visions of a
huge room filled with ping-pong balls and mouse traps.)

E. Somewhere all of the above interacts with X11 ... and a miracle happens
(except it does not happen on my tablet)
Q12 -- how do I see (a) what is happening, and (b) what went wrong, and (c)
share what I see with others who might help fix things?

F. Things happen on my laptop [eg, low battery or battery charged, etc] and I
see a desktop [gnome] pop-up announcing some happening.
(there is no Q13)
Q14 --  This is not upstart but some form of "notify" widget that is part of the
desktop suite and extensions, right?


Eager but frustrated,
~~~ 0;-Dan