ubuntu-manual team mailing list archive

[Luke-Jennings <ubuntujenkins@xxxxxxxxxxxxxx>]

Hi all,

On Fri, 2010-07-16 at 08:22 -0400, Kyle Nitzsche wrote:
> 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>

unfortunaly my knowledge on the subject is not that great along with the
lack of time I have at the moment I am not much help. I was wondering
how it is going and if we are at the stage of having another meeting to
decide on a format?

Regards

Luke Jennings
{jenkins on #freenode}