Project Overview

The Shuttleworth Foundation intends the Cookbook to accompany all tuXlab implementations. Where there isn't a local LUG, it should provide sufficient guidance and information to enable a motivated staff or community member to setup and configure a tuXlab from scratch.

Where there is an up and running tuXlab, the Cookbook should enable users and administrators to explore, troubleshoot and fully utilise it. As such, it should identify all components (PCs, cabling, hubs/switches, printers, plugs, trunking) and provide walkthroughs for familiarising oneself with e.g. the network and available applications, and for troubleshooting common problems. It could also contain recipes on common tasks such as using email, creating and saving a document, or using internet banking.

The first deliverable of this project is a printed book of between 100 and 200 pages (depending on the scope, it may also be more). tuXlab installations should include a PDF suitable for printing additional copies as needed (which may differ from the book PDF in being prepared for an A4 printer), as well as a locally browsable hypertext version. Since tuXlabs will continue evolving and adapting to changing circumstances, the Cookbook will be a living project, with a website where readers may submit feedback, contributions and corrections.

Writing

I propose to do the writing in plain text. For outlines, I use VimOutliner , and for the book text, I use reStructuredText .

reStructuredText is a plain text format which uses typographic conventions and significant whitespace to convey structure. It is well-specified, extensible, and subtle enough to capture most of a book's structure. Being plain text, it works well with version control systems. While writing, I maintain lists of terms that I want to be able to tag in bulk after conversion to DocBook .

After writing has been completed, I use a couple of tools to move from reStructuredText to DocBook, and then continue maintaining the text in DocBook. I use reStructuredText to begin with because I live in Vim , and it allows me to concentrate on the writing and worry about tagging later.

DocBook is a valuable destination format for the Cookbook, since a wealth of tools exist to process it further. It can be used to generate derived content such as indices, and it can function as the core of a translation project: e.g. the KDE project provides tools that use GNU gettext to translate DocBook. (At this point it might become necessary to leave behind the reStructuredText source text.)