Podstawy personalizacji są bardzo proste, ponieważ wszystko można wykonać, ustawiając odpowiednie parametry. Ich wpisywanie w linii komend jest jednak dość niewygodne, dlatego stworzymy sobie plik konfiguracyjny. W katalogu xsl/ powinieneś mieć już jeden taki: common.xsl. Nazwij sobie swój jakośtam i zaczynamy od początku:

<?xml version='1.0'?> 
<xsl:stylesheet  
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> 
 
<xsl:import href="docbook/html/docbook.xsl"/> 
 
</xsl:stylesheet>

Plik konfiguracyjny jest w rzeczywistości zwyczajnym arkuszem XSLT, który dołącza oryginalne pliki DocBook XSL, a później je konfiguruje. Pamiętajmy, że XSLT jest normalnym językiem programowania, aczkolwiek zalicza się go do grupy języków funkcyjnych (np. Haskell) - z tego też powodu część rzeczy wykonuje się zupełnie inaczej, niż np. w C++.

Dowolny parametr możemy ustawić znacznikiem <xsl:param name="nazwa" select="wartosc"/>. Zaczniemy od prostego wyboru języka, w jakim mają wyświetlać się komunikaty - będzie on wczytywany z atrybutu lang głównego tagu BOOK:

<xsl:param name="l10n.gentext.language" select="/book/@lang"/>

Możemy także określić własny styl CSS:

<xsl:param name="html.stylesheet" select="'style.css'"/>

Poniższy parametr włącza numerowanie także sekcji, a nie tylko rozdziałów:

<xsl:param name="section.autolabel" select="1"/>

Jednak coś jest nie tak - numery sekcji nie zawierają numeru rozdziału, w którym się znajdują. Możemy to włączyć tym ustawieniem:

<xsl:param name="section.label.includes.component.label" select="1"/>

Na stronie głównej zwykle znajduje się spis treści. Zajmijmy się teraz jego konfiguracją. Na początek sprawmy, aby pokazywał także sekcje wewnątrz rozdziałów. W poniższym parametrze określamy maksymalną głębokość, z jakiej sekcje są pokazywane (tutaj: 4):

<xsl:param name="toc.section.depth" select="4"/>

Możemy teraz wygenerować nasz dokument w formacie HTML:

xsl --output output/index.html xsl/moj_docbook.xsl moj_dokument.xml

Po chwili plik zostanie utworzony. W przypadku pisania dokumentacji przydaje się opcja podzielenia jej na wiele mniejszych plików. DocBook XSL również posiada do tego odpowiednie opcje. Należy zamiast docbook.xsl załączyć arkusz chunk.xsl w naszym pliku konfiguracyjnym, a w parametrze --output programu xsltproc wskazać sam katalog wyjściowy.

Wieloplikowy rezultat także możemy dodatkowo skonfigurować. U siebie używam do tego następujących parametrów:

<xsl:param name="use.id.as.filename" select="1"/>
<xsl:param name="chunk.section.depth" select="2"/>
<xsl:param name="chunk.first.sections" select="1"/>
<xsl:param name="generate.toc">
appendix  toc,title
sect1     toc
sect2     toc
book      toc,title
section   toc
preface   toc,title
chapter   toc,title
</xsl:param>
<xsl:param name="generate.section.toc.level" select="1"/>

Oto, co one oznaczają:

• use.id.as.filename - domyślnie DocBook nadaje plikom bardzo nielogiczne nazwy w stylu c05s03s05.html. Jeżeli ustawimy ten parametr, jako nazwa zostanie użyty nadawany przez nas unikalny ID elementów.
• chunk.section.depth - tutaj określamy, że wszystko do głębokości sekcji poziomu drugiego ma zostać rozbite na pojedyncze pliki. Głębsze obiekty nie zostaną podzielone.
• chunk.first.sections - ten parametr przyda się szczególnie, kiedy robimy spis wszystkich funkcji w naszej bibliotece. Domyślnie DocBook XSL włącza do pliku rozdziału także pierwszą znajdującą się w nim sekcję. Jednak co, jeżeli ta pierwsza sekcja zawiera już opis jakiejś funkcji? Musimy ustawić ten parametr na 1 i już wszystkie funkcje będą w osobnych plikach.
• generate.toc - w tym parametrze możemy skonfigurować, które elementy będą posiadały jakie spisy treści. Tutaj np. wyłączam tworzenie listy przykładów, tabel itd., ograniczając się wszędzie do wyświetlenia listy węzłów podrzędnych. Włączam takowe też dla sekcji, lecz aby zostały one tam uwzględnione, musimy ustawić jeszcze dla generate.section.toc.level głębokość sekcji, do której spisy treści będą wyświetlane.

Ostatnia rzecz to ładne formatowanie opisu funkcji, jakie widuje się w dokumentacji PHP, np. int imagecolorexact ( resource image, int red, int green, int blue ). Do tego celu można użyć znaczników METHODSYNOPSIS, a kod do ich odpowiedniego formatowania znajduje się w pliku common.xsl - wystarczy go stamtąd skopiować do naszego i po kłopocie.

Wyszukanie tych opcji zajęło mi trochę czasu i mam nadzieję, że ten krótki spis się komuś przyda. W przyszłości może napiszę szerszy artykuł o DocBook oraz DocBook XSL (hmmm... z tego, co pamiętam, to już w zeszłym roku się nad czymś takim zastanawiałem, więc czemu by nie teraz :)).

Powrót

• DocBook XSL: The Definitive Guide

Na Zyxist.com panuje swoboda wyrażania opinii oraz krytyki pod dowolnym adresem. Jedyny warunek: musi być ona kulturalna i rzeczowa. Na chamstwo, prostactwo lub jawne obrażanie kogokolwiek nie ma tu miejsca i takie komentarze są bardzo szybko usuwane. Jeśli zamierzasz polemizować z treścią wpisu, wpierw uważnie ją przeczytaj.