Poniższy opis powstał w dużej mierze na podstawie dokumentacji dla Ubuntu. Aby nie powtarzać tych samych informacji polecam na początek zapoznać się z nią i dopiero wtedy wrócić na tą stronę. Nie jest to jednak konieczne ponieważ część informacji zostanie powtórzona. Zostaną również przedstawione dodatkowe przykłady nie zawarte w dokumentacji Ubuntu.
Instalacja
Instalujemy następujące pakiety: xsltproc, docbook-xsl, docbook-defguide
sudo apt-get install xsltproc docbook-xsl docbook-defguide
Przykład 1
Pierwszy przykład pokazuje podstawową strukturę dokumentu DocBooka. Tutaj konkretnie mamy artykuł (article). Do innych typów dokumentów jakie możemy utworzyć można zaliczyć: książkę (book), część (part), rozdział (chapter),sekcję (section), dodatek (appendix), odwołanie (refentry), wykaz haseł (glosary). Każdy z tych typów ma oczywiście inną formę, dlatego warto zapoznać się wcześniej z oficjalną dokumentacją.
Plik article1.xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<article>
<articleinfo>
<title>Artykuł</title>
<author>
<firstname>Rafał</firstname>
<surname>Petryniak</surname>
<affiliation>
<orgname></orgname>
</affiliation>
</author>
<pubdate>2009.01.03</pubdate>
</articleinfo>
<section>
<title>Sekcja pierwsza</title>
<para>treść</para>
</section>
</article>
Transformacją naszego dokumentu zajmie się zainstalowany przez nas xsltproc. Na wejście podajemy mu nazwę pliku do przetworzenia (article1.xml), nazwę pliku wynikowego (output.html) oraz plik styli xsl (warto zajrzeć do katalogu /usr/share/xml/docbook/stylesheet/nwalsh/, aby zobaczyć jakie inne formaty wyjściowe mamy jeszcze dostępne).
xsltproc -o output.html /usr/share/xml/docbook/stylesheet/nwalsh/xhtml/docbook.xsl article1.xml
Przykład 2
Kiedy już utworzymy kilka plików DocBooka, niewygodnym może się okazać generowanie wyjścia dla każdego z osobna. W takim przypadku najwygodniej przygotować sobie plik Makefile, który zrobi to za nas.
Plik Makefile
TARGETS = article1.html article1-copy.html
XSLTPROC = /usr/bin/xsltproc
XSL = /usr/share/xml/docbook/stylesheet/nwalsh/xhtml/docbook.xsl
%.html: %.xml $(XSL)
@$(XSLTPROC) -o $@ $(XSL) $<
all: $(TARGETS)
clean:
@rm -f *.html
Teraz wystarczy już wpisać make w konsoli i po chwili zobaczymy pliki wyjściowe.
Przykład 3
Kolejne dwa przykłady pokazują jak sobie poradzić, kiedy mamy do napisania dużą dokumentację i chcielibyśmy rozbić ją na kilka plików.
W pierwszym sposobie skorzystamy z encji zewnętrznych. Dzięki nim możemy do wybranych przez nas zmiennych przypisać zawartość plików podrzędnych, a później wstawić ją w dowolnym miejscu dokumentu. Po przeanalizowaniu poniższych plików wszystko powinno się wyjaśnić.
Plik article3.xml
<?xml version="1.0" encoding="UTF-8"?>Plik article3a.xml
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY sekcja1 SYSTEM "article3a.xml">
<!ENTITY sekcja2 SYSTEM "article3b.xml">
]>
<article>
<articleinfo>
<title>Artykuł</title>
<author>
<firstname>Rafał</firstname>
<surname>Petryniak</surname>
<affiliation>
<orgname>Politechnika Krakowska</orgname>
</affiliation>
</author>
<pubdate>2009.01.03</pubdate>
</articleinfo>
&sekcja1;
&sekcja2;
</article>
<section>Plik article3b.xml
<title>Sekcja pierwsza</title>
<para>treść</para>
</section>
<section>
<title>Sekcja druga</title>
<para>treść</para>
</section>
Całość kompilujemy podobnie jak w przykładzie pierwszym, wydając polecenie:
xsltproc -o output.html /usr/share/xml/docbook/stylesheet/nwalsh/xhtml/docbook.xsl article3.xml
Przykład 4
Ostatni już przykład również pozwala na łączenie dokumentów, tylko tym razem z wykorzystaniem XML Inclusions. Główną zaletą tego podejścia jest możliwość definiowania zagnieżdzeń bardziej złożonych, aniżeli dokument główny - dokumenty podrzędne (przykład 3).
Plik article4.xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<article xmlns:xi="http://www.w3.org/2001/XInclude">
<articleinfo>
<title>Artykuł</title>
<author>
<firstname>Rafał</firstname>
<surname>Petryniak</surname>
<affiliation>
<orgname>Politechnika Krakowska</orgname>
</affiliation>
</author>
<pubdate>2009.01.03</pubdate>
</articleinfo>
<xi:include href="article3a.xml" parse="xml" encoding="utf-8" />
<xi:include href="article3b.xml" parse="xml" encoding="utf-8" />
</article>
Aby skompilowac ten przykład będziemy musieli dodać kolejny parametr dla polecenia xsltproc, a mianowicie --xinclude. Całość wygląda tak:
xsltproc --xinclude -o test.html /usr/share/xml/docbook/stylesheet/nwalsh/xhtml/docbook.xsl article4.xml
Edytory
Listę dostępnych edytorów DocBooka również można znaleźć w dokumentacji Ubuntu. Ja ze swej strony do bardziej zaawansowanych dokumentów polecam XML Mind Editor, a do zupełnie podstawowych wystarczy edytor tekstowy kolorujący składnię.
3 komentarze:
dzięki za to wprowadzenie, przydało się
--
pozdrawiam
Tomek
masz tam buga, brakuje "e" w tej linijce: "sudo apt-get install xsltproc docbook-xsl docbook-defguid" powinno być "sudo apt-get install xsltproc docbook-xsl docbook-defguide"
Poprawione. Dzięki za przetestowanie i uwagi.
Prześlij komentarz