1. Zamiana dokumentu Docbook na poprawny dokument XHTML
Transkrypt
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