[TYPO3-doc] DocBook: customizing the schema

[Thomas Schraitle]

Hi,

Thursday 16 June 2011
> 
> > Some open questions still persist:
> > 
> > 1. How "restrictive" want we to be?
> >
> >[snip]
> >
> > 2. What should we do with semantical similar elements?
> > [snip]
> 
> Answering those 2 questions together: I think we should not be too
> restrictive. OTOH I think it's worth banning as many tags as possible to
> make editor's lives easier and the editing process less prone to
> mistakes.

Right, totally agree. I've started that process already some time ago, but I 
was unsure what is really needed and what not. So my changes are based on my 
own views and may or may not be sufficient for TYPO3 documentation. 


> DocBook sometimes goes into a lot of details, which I don't
> think is necessary. Your example with all the "gui*" tags is a perfect
> one. With the sample manual I tried to use most of the tags that I think
> we would need, so I would take it as a basis for restrictions. Of
> course, this is open for discussion as I may well have missed some
> useful tag.

Same for me. If someone wants to comment on my RNG customization, please do! 
:-)


> > 3. Do we want to allow "foreign" DocBook vocabulary (like SVG or MathML)?
> 
> I don't know. I wouldn't expect math formulas to be necessary.

Yes, me too. It is still possible to use the SVG or the rendered PDF and 
reference them in your mediaobject element.


> SVG could be nice I guess, although our need for charts is pretty limited.
> Most of our pictures are screenshots.

Just that everbody understands what I'm talking about: If you want to insert 
some graphics, the usual way is to use mediaobject and link to it:

--------[ Mediaobject with Reference to Image ]--------
 <mediaobject>
  <imageobject>
    <imagedata fileref="typo3.svg"/>
  </imageobject>
  <!-- Maybe add additional imageobjects here, if needed -->
 </mediaobject>
-------------------------------------------------------

However, it is possible to customize the DocBook schema and allow SVG markup 
inside an imageobject like this:

--------[ Mediaobject with SVG Image ]--------
 <mediaobject>
  <imageobject>
   <svg xmlns="http://www.w3.org/2000/svg" 
     width="5cm" height="5cm">
     <rect x="1cm" y="1cm" width="3cm" height="3cm" fill="black"/>
     <rect x="2cm" y="2cm" width="1.5cm" height="1.5cm" fill="orange"/>
   </svg>
  </imageobject>
  <!-- Maybe add additional imageobjects here, if needed -->
 </mediaobject>
-------------------------------------------------------

That way you "draw" your chars/illustrations/etc. inside DocBook! Scary, isn't 
it? ;-)

For me, this is overkill; usually you draw your illustrations in your special 
drawing application (like Illustrator, Inkscape, ...) and save it as SVG.


> I suppose it's still possible to point to an SVG file, right?

Sure, that doesn't affect the reference as shown above.


> > 6. Consistent Linking?
> >     [...]
> >     Should we use explicitly<link>  for our external links and disallow
> >     XLinks? Again, consistency vs. flexibility.
> 
> I would say that links are indeed easier to understand (and especially
> to keep an overview of). In the sample reference manual I also used xref
> tags. Is that related to your question?

Yes, exactly. I would completely remove XLinks. That way it is consistent and 
no writer is lead into temptation of using it. :) What's not there could not 
be (ab)used. ;))


Oh, and if I didn't say it explicitly enough: I strongly recommend to keep our 
customization as compatible as possible to DocBook. That means, no self-
invented new elements or attributes. The customization will be just a subset 
of the DocBook schema.


> [...]


Tom