Revamping the Packaging Guide

[Daniel Holbach]

Hello everybody,

At UDS we talked about "Revamping the Packaging Guide" and figured out a
plan ([1], [2]) 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. - [3] and [4] might be
    helpful there)
 3. update old docs and massage them into single standalone articles
    that focus on explaining specific tasks (and re-use bits here and
    there)
 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 [5] and
Sphinx [6]. Here's the list of pros and cons:
 * Mallard:
  - PRO: used in GNOME
  - PRO: integrated with yelp
  - PRO: does translations nicely
  - CON: XML
  - CON: doesn't do .pdf or epub
 * Sphinx:
  - PRO: ReStructured text
  - PRO: variety of output formats (.html, single .html, pdf, epub,
         .txt, etc.)
  - 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 [7] and put up a
couple of short articles at lp:~dholbach/+junk/ubuntu-packaging-guide [8].

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.

Open questions:
 - 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,
 Daniel



[1]
https://blueprints.launchpad.net/ubuntu/+spec/ubuntutheproject-community-n-improve-packaging-guide
[2] https://wiki.ubuntu.com/Specs/ImprovePackagingGuide
[3] https://wiki.ubuntu.com/CategoryPackagingGuideNeedsPolicyReference
[4] https://wiki.ubuntu.com/CategoryPackagingGuideNeedsUpdate
[5] http://projectmallard.org/
[6] http://sphinx.pocoo.org/
[7] https://launchpad.net/~dholbach/+archive
[8] https://code.launchpad.net/~dholbach/+junk/ubuntu-packaging-guide