Ubuntu: A Beginners Guide
kyle.nitzsche at canonical.com
Wed Dec 23 15:02:21 UTC 2009
Instead of OpenOffice as the source format, you might consider
single-sourced docbook. When set up properly this allows:
* true single sourcing (content is never duplicated, even for translations)
* easy localization (translations and images - for example screenshots)
* conversion to multiple localized output formats (html, pdf, docbook)
with a single command
There's a project that makes all this easy:
That project has a PPA that allows you to install the doctemplate
Just add that to your System > Administration > Software Sources then
install doctemplate with:
* "sudo apt-get update"
* "sudo apt-get install doctemplate"
Once doctemplate is installed:
* you create a new docbook article or book in the current directory
with a single command ("doctemplate_setup_article" or
* docbook content that is ready to edit, modify and build is created
* you generate localized pdf, html, docbook, with a single command
("make_pdf" "make_html" "make_docbook")
* translations are in po files that can be updated from source with a
single command, and localized outputs always use the po files. po files
can be translated in Launchpad or using many other available
The guiding design/development principle for doctemplate is: make it
easy for writers to write by handling the techy bits.
Docbook does have a handful of tags the writer needs to know. They are
well-documented on the web, for example:
You can edit the docbook files in various applications, including text
editors like gedit. The bluefish package provides some pretty good
docbook specific functions.
I am currently finalizing the short documentation for doctemplate:
Get the docs this way:
(you have to have the "bzr" package installed.)
'bzr branch lp:doctemplate-user-guide"
Then, in the root directory, run "./make_html"
Then display the English version with: "firefox build/html/en/index.html"
(or, to make a pdf, run "./make_pdf" and display it with "evince
(or to make localized docbook, run "./make_docbook" and display it in
yelp with "yelp build/xml/en/doctemplate-doc.xml")
(The doctemplate-user-guide is also written using the doctemplate approach.)
Benjamin Humphrey wrote:
> Hello everyone,
> Recently I started up a project to write a manual for Ubuntu that is
> both informative and easy to follow. My goal is around 50-75 pages,
> and perhaps having two different versions - one in-depth guide that
> covers pretty much everything, and one 10 page Quick Start guide,
> which, in the future, could be shipped with the Ubuntu CDs.
> I began writing it myself, but after deliberation and advice from
> other users, it would be better to make it a community effort. The
> idea is to have the first release ready for Lucid, and then a refresh
> every 6 months to coincide with a new Ubuntu version. Eventually, I
> hope it becomes the first point of reference for any Ubuntu newcomers.
> We need contributors, and I thought the best place to start would be
> the documentation team.
> I was talking with Jono Bacon tonight and he suggested the ideal way
> to go about testing/feedback/contributions for the manual is via
> Launchpad. He is really excited about the idea and is interested to
> see how it pans out – so am I.
> Therefore, I’ve just created a Launchpad team for the Beginners Manual:
> I’ll set up a bzr tomorrow and upload the .odt and .pdf of what I have
> so far (about 3 rough chapters), feel free to download it and start
> contributing. Perhaps the best way to do it would be to pick a chapter
> that you feel confident in and write something on it – doesn’t have to
> be big, just a rough draft and I can add extra stuff when I get there.
> I will also try to be on #ubuntu-doc tomorrow for any questions.
> If anyone knows anything about LaTeX could they let me know too.
> Benjamin Humphrey
> humphreybc at gmail.com <mailto:humphreybc at gmail.com>
> www.interesting.co.nz <http://www.interesting.co.nz>
More information about the ubuntu-doc