Scott Tiger Tech Blog

Blog technologiczny firmy Scott Tiger S.A.

DocBook

Autor: Piotr Karpiuk o wtorek 29. Listopad 2011


Wygenerowany z DocBooka format Web Help. Projekt powstał powstał podczas Google Summer of Code 2010. Kliknij aby obejrzeć na żywo.

Dokumentacja produktów firmy informatycznej – w jakim formacie i jak wyobrażamy sobie optymalny proces jej wytwarzania? Często traktowana po macoszemu, powstaje ad hoc w MS Wordzie. Tymczasem chciałoby się mieć:

  • spójny wygląd dokumentów firmy,
  • tak naprawdę przydałyby się różne formaty wynikowe: przynajmniej PDF do wydruku i HTML do dokumentacji online,
  • możliwość przeszukiwania i wygodnego przeglądania wszystkich dokumentów dotyczących jednego produktu, ale może również dokumentów wszystkich produktów firmy,
  • wersjonowanie, z możliwością ustalenia kto, kiedy, gdzie i dlaczego naniósł jakieś poprawki,
  • fragmenty dokumentacji mogłyby być generowane automatycznie, np. z komentarzy w kodzie źródłowym lub ze schematu bazy danych.

Dziś będzie o DocBooku, który moim zdaniem z gracją odnosi się do tak postawionych wymagań. Na początek kliknij w rysunek po prawej, który przedstawia jeden z możliwych docelowych formatów dokumentacji wygenerowanej z tego narzędzia. Zwróć uwagę na pełnotekstowe przeszukiwanie i spis treści w postaci drzewka.

O ile MS Word to edytor, DocBook to język. Dokładniej, jest to DTD definiujący składnię dokumentów XMLa (wprowadza ok. 400 tagów) i pozwalający je zwalidować (jeszcze dokładniej są to RelaxNG i Schematron, ale przymrużmy oko i potraktujmy je jako odpowiedniki DTD, tym bardziej że DTD i innego typu schematy też istnieją). Aby otrzymać konkretny dokument w postaci PDF czy HTML należy jeszcze użyć arkuszy XSL (dostarczanych z DocBookiem, przez społeczność lub własnych) i dokonać transformacji (tego typu narzędzia potrafią też automatycznie wygenerować spis treści i indeks). Całość przedstawia schematycznie poniższy rysunek:

Za pomocą DocBooka można składać zarówno artykuły, strony pomocy (ang. man pages), jak i książki. Używa się powszechnie konwerterów do formatów XHTML, PDF (zarówno za pomocą LaTeXa – narzędzie dblatex – jak i FO), RTF, Web Help, PostScript, EPUB (książki elektroniczne), a także OpenOffice. Zwraca uwagę brak formatu MS Worda, ale w tym procesorze tekstu można otworzyć RTF (format stworzony przez Microsoft).

Jak wspomniałem, dokumenty DocBooka to pliki tekstowe (XML), więc podobnie jak kod źródłowy programów można je edytować w dowolnym edytorze tekstu i w pełni wykorzystać wszystkie zalety systemów kontroli wersji takich jak SVN, Git czy CVS. Dowolne fragmenty tego XMLa mogą być generowane automatycznie. Możemy sobie podefiniować własne tagi i napisać preprocesor, który napotykając tag

    <oracle connect-string="jdbc:oracle:thin:@//myhost:1521/orcl"
            schema="SYS_KIWI" function="GEN_TABLE_DOC" params="OSOBY"/>

połączy się z bazą danych, wykona jakąś procedurę składowaną a sam tag zastąpi wynikiem tej procedury.

DocBook jest językiem semantycznym, nie zawiera żadnych informacji o formatowaniu, skupia się na znaczeniu swoich konstrukcji. Przykładowo, zamiast wyjaśniać jak streszczenie dokumentu (ang. abstract) ma być wizualnie formatowane, DocBook po prostu definiuje, że określony fragment jest streszczeniem – zewnętrzne narzędzia przetwarzające decydują jak to streszczenie będzie wyglądało w ostatecznym dokumencie, a nawet czy w ogóle się tam znajdzie. Wyraźne rozdzielenie semantyki od prezentacji ma swoje dalsze konsekwencje – zdecydowanie ułatwia działanie wszelkim mechanizmom przeszukującym zawartość firmowej dokumentacji.

Czas już pokazać jakiś prosty dokument:

       <?xml version="1.0" encoding="UTF-8"?>
       <book xml:id="simple_book" xmlns="http://docbook.org/ns/docbook" version="5.0">
         <title>Very simple book</title>
         <chapter xml:id="chapter_1">
           <title>Chapter 1</title>
           <para>Hello world!</para>
           <para>I hope that your day is proceeding <emphasis>splendidly</emphasis>!</para>
         </chapter>
         <chapter xml:id="chapter_2">
           <title>Chapter 2</title>
           <para>Hello again, world!</para>
         </chapter>
       </book>
    

Podczas edycji można zagnieżdżać dwie inne znane aplikacje XML: MathML (do tworzenia wzorów matematycznych) oraz SVG (do osadzania grafiki wektorowej).

Inne cechy DocBooka świadczące na jego korzyść

  • Ma już 20 lat (rozpoczął się w 1991 roku jako wspólny projekt firm HaL Computer Systems i O’Reilly, później rozwijały go m.in. Novell, DEC, Hewlett Packard, Sun Microsystems, SCO, Fujitsu, Hitachi, Unisys; obecnie jest utrzymywany przez OASIS). Pociąga to za sobą bogatą dokumentację, FAQ, opis wszystkich tagów oraz co najmniej dwie książki: DocBook 5: The Definitive Guide (dostępna online), oraz DocBook XSL: The Complete Guide (również online).
  • Jest projektem opensource, więc jego wdrożenie nie wiąże się z większymi wydatkami.
  • DocBook jest powszechnie używany do tworzenia dokumentacji w takich projektach jak FreeBSD, KDE, GNOME, GTK, jądro Linuksa, Linux Documentation Project, a także Darwin Documentation Project (Apple). Korzystają z niego m.in. takie firmy jak Caldera Systems, Mandrakesoft, Red Hat i SuSE.
  • Jest rozszerzalny. Właściwie DocBook to po prostu DTD który można zmodyfikować na własny użytek, a do generowania dokumentów wynikowych używa się standardowego stosu narzędzi przetwarzających XML i arkuszy stylu XSL. Zamiast zatem wykorzystywać standardowe arkusze, można potworzyć własne tak aby wszystkie firmowe dokumenty miały spójny wygląd i zawierały nazwę firmy oraz logo.

Wady:

  • w powszechnym odczuciu XML nie jest przyjaznym dla człowieka formatem w porównaniu z możliwościami oferowanymi przez współczesne procesory tekstu – na szczęście powstały edytory XML typu WYSIWYG, takie jak XMLMind (XXE, wersja Standard jest bezpłatna i zawiera wszystko co potrzeba do edycji dokumentów DocBooka), oraz Oxygen,
  • mniejsza kontrola nad szczegółami układu w porównaniu z procesorami tekstu – gdy ktoś się uprze żeby na jednej konkretnej stronie ustawić jakiś element z dokładnością do milimetra inaczej niż robi to szablon, to niestety pozostaje tylko modyfikacja szablonu lub wynikowego dokumentu,
  • DocBook to język, a więc trzeba się go nauczyć.


Screencast pokazujący jak używać XMLMind. Kliknij aby obejrzeć. Polecam również inne screencasty do nauki tego edytora

Jeśli chodzi o edycję plików źródłowych DocBooka – a więc XMLa – to pomiędzy wspomnianymi wyżej edytorami WYSIWYG a windowsowym Notatnikiem jest jeszcze cała gama edytorów pokazujących XMLowe flaki, ale znacząco ułatwiających edycję – np. poprzez walidację online, podpowiadanie tagów zgodnie z definicją DTD języka, czy choćby automatyczne domykanie znaczników lub zwijanie fragmentów których nie chcemy w danym momencie oglądać. Sam używam na codzień Emacsa z trybem nXML i sprawdzaniem pisowni, co w zupełności mi wystarcza. Jeszcze inne podejście oferuje narzędzie wiersza poleceń o nazwie AsciiDoc. Definiuje ono czytelny dla człowieka format plików tekstowych (patrz przykład) i konwertuje go np. do DocBooka. Jak się można domyślać, do prostych dokumentów jest idealny, ale gdy trzeba np. wstawić tabelkę, to pojawiają się problemy.

Share and Enjoy:
  • del.icio.us
  • Facebook
  • Google Bookmarks
  • Śledzik
  • Blip
  • Blogger.com
  • Gadu-Gadu Live
  • LinkedIn
  • MySpace
  • Wykop

Zostaw komentarz

XHTML: Możesz użyć następujących tagów: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>