ubuntu-manual team mailing list archive

[Kyle Nitzsche <kyle.nitzsche@xxxxxxxxxxxxx>]

On 07/14/2010 12:27 AM, Jim Campbell wrote:
> Hi All,
{snip}
> 2) Put the content into the different formats.  Format assignments are 
> as follows:
> - 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
 * paragraph
 * 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.)
 * tables
 * 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 
delivery format.

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.

Cheers,
Kyle














{snip}
> Jim