ubuntu-manual team mailing list archive
Mailing list archive
Re: Documentation pool sample content
On 07/14/2010 12:27 AM, Jim Campbell wrote:
2) Put the content into the different formats. Format assignments are
- Docbook v5 - Could a member of the docs team take care of this one?
Perhaps Kyle? Mdke?
Yes I can put some docbook 5 there.
This is perhaps a reasonable place to note that the content pool's
element "vocabulary" (its set of structures for indicating sections,
paragraphs, etc) must, I think, support *all* required fundamental
structures of all delivery formats. By which I mean, suppose a delivery
format is going to use numbered lists, then clearly the source format
needs to support numbered lists. So, if a proposed content pool source
format does not support structures that are required by target delivery
formats, this would seem to rule this source format out.
So what are the required "structures" or element vocabularies that the
source format must support? Well, as a start, here's some guesswork:
* overall container (in docbook, that's <article>, since it is
perfectly topic oriented (despite the oft-repeated and, I believe,
technically incorrect view that docbook is only suitable for books,
manuals, and linear documents))
* container title and other meta info (author, revision, etc.)
* header 1
* header 2
* code snippets
* media (images, videos, sounds clips)
* bulleted lists
* numbered lists
* links (this is a topic where things can go wrong though. I'd argue
topics should only link to other parts of themselves or they can too
easily break. The user portal (whatever it is in each case), should
provide facilities for finding topics of interest.)
* inline tagging (emphasis, other)
It is remarkable that almost everything can be written using just those
constructs (I probably forgot some...?)
Naturally, there has to be mechanized means of converting all of these
to their equivalents in the delivery formats, or else, I would argue,
the source format does not meet requirements.
Given this "convertibility" requirement, there should be an "official"
list of elements that are allowed to be used in the source format. To be
an allowed element, it has to be shown to be convertible to every
I think docbook is the most likely candidate for the source format because:
* It already has vocabulary (element structures) for all needs
(indeed, one can argue its vocabulary is too big)
* It already has rich conversion capabilities (although perhaps not
yet to Mallard. This could be created though.)
One potential pitfall with docbook would be *not restricting the set of
allowed elements*. Therefore the need for a managed list.