In my desktopcouch chapter of the manual, I have an example program to
demonstrate the principles I'm talking about. It's a very (very very)
simple thing for cataloguing your DVDs, and it's a quickly program. The
desktopcouch code is (deliberately) confined to one file, backend.py,
and that's the file that I explain in the chapter, to illustrate the
principles of using desktopcouch, storing and retrieving data therein,
and so on.
The rest of this program -- the quickly code, the Glade UI, the code to
handle clicks on buttons and so on -- isn't relevant to my chapter. So,
I am loath to put that code in the chapter; it will bulk out the chapter
with things that don't have anything to do with desktopcouch (and are
explained, better, in other chapters anyway!) However, if you *only*
have the desktopcouch backend explained in the chapter, you can't
actually see the program running and experiment with it.
I therefore propose that the program is available somewhere on
Launchpad, and that my chapter says: to get the code for this whole
program (if you want to work with it, rather than just read examples),
do "bzr branch lp:ubuntu-developer-manual/desktopcouch-dvd-example". I
know that at that point in the manual we won't have explained bzr, but I
don't think we need to have done: we can just say "run the above command
to get the code; you do not have to worry about why or how it works. If
you really do want to know that, then read the bzr chapter now, but it's
not necessary to do so."
There's also another benefit here: if the example programs are all
available on LP as downloadable source code, it makes it relatively easy
for someone to fetch the whole suite of example programs and follow
along in their text editor as they read the book.
(Note: it would be possible to explain how to create the whole DVD
catalogue program as part of my chapter. I don't think this is a good
idea because it will bulk out the chapter unnecessarily, as mentioned,
but also because the program uses Glade (because it's a Quickly app),
and I'd have to have a whole section showing how to use Glade to
reconstruct the window and signals required for the app. That'll bulk
out the chapter even more severely than having a bunch of Python code
which isn't particularly relevant.)
Your thoughts invited.
