[TYPO3-doc] A few DocBook questions

[Thomas Schraitle]

Hi François,

Thursday 16 December 2010
> I'm trying to come up with a sample DocBook document that reflect our
> current template file (currently based on OpenOffice). I thought I would
> wrap it up before asking some questions, but I find myself stuck on some
> points, so here goes with the questions first.
> 
> 1) there are a number of structures which exist in both formal and
> informal variants. Is there any recommendation about which to use. Is it
> advisable to limit the choice to formal structures to... err, well, be
> formal? Or should we just keep the freedom?

You mean probably informalfigure/figure, informalexample/example etc.

Well, the difference is the title: it's only allowed on figure, example, table 
etc. The informal* elements don't have any titles at all.

The title in figure, example, etc. shows up in the list of figures, list of 
tables, list of examples etc.

To sum it up: If you want your titles of your tables, examples, etc to appear 
in the "table of contents" then use the elements with the respective names. If 
you don't need an entry in the TOC, use the informal* variant.


> 2) some of our manuals are language references, in particular TypoScript
> which is a kind of parametrization language with which templates are
> built in TYPO3 (to give a (very) short explanation to Tom, our visiting
> DocBook expert).

Thanks! :-)


> [... table with four columns ...]
> 
> How should we do this with DocBook? I naively tried out with a table
> (HTML), but the "td" element cannot contain block elements. This makes
> it insufficient with regards to the needs for the description.

It is possible. Before I will show you how, I should mention that DocBook 5 
allows two table models:

 a) CALS tables
 b) (X)HTML tables

Both are sufficient for your table issue. I've tested both. Let's deal with 
CALS first:

a) CALS tables

  <table pgwide="1">
    <title>A good title</title>
    <tgroup cols="4">
      <colspec colname="c1" colwidth="1*"/>
      <colspec colname="c2" colwidth="1*"/>
      <colspec colname="c3" colwidth="4*"/>
      <colspec colname="c4" colwidth=".8*"/>
      <thead>
        <row>
          <entry>Property</entry>
          <entry>Data type</entry>
          <entry>Description</entry>
          <entry>Default</entry>
        </row>
      </thead>
      <tbody>
        <row>
          <entry><property>allWrap</property></entry>
          <entry>wrap/stdWrap</entry>
          <entry>Wraps the whole item</entry>
          <entry/>
        </row>
        <row>
          <entry><property>RO_chBgColor</property></entry>
          <entry>string</entry>
          <entry>
            <para>If property RO is set (see below) then ...</para>
            <cmdsynopsis>
              <group>
                <arg choice="opt">over-color</arg>
                <arg choice="opt">out-color</arg>
                <arg choice="opt">id-prefix</arg>
              </group>
            </cmdsynopsis>
            <informalexample>
              <screen>page = PAGE
page = PAGE
page.typeNum = 0
page.10 = HMENU
page.10.wrap = &lt;table border=1>|&lt;/table>
page.10.1 = TMENU
page.10.1.NO {
allWrap = &lt;tr>&lt;td valign=top
id="1tmenu{elementUid}"
style="background:#eeeeee;">|&lt;/td>&lt;/tr>
subst_elementUid = 1
RO_chBgColor = #cccccc | #eeeeee | 1tmenu
RO = 1
}</screen>
            </informalexample>
            <para>This example will start out with the table cells in
                #eeeeee and change them to #cccccc (and back) when
                rolled over.</para>
          </entry>
          <entry/> 
        </row>
      </tbody>
    </tgroup>
  </table>


b) (X)HTML table

  <table pgwide="1" rules="all" border="1">
    <caption>A good title</caption>
    <col width="1*"/>
    <col width="1*"/>
    <col width="8*"/>
    <col width=".8*"/>
    <tr>
      <th>Property</th>
      <th>Data type</th>
      <th>Description</th>
      <th>Default</th>
    </tr>
    <tr>
      <td><property>allWrap</property></td>
      <td>wrap/stdWrap</td>
      <td>Wraps the whole item</td>
      <td/>
    </tr>
    <tr>
      <td><property>RO_chBgColor</property></td>
      <td>string</td>
      <td>
        <para>If property RO is set (see below) then ...</para>
        <cmdsynopsis>
          <group>
            <arg choice="opt">over-color</arg>
            <arg choice="opt">out-color</arg>
            <arg choice="opt">id-prefix</arg>
          </group>
        </cmdsynopsis>
        <informalexample>
          <screen>page = PAGE
page = PAGE
page.typeNum = 0
page.10 = HMENU
page.10.wrap = &lt;table border=1>|&lt;/table>
page.10.1 = TMENU
page.10.1.NO {
allWrap = &lt;tr>&lt;td valign=top
id="1tmenu{elementUid}"
style="background:#eeeeee;">|&lt;/td>&lt;/tr>
subst_elementUid = 1
RO_chBgColor = #cccccc | #eeeeee | 1tmenu
RO = 1
}</screen>
        </informalexample>
        <para>This example will start out with the table cells in
          #eeeeee and change them to #cccccc (and back) when rolled
          over.</para>
      </td>
      <td/>
    </tr>
  </table>


The obvious question you probably have: Which one is better? I don't know. :) 
This is a matter of taste. Some prefer CALS, some the (X)HTML table model.

The (X)HTML table model might be a bit easier if you legacy data in (X)HTML 
tables. This would be indeed easier to use in DocBook.

Interestingly, the above code appears a bit differently. I'm not sure if this 
is a problem of the DocBook stylesheets or if I did something wrong.


Apart from CALS vs. (X)HTML issue, tables can be "difficult". The problem with 
tables are, they disrupt the normal text flow. It's not an issue for (X)HTML, 
but can be for FO -> PDF. Some FO formatters (FOP?) can run out of memory, if 
you have very long tables. I'm not sure if this problem still persists, but 
I've read that on the mailinglist some time ago.

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. ;-)


Hope that helps,
  Tom


----
[1] http://www.docbook.org/tdg5/en/html/refentry.html