1. Zamiana dokumentu Docbook na poprawny dokument XHTML

1. Zamiana dokumentu Docbook na poprawny
dokument XHTML
t.przechlewski 2007, Dokument może być modyfikowany/rozpowszechniany na licencji Creative Commons Attribution License [CC-BY 2.5]
1.1. Generowanie poprawnego dokumentu XHTML
Procesory XSLT, takie jak Saxon czy Xsltproc, od pewnego czasu potrafią zamienić format DocBook XML na XHTML przy wykorzystaniu arkuszy XSL [http://sourceforge.net/projects/docbook]
Normana Walsha (dalej określanych jako DBXSL). Jak to zrobić jest opisane w rozdziale 24 znanego podręcznika Boba Staytona DocBook XSL: The Complete Guide [http://www.sagehill.net/docbookxsl/OtherOutputForms.html#Xhtml]. Ten tekst dotyczy wersji 1.72 arkuszy DBXSL.
Postępując zgodnie z zaleceniami z podręcznika Staytona udało mi się otrzymać poprawny dokument
XHTML tylko w przypadku zastosowania procesora xsltproc. Zwykle przeze mnie używany saxon
zaśmiecał dokument dziwnymi i niepotrzebnymi przestrzeniami nazw. Niestety ten poprawny dokument
XHTML nie zawsze jest dobrze wyświetlany w przeglądarkach. Przykładowo polecenie script wstawiane jako:
<script type="text/javascript" src="foo.js">
nie działa poprawnie w przypadku Internet Explorera (wersja 6), który upiera się przy zapisie:
<script type="text/javascript" src="foo.js"></script>
Ten tekst zawiera rekapitulację zaleceń zawartych w ww. podręczniku wraz z niezbędnymi uzupełnieniami,
które poprawiają sposób jego wyświetlania w przeglądarkach.
Wszystkie niezbędne zmiany dotyczące arkuszy XSLT należy umieścić w arkuszu ,,adaptującym'' a następnie ten plik podawać jako argument przy uruchamianiu procesora XSLT, tj.:
<xsl:import href="/usr/local/sgml/stylesheets/xmldocbook/1.72.0/xhtml/docbook.xsl"/
<xsl:output method="xml"
encoding="iso-8859-2"
doctype-public="-//W3C//DTD XHTML 1.1//EN"
doctype-system="http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd" />
Procesor xsltproc uruchamiamy w następujący sposób:
xsltproc --stringparam chunker.output.doctype-public \
"-//W3C//DTD XHTML 1.0 Strict//EN" \
--stringparam chunker.output.doctype-system \
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd" \
-o plik.wy dbx2xhtml-pl.xsl plik.xml
gdzie dbx2xhtml-pl.xsl, to nazwa arkusza ,,adaptującego''.
Otrzymany plik XHTML będzie poprawny jeżeli do pliku dbx2xhtml-pl.xsl dodamy następujące
deklaracje:
<!-- see: http://www.sagehill.net/docbookxsl/OtherOutputForms.html -->
1
Zamiana dokumentu Docbook
na poprawny dokument XHTML
<xsl:param name="css.decoration" select="0"/>
<xsl:param name="ulink.target" select="''"/>
<xsl:param name="make.graphic.viewport" select="0"/>
<xsl:param name='html.longdesc ' select='0'/>
<!-- generate id='foo' not name='foo': -->
<!-- uwaga: jeżeli ustawimy poniższy parametr na 1,
to xsltproc generuje duplikaty @id -->
<xsl:param name="generate.id.attributes" select="0" />
Dodatkowo należy przedefiniować szablon <xsl:template name="language.attribute">
znajdujący się w pliku ~/common/l10n.xsl (znak ~ oznacza ,,korzeń'' dystrybucji pakietu stylów
docbook-xsl) ponieważ wstawia on błędny atrybut lang, zamiast xml:lang. Zmiana jest bardzo
prosta:
<xsl:attribute name="xml:lang"> <!-- zamiast name="lang" -->
tyle, że cały, dość długi szablon <xsl:template name="language.attribute"> trzeba przepisać in extenso
Plik powinien być w tym momencie poprawny, ale żeby obejść błędy przeglądarek trzeba go poprawić. Ja
w tym celu wykorzystuję bardzo prosty skrypt Perla:
#!/usr/bin/perl
while (<>) {
s/(<script[^<>]+)\/>/\1><\/script>/g; # <script> -> <script></script>
s/(<a id[^<>]+)\/>/\1><\/a>/g; # <a id='foo'/> -> <a id='foo'></a>
print $_; }
1.2. Modyfikowanie sposobu formatowania dokumentu
XHTML
Poniższe szablony pozwalają dodać paginę górną i dolną do każdej wygenerowanej strony XHTML oraz
dopisać niezbędne elementy do nagłówka strony (element html/head):
<xsl:template name="user.head.content">
... dodaje zawartość do elementu head ...
</xsl:template>
<xsl:template name="user.header.content">
... dodaje zawartość przed zasadniczą treścią strony ...
</xsl:template>
<xsl:template name="user.footer.content">
... dodaje zawartość po zasadniczej treści strony ...
</xsl:template>
Powyższy sposób jest poprawny jeżeli generujemy dokument do jednego pliku, za pomocą szablonu ~/
xhtml/docbook.xsl (~ oznacza korzeń dystrybucji arkuszy stylów). Jeżeli używamy szablonu ~/
xhtml/chunk.xsl do zamiany dokumentu DocBook na dokument XHTML podzielony na wiele plików, to aby nasze paginy wypadły nad panelami nawigacyjnymi wstawianymi automatycznie należy raczej zmodyfikować szablony user.header.navigation i user.footer.navigation a nie
user.header.content oraz user.footer.content. (Por. też DocBook XSL: The Complete Guide [http://www.sagehill.net/docbookxsl/HtmlCustomEx.html#HTMLHeaders]) BTW, modyfikacja
user.header.navigation i user.footer.navigation będzie zapewne poprawnym rozwią2
Zamiana dokumentu Docbook
na poprawny dokument XHTML
zaniem także w przypadku wykorzystywania ~/xhtml/docbook.xsl. Więcej szczegółów dotyczących generowania poprawnego dokumentu XHTML, podzielonego na wiele plików zawiera punkt Sekcja 1.3, „Zamiana na dokument XHTML podzielony na wiele plików” .
Często pagina dolna będzie zawierała guzik ,,Powrót'' z odsyłaczem do poprzedniej strony. URL tej strony
podaję z wiersza poleceń, uruchamiając procesor xsltproc z odpowiednim argumentem:
--stringparam My.back.page "../../index.html"
Porządne dokumenty XHTML zawierają także datę ostatniej modyfikacji. Do tego celu także wykorzystuję
argument wiersza poleceń:
--stringparam My.current.date "`LANG=C date`"
Powyższe zadziała oczywiście tylko w systemie Linux/Unix. Niestety systemy suboptymalne mają tę wadę, że pewnych rzeczy nie da się przy ich pomocy zrobić:-) Zapis LANG=C powoduje, że data wydrukowana za pomocą polecenia date będzie w języku angielskim.
1.3. Zamiana na dokument XHTML podzielony na wiele
plików
Zmianę sposobu kodowania znaków, sposobu formatowania dokumentu czy też rodzaju wstawianych identyfikatorów doctype-public/doctype-system można osiągnąć za pomocą następujących deklaracji:
<xsl:param name="chunker.output.encoding" select="'iso-8859-2'"/>
<xsl:param name="chunker.output.indent" select="'yes'"/>
<xsl:param name="chunker.output.doctype-public" select="'-//W3C//DTD XHTML 1.1//EN'
<xsl:param name="chunker.output.doctype-system"
select="'http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd'"/>
W szczególności ~/xhtml/chunk.xsl nie korzysta z nastawień dotyczących rodzaju kodowania znaków, formatowania dokumentu (atrybut indent) czy też rodzaju wstawianych identyfikatorów (atrybuty
doctype-public i doctype-system), deklarowanych za pomocą stosownych atrybutów elementu
<xsl:output>.
Jeżeli
wartości
parametrów
chunker.output.doctype-public
oraz
chunker.output.doctype-system zadeklarujemy w arkuszu ,,adaptującym'', to oczywiście parser xsltproc, można uruchomić, wpisując po prostu:
xsltproc -o plik.wy dbx2xhtml-pl.xsl plik.xml
Przy czym, w przypadku generowania wielu plików (tj. wykorzystania ~/xhtml/chunk.xsl), cześć
-o plik.wy, należy pominąć
Arkusze DBXSL wstawiają panele nawigacyjne, definiowane za pomocą tabeli (<table>), wykorzystując niepoprawny w standardzie XHTML atrybut width, elementu td. Ponieważ ww. panele
są definiowane ,,na sztywno'' (nie są sparametryzowane), więc jedynym sposobem na poprawny plik
XHTML jest albo wyłączenie generowania paneli (parametry suppress.footer.navigation,
suppress.header.navigation i/lub suppress.navigation) albo przedefiniowanie szablonów:
<xsl:template name="header.navigation"> ... </xsl:template>
<xsl:template name="footer.navigation"> ... </xsl:template>
3
Zamiana dokumentu Docbook
na poprawny dokument XHTML
Należy w tym celu z pliku ~/xhtml/chunk-common.xsl skopiować odpowiednie definicje szablonów, umieścić je w arkuszu ,,adaptującym'' a następnie usunąć z nich wszystkie wystąpienia atrybutu
width w kontekście elementu td.
1.4. Pliki do pobrania
Szablon dbx2xhtml-pl.xsl [./dbx2xhtml-pl.xsl]. Automatyzujący wszystko plik Makefile [./Makefile], plik Perla do poprawienia dokumentu XHTML xhtml2xhtml.pl [./xhtml2xhtml.pl], wszystko spakowane w pliku zip [./db2xhtml.zip].
Szablon dbx2xhtml-pl-chunk.xsl [./dbx2xhtml-pl-chunk.xsl], do zamiany na wieloplikowy dokument XHTML. Automatyzujący wszystko plik Makefile [./Makefile.chunks].
Zobacz też DocBook, praktyczne wykorzystanie standardu XML [http://gnu.univ.gda.pl/~tomasz/sgml/
dbintro.tp/bachotek2003/bach2003db/dbt.html].
Ten dokument w formacie: pdf [./db2xhtml.pdf] oraz xml [./db2xhtml.xml].
4