ubuntu-developer-manual team mailing list archive

[Kyle Nitzsche <kyle.nitzsche@xxxxxxxxxxxxx>]

On 03/05/2011 11:58 AM, Kyle Nitzsche wrote:
> (But, I cannot currently push those branches due to an apparent bzr server 
> error, so until I can push, one cannot build the book pdf from those branches, 
> although articles build fine individually.) 

Not sure why, but the chapter branches had server side bzr locks in them which I 
could not break with bzr break-lock bzr+ssh://URL.

So I have moved them aside (renaming them by appending ".orig".) And have pushed 
the latest chapter branches which can be built into a book pdf with doctemplate 
and a proper directory layout:

$ tree -L 1 ubuntu-developer-guide/
ubuntu-developer-guide/
|-- bazaar/
|-- book/
|-- credits/
|-- customization/
|-- distribution/
|-- glade/
|-- glossary/
|-- launchpad/
|-- quickly/

(Other chapter branches coming, per Belinda.)

That is, you have a parent directory (ubuntu-developer-guide) that contains all 
those ^^^ directories, all of which can be branched from 
https://code.launchpad.net/~ubuntu-developer-manual/ubuntu-developer-manual/

Two of these directories are not chapters:
 * "customization": This contains per-output-type customization layers for 
chapters. Each chapter's environment file points at it via the "CUSTOM" 
variable. Each article requires such a directory, and it can live anywhere. It 
makes sense for them all to share one so that design and other customization 
work is done once and common to all.
 * "book": This is the book project, used to build the chapters into a book 
pdf. It contains book.xml, which has <art> elements that point at the chapters, 
which is how they are included. Not that the books has its own, separate, 
customization capabilities. So for example, pdf customizations done for articles 
do not apply to the book pdf.

Note that chapters are actually docbook <article>s. Each is a free-standing 
doctemplate (launchpad.net/doctemplate) article project that is localized 
(languages, images) and built (into html, docbook, pdf, epub) by doctemplate. 
(build with doctemplate_make* commands)

The book is a doctemplate book project and a docbook <book> that includes 
articles as chapters (via the book.xml file and some doctemplate xml/xsl). It is 
currently built into localized pdfs. On build, each article's localized docbook 
is generated, then included into the localized book docbook, then turned into a 
pdf. The book can have docbook <part>s that divide the chapters into groups, if 
desired. (build with doctemplate_make_book-pdf command).

A key point of this directory layout is complete modularity of main topics, the 
chapters, to support remixing into various use cases. These chapter/articles are 
separately developed and translated. And live in dedicated branches. For 
example, they can be built to localized html output for posting to 
developer.ubuntu.com. And, they can be pulled into a book(s). As such, their 
content should be self contained: authors should write them as independent 
articles, I think.

Cheers,
Kyle



Cheers,
Kyle