Revamping the Packaging Guide
daniel.holbach at ubuntu.com
Mon Dec 13 10:06:50 GMT 2010
At UDS we talked about "Revamping the Packaging Guide" and figured out a
plan (, ) that we feel is realistic and allows us to fix and
update the Packaging Guide over time.
The main problems we want to solve are:
- move away from unmaintainable wiki guides
- provide an easy way to translate the guides (using LP infrastructure)
- provide an easy way to file bugs on the guides
- provide online and offline (.html, .pdf, epub?) guides
- provide raw text guides in /usr/share/doc
The general plan looks like this:
1. decide on a toolkit
2. review old documentation (reusability, etc. -  and  might be
3. update old docs and massage them into single standalone articles
that focus on explaining specific tasks (and re-use bits here and
4. package for Ubuntu, publish guides on the web, etc. as more and
more guides get added
The current toolkit contenders discussed at UDS were Mallard  and
Sphinx . Here's the list of pros and cons:
- PRO: used in GNOME
- PRO: integrated with yelp
- PRO: does translations nicely
- CON: XML
- CON: doesn't do .pdf or epub
- PRO: ReStructured text
- PRO: variety of output formats (.html, single .html, pdf, epub,
- PRO: supports gettext infrastructure
- CON: only supports gettext in 1.1 (trunk), we're on 1.0 in natty now
(Barry talked to sphinx upstream and they might be able to
release 1.1 before Feature Freeze.)
I had a look at sphinx and I'm quite happy with it. Not only is it used
by lots of python projects already, but also is it very easy to write in
ReStructured text, and the output looks great too.
I packaged current trunk of sphinx in ppa:dholbach/ppa  and put up a
couple of short articles at lp:~dholbach/+junk/ubuntu-packaging-guide .
Additional ideas we had:
- include version information in the doc
- in offline docs, add points to latest version on the web
The possibility of using DocBook (all kinds of output formats, XML, does
translations) was brought up too.
- is RTL supported?
Who would be interested in helping out? Are there additional things we
should think about now before getting started?
Have a great day,
More information about the ubuntu-devel