ubuntu-manual team mailing list archive

[Kyle Nitzsche <kyle.nitzsche@xxxxxxxxxxxxx>]

Hi,

Regarding docbook ease of use and suitability, a while ago I put 
together a build system (I call it doctemplate) for docbook that was 
designed to maximize certain values:
 * extreme ease of use
 * multiple output formats, all localized (currently two forms of html, 
pdf, epub,
 * localization of text and images
 * separation of content (including translations and images) from build 
infrastructure (so there is no irreversible commitment to doctemplate).
 * for pdf output, ability to specify font per language
 * built-in per-output format docbook customization layers and 
parameters. For pdfs this means customizable tables of contents, front 
pages, profiles, etc. etc.
 * autogeneration of localized omf files (for installing docs in 
gnome-like systems such as ubuntu)

I packaged it up and pushed it up to a doctemplate Launchpad PPA: 
launchpad.net/doctemplate

If anyone would like to give it a try, just:
(1) add the ppa:
apt-add-repository ppa:doctemplate-team

(2) install doctemplate:
 sudo apt-get install doctemplate

(3) create a new directory for the new docbook article and move into it:
mkdir ~/doctemplate-test-article
cd ~/doctemplate-test-article

(4) create the article:
doctemplate_setup_article

(5) note:
 * the article/ directory contains "sample-article.xml'. That's where 
you can start editing if you like.
 * articles are set up by default for four languages: en, es, ru, zh_TW 
(see the LINGUAS) file

(6) build html (first type):
./make_html

(6a) view it in, for example, Russian, by opening: build/html/ru/index.html
chromium-browser build/html/ru/index.html

Note that all generated output files are placed in build/ directory and 
this can be deleted at any time.

(7) build html (second type):
./make_html-site

(7a) view it in, for example, Russian, by opening: build/html/ru/index.html
chromium-browser build/html-site/es/index.html

(8) build pdfs in all target languages:
./make_pdf

(8a) view, Russian pdf:
evince build/pdf/ru//sample-article.pdf

(9) build epub (ebook):
./make_epub

(9a) view Russian epub ebook:
(install fbreader: sudo apt-get install fbreader)

FBReader build/epub/ru/OEBPS/content.opf

Etc.

I need to update docs (they are so old as to be wrong and confusing), 
and perhaps revisit this project if folks find it useful.

Docbook articles are supported, books have some issues. But since 
articles have a structure that is is very appropriate for short topic 
based help, this seems applicable.

Etc.

Cheers,
Kyle









On 07/10/2010 07:47 PM, Kevin Godby wrote:
> Hello, Phil and, er, Phill.
>
> On Sat, Jul 10, 2010 at 6:25 PM, Phil Bull<philbull@xxxxxxxxx>  wrote:
>    
> > Frustratingly, my Internet connection went down before the meeting, and
> > only just came back up. Does anyone have logs for the meeting that I can
> > review?
> >      
> You can read the logs of the meeting here:
>
>    http://irclogs.ubuntu.com/2010/07/10/%23ubuntu-manual.html#t21:00
>
> This week, each team (manual, docs, and learning) are going to work on
> writing a sample in the following formats: Docbook 5, HTML 5, Mallard,
> and DITA.  This way we can get a feel for the various formats, their
> pros and cons, and also explore how the writing styles differ among
> the materials produced by each team.
>
> I encourage everyone to post questions, notes about what they've
> learned, opinions, etc. to the mailing lists throughout the week.
>
> Thanks!
>
> --Kevin Godby
>
>