[TYPO3-doc] DocBook: customizing the schema

[Thomas Schraitle]

Hey Ben,

Monday 20 June 2011
> 
> The work you are doing seems awesome. I do understand limiting the
> amount of tags and a lot of other stuff. I tried XMLmind a couple of
> times during the years, but never felt able to understand it properly.
> What would I need as a simple editor to get going and can you in some
> way provide the basics for less knowledgable editors to get started with
> docbook for TYPO3? As I understood the documentation needs to be written
> in docbook, probably using XMLmind, right?

It needs to be written in DocBook, that's right. However, if you don't like 
XMLmind you are not limited to this editor. As DocBook/XML is basically text, 
you can use every editor you like. Of course, I would recommend a good XML 
editor which simplifies the writing process _a lot_! For example, a good XML 
editor understands the DocBook schema and can provide context sensitive tag 
suggestions and completions.

To answer your original question:
Maybe Serna[1] would be an option? Also jEdit could be useful as well. You 
need to download some plugins to get it going.

Of course, the "good old" Emacs and vi are also alternatives to some extend. 
*cough* I only used Emacs some time, but for a beginner it might be a bit "too 
geeky". ;) Same for vi.

I use oXygen for my daily XML/XSLT and DocBook tasks, but this may be out of 
scope for most as it is commercial.

Well, usually I would insert here a link to the DocBook Wiki. It contained a 
very extensive and helpful overview page about XML editors. Unfortunately, it 
completely disappeared after a server crash. ;-(( Sad, sad.

 
> I downloaded tsref as docbook and opened it with xmlmind. The images are
> not rendered, but I think I reported that before.

I'm not sure, but I guess the images are stored in a completely different 
path, but the reference to the images points to the directory where the XML 
files are.


> Can you provide a
> proper package for me to try out, so I can get the idea. Another thing
> we definitely need to tackle is the fact that every manual is called
> manual ;-) Inside the zip file there is a folder manual and a manual.xml.

That is indeed misleading, unfortunately out of my permissions. :) "Manual" is 
really too generic. 

If you are brave enough, you can use also my example[2] in the SVN. This is 
usually my "playground" where I develop the schema and stylesheets. Basically 
you just need the "flow3-manual" directory. You can find the schema itself in 
"docbook51b2/typo3.rnc". The other stuff can be ignored for the time being.

 
> I am 100% sure that this will be awesome when we have it in place. It is
> a bit like TYPO3 itself I guess. A steep learning curve, but once you
> get it the possibilities are great.

Well, it depends on your mindset. If you have already experienced HTML, it 
will be less difficult. People who only knows word processors has probably 
more problems.

Thanks for your input, Ben. Hope you like the results of our "DocBook schema 
attack". ;)  I guess, we will get most of the input when all writers really 
start using it.


Cheers,
  Tom

---------
[1] http://www.syntext.com/products/serna/
[2] 
https://svn.typo3.org/TYPO3v4/Documentation/official_template/trunk/DocBook