www.alexander-merz.com | Alexander Merz

BLANKPAGEHACK

DocBook-Dokumente werden meist mit den modularen DSSSL- oder XSL-Stylesheets von Norman Walsh nach HTML transformiert. Dabei können Inhaltsverzeichnisse auch auf Kapitel-Ebene erzeugt werden. Manchmal stört es aber, dass das Verzeichnis auf einer Seite zusammen mit der ersten Sektion des Kapitels landet.

Leider kann dieses Verhalten nicht geändert werden, ohne die StyleSheets selbst anzufassen - was bei den komplexen Stylesheets alles andere als leicht ist.

Es gibt allerdings einen einfachen Trick: Man definiert einfach am Anfang eine leere Sektion.

<chapter>
 <title>Mein Kapitel</title>

 <sect1>
  <title/>
  <simpara/>
 </sect1>

 <sect1 ...
 ...
</chapter>

Nachteil dieser Lösung ist allerdings, dass sie bei anderen Ausgabe-Formaten, die "echte" Inhaltsverzeichnisse unterstützen, zu unschönen Ergebnissen führen. Das gilt z.B. für Latex und PDF.

Es wäre also praktisch, wenn wir diesen Trick mit der leeren Sektion an- und ausschalten könnten. Dazu packen wir die leere Sektion in eine Entität:

<!ENTITY blankpagehack '<sect1><title/><simpara/></sect1>'>
und diese setzen wir entsprechend ein:
<chapter>
 <title>Mein Kapitel</title>

 &blankpagehack;

 <sect1 ...
 ...
</chapter>

Will man die leere Sektion deaktivieren, dann setzen wir den Wert der Entität einfach auf eine leere Zeichenkette:

<!ENTITY blankpagehack ''>

Das jedesmal von Hand zu machen ist das natürlich etwas umständlich. Kommt aber ein ./configure-Skript für die Transformation zum Einsatz, was bei größeren DocBook-Dokumenten ein sinnvolles Muß ist, kann es entsprechend ergänzt werden. Dazu ändern wir die Entität zu:

<!ENTITY blankpagehack '@BLANKPAGEHACK@'>
Im ./configure-Skript ergänzt man einen entsprechenden Schalter:
AC_MSG_CHECKING(for blankpage hack)
AC_ARG_ENABLE(blankpagehack,
[  --disable-blankpagehack     Disables the blankpage hack,
                                           recommended for non-HTML output],
[
if test $enableval = yes; then
    BLANKPAGEHACK="<sect1><title/><simpara/></sect1>"
else
    BLANKPAGEHACK=""
fi
],[
    BLANKPAGEHACK="<sect1><title/><simpara/></sect1>"
])
AC_SUBST(BLANKPAGEHACK)
(Nicht vergessen, dass das ./configure-Skript auch die Datei, welche die Definition enthält, auch beachten muß!)

Wird das ./configure-Skript ohne der blankpagehack-Option aufgerufen, dann wird die leere Sektion eingefügt. Erfolgt der Aufruf hingegen mit der Option --disable-blankpagehack, dann wird die leere Sektion nicht eingefügt.