[TYPO3-doc] A few DocBook questions

[Thomas Schraitle]

Hi Phil,

Saturday 18 December 2010
> 
> On Fri, 17 Dec 2010 19:58:57 +0100, Thomas Schraitle wrote:
> > Your above data reminds me of reference material. So why not use
> > refentry[1] for that? This makes it easier to group your different
> > colums into different refsections. If you use refentry, you completely
> > avoid the need to push your data into tables. Just another strange idea
> > from me. ;-)
> > 
> > [1] http://www.docbook.org/tdg5/en/html/refentry.html
> 
> Looks cool :)
> It will just be a lot of work to do the initial transformation.

Well, that can be done in two steps: first create your DocBook files from 
OpenOffice documentation. This step is mandatory and you have to do it anyway. 
As a second step transform your DocBook files into the structure you want. 

The quality of the transformation depends on how you get from OpenOffice to 
DocBook. 

 
> Would it be possible to generate two views then, e.g. a table link now
> and a detail view like the php manual?

Maybe. Could be "only" a matter of XSLT magic. Of course, it depends heavily 
how you structured your table and if it's possible to map it into different 
structures.

Another question is if it's really a good idea to have two views. I would 
doubt that, but my knowledge of your TYPO3 documentation is limited. My 
suggestions would be the following:

 1. Collect all reference material into <refentry>s 
 2. Use <function>bla</function> in your text.
 3. Create a XSLT customization which adds automatically a link to the
    respective refentry. 

Of course, step 1 depends heavily on how much work is to get to this point. 
Step 2 is probably not that much work as you may have to go through the files 
anyway. Step 3 is not really difficult; I did it with indexterms to create a 
semi-automatical index.

Of course there are other variations of the above idea (or should I better 
say: crazy ideas?). For example, annotations come to my mind. :)



> (In this case I would even drop all examples from "table" and use
> the single view to show longer snippets).

I'm not sure if I understood you correctly: You mean, the table should display 
the most important information only? In that case, wouldn't it be enough to 
just insert a link to a refentry as described above?


Cheers,
  Tom