[TYPO3-doc] About DocBook 5 Customization

[Thomas Schraitle]

Hi,

Monday 13 December 2010
> [...]
> >> - Much linking between manuals and to URIs outside (the problem is often
> >> broken links because of changed URIs)
> > 
> > Yes, linking can be a pain. Are you talking about internal or external
> > links?
> 
>  From what I understand from DocBook (which is not yet much) internal
> links are not really problematic.

That's true.

Before we should talk about this, what writers do usually? They define terms 
before they use it! :)

Ok, here we go:
* Internal links in DocBook-speak are usually <xref/>s (coming from cross-
reference). You need two attributes: the xml:id attribute on the source which 
forms the label. On the other side, the linkend attribute on <xref/> points to 
the link target by identifying the value of its xml:id attribute. Something 
like this:

  <section xml:id="sec.foo">
    <title>Bla</title>
    ...
  <para>See <xref linkend="sec.foo"/> for further information.</para>

Internal links (xrefs) are checked during validation regardless of the schema. 
As you know, each ID can occur only once in the whole document.

* External links in DocBook-speak are usually <link>s. Interestingly, DocBook5 
allows not only <link> elements as external links. Each(!) element can be 
turned into a "hot link" using the XLink syntax. For example:

  <link xlink:href="http://www.w3.org/1999/xlink"
    >XML Linking Language (XLink)</link>

the previous link can also be written with citetitle:

  <citetitle xlink:href="http://www.w3.org/1999/xlink"
    >XML Linking Language (XLink)</citetitle>

By the way: This would not be possible with DocBook 4. 

Each solution above is ok, it's more a matter of taste, I would say. However, 
external links are NOT checked during validation.


> Our issue is really with external
> links, i.e. linking across manuals, but also outside links pointing to
> manuals. [...]
> 
> The real headache we're having right now is that most of the time when a
> manual is generated the numbering of the chapters changes. This means
> that existing links are broken (plus the fact that the full URLs also
> contain the version of the manual, which doesn't help). [...]

Your problems remind me of the current structure of our manuals. We use a 
structure like this (simplified for the sake of simplicity):

  set
    book xml:id=book.quick  # Quick Starts
      article
      article
    book xml:id=book.user   # User Guide
      preface
      chapter
      ...
    book xml:id=book.admin  # Admin Guide
      preface
      chapter

In the above structure, we can create a <xref/> from deep inside book.user to 
some chapter or section in book.admin. As this is a _complete_ document, the 
<xref/>s are checked and correctly resolved. Numbers are preserved.

The DocBook stylesheet allows to process only a part of the document, for 
example, only the User Guide.

Disadvantage: IDs can only be used once in the whole set. This may be 
problematic when dealing with a more "topic oriented" approach when you 
shuffle around your chapters, section, etc. to form a new manual.

Maybe DocBook assemblies may be a solution, but as far as I know, they are 
currently not supported by the stylesheets. There are lots of interesting 
things going on in the DocBook world...

If you don't like this solution, use the olink feature. I try to avoid it as 
it is difficult to understand (and use).


> http://typo3.org/documentation/document-library/core-documentation/doc_core
> _tsconfig/4.3.2/view/1/6/
> 
> The problem with the version number must be handled on the TYPO3 side,
> but it would be much better if we could use more explicit keywords than
> "/1/6". This is probably something that needs to be solved on the TYPO3
> side too, but with information extracted from the DocBook files.

This can be solved really easily by DocBook. For example, let's assume you 
have a chapter with this ID:

  <chapter xml:id="cha.typo3.introduction">

You can control the filename with a stylesheet parameter. This turns the ID 
value into a filename: cha.typo3.introduction.html. It is also possible to 
create individual HTML filenames.

 
> BTW I'm wondering how a full manual rendered to HTML would fit into the
> structure of typo3.org. Currently the manuals are cut into HTML "pages"
> that correspond to chapters. These "pages" are stored in a database
> table (AFAIK, I'm unsure about this part) and are served as content
> inside the site's template when requested. I'm not sure how this would
> be achieved after the DocBook migration. Could we have a rendering that
> splits the HTML into several files that would be equivalent to the
> "virtual pages" that we have now?

This is mostly done by the chunking process of the DocBook HTML stylesheets. 
You can define at which level a new chunk is created. For example, you can say 
you want it at the chapter level, or at each section 1 level, or ...

 
> (I don't know if this is really clear for you :-/ )

I hope so. :)


> > 1. Which block elements do you need (especially sectX vs. section)?
> > 2. Should content models can be simplified?
> > 3. Which inline elements do you need?
> > 4. Can para be simplified?
> 
> I'm currently preparing a sample DocBook document based on our current
> template, so that we have a first example which should normally contain
> most of what we should need. I'm also using the FLOW3 (TYPO3's next
> generation PHP framework) documentation as a reference, as it seems
> quite clean and well structured.

Ahh, now I know what the FLOW3 acronym is all about. :)

 
> [...]


Thanks, this is really an interesting discussion! :-)


Cheers,
  Tom