niedziela, 4 stycznia 2009

DocBook w Ubuntu - jak zacząć

Dłuższy czas temu przygotowałem dla studentów instrukcję jak używać DocBooka do pisania dokumentacji technicznej. Opis dotyczył systemu Windows. Jako, że sam korzystam teraz głównie z Linuksa i wielu studentów również preferuje ten system, czas na mały starter właśnie dla Linuksa.
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"?>

<!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>
Plik article3a.xml
<section>
<title>Sekcja pierwsza</title>
<para>treść</para>
</section>
Plik article3b.xml
<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:

Anonimowy pisze...

dzięki za to wprowadzenie, przydało się

--
pozdrawiam
Tomek

Anonimowy pisze...

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"

Rafał Petryniak pisze...

Poprawione. Dzięki za przetestowanie i uwagi.

Prześlij komentarz