1 Docbůk Radek Hnilica2 Docbůk Radek Hnilica Věčně nedodělaná verze Vydání Vydáno Copyright 2009, 2010 Radek Hnilica Tento dokument je mým n-tým pokus...
Dle vlastní volby smíte užít tento dokument s jednou ze dvou následujících licencí. Tento dokument a všechny pˇrináležící soubory jsou publikovány pod licencí GPLv3 (http://www.gnu.org/licenses/gpl-3.0.html). Veˇcná sláva svatému RMS. Hodnˇe štˇestí. Toto dílo smíte užívat dle podmínek licence CC BY-NC-SA (http://creativecommons.org/licenses/by-nc-sa/3.0/cz/).
Pˇrehled revizí Revize new 2009-03-10 Revidoval: rfh Aktuální pracovní verze. Revize 2 2009-05-05 Revidoval: rfh Pˇrevedeno pod Debian 5.0 Lenny Revize 2 2009-12-16 Revidoval: rfh Rozšíˇrena kapitola dobˇre mínˇených rad a oprava nˇekolika pˇreklep˚u. Revize 3 2010-03-31 Revidoval: rfh Zavedeno di SCM git. Pˇridány informace o stylování. Revize 4 2010-11-02 Revidoval: rfh Zmˇeny v licenci.
ˇ Venování FIXME:napsat vˇenování
Obsah Pˇredmluva.............................................................................................................................................................. vi 1. Úvod .................................................................................................................................................................... 1 2. Co to je DocBook a proˇc vlastnˇe to všechno .................................................................................................... 2 3. Nástroje a jejich instalace ................................................................................................................................. 3 3.1. Transformaˇcní stylesheety....................................................................................................................... 3 3.2. Java .......................................................................................................................................................... 3 3.3. OpenJade ................................................................................................................................................. 3 3.4. xmllint ..................................................................................................................................................... 4 4. Debian 5.0 Lenny ............................................................................................................................................... 5 4.1. R˚uzné poznámky a nezapracované texty................................................................................................. 6 4.2. Poznámky k balíˇck˚um ............................................................................................................................. 6 5. Dokument............................................................................................................................................................ 9 6. Zpracování........................................................................................................................................................ 10 6.1. Vytváˇrení HTML................................................................................................................................... 10 6.2. Vytváˇrení postscriptu pomocí OpenJade a dsssl ................................................................................... 12 6.3. Modifikování vytváˇreného HTML ........................................................................................................ 13 7. Automatizace .................................................................................................................................................... 17 7.1. Posbírané entity ..................................................................................................................................... 17 7.2. Adresáˇrové databáze.............................................................................................................................. 17 8. Editory .............................................................................................................................................................. 18 9. Nˇekteré konstrukce a zápisy ........................................................................................................................... 19 9.1. Znakové entity ....................................................................................................................................... 19 9.2. Vkládání obrázk˚u .................................................................................................................................. 21 9.3. Obrázky malované programem pic ....................................................................................................... 22 9.4. Použití simplesect.................................................................................................................................. 23 9.5. Popis prototypu funkce.......................................................................................................................... 23 9.6. Zápis rovnic a matematických výraz˚u ................................................................................................... 24 9.7. Použití licence Creative Commons ....................................................................................................... 25 10. Dobˇre mínˇené rady a velmi špatné nápady ................................................................................................. 27
Pˇredmluva FIXME:napsat nebo nechat napsat pˇredmluvu.
vi
Kapitola 1. Úvod Jednou takhle pˇrijde do konference debian-l zpráva, a ta to všechno zaˇcala. Ted’ tady sedím, celý svˇet mˇe sere, v krku mˇe bolí, hodiny ukazují 0:40, a já píšu. No nésu u debil. Su. Zdravim, nedavno jsem se odhodlal, ze zacnu pouzivat docbook a v domeni, ze po bezmala 10 letech existence bude mit dostatecne vyladene nastroje jsem zazil nemile prekvapeni. Prvni co jsem v debianu objevil byly nastroje docbook2xxx, ktere pouzivaji SGML stylesheety. Po prvnich par neuspesnych pokusech o transformaci jednoducheho prikladu, kde jsem vzdy koncil na ceske diakritice jsem vygooglil, ze je lepsi pouzivat XML nastroje. Dalsi co jsem tedy vyzkousel bylo xmlto. Tam se mi uz konecne podarilo bezbolestne prevest docbook do html, ovsem pri prevodu do PDF jsem zacal koncit na vsemoznych TeXovych chybach. Vzdy kdyz jsem pomoci googlu nejakou odstranil, skoncilo to na jine, takze jsem to zatim vzdal. Pak jsem zkusil pouzit prevod do pdf pres FO a svete div se, na konci vypadlo PDF. Ovsem po otevreni jsem zjistil, ze misto nekterych ceskych znaku jsou "#". Takze moje otazka zni, je tu nekdo kdo v debianu pouziva docbook? A jak prinutit vyse zminene (nebo i jine) nastroje aby byly funkcni i pro cestinu? Vsude jsem zkousel kodovani utf8, ktereho se neminim vzdat. :o) Debian mam vicemene aktualni testing. Diky za nejake tipy. Mixi
Takže on za to m˚uže a všichni co mu odpovˇedˇeli. Nebýt jich tak jsem tehdy v noci klidnˇe spal a nezaˇcal psát tento zatracený dokument. Tak tedy píšu a zkouším dát dohromady všechny zkušenosti za ta léta používání a zapasení z docbookem a hlavnˇe nástroji na jeho zpracování. Souˇcástí tˇechto stránek jsou i plné zdrojové kódy, makra a použité skripty. Tedy pokud jsem na nˇeco nezapomˇel. V tom pˇrípadˇe mi dejte prosím vˇedˇet. Všechno je v balíˇcku docbook.tar.bz2. Opˇet upozorˇnuji že mezi skripty v balíˇcku a ukázkami kódu zde v dokumentu mohou být rozdíly. Totiž pˇri psaní tohoto dokumentu ladím ˇreˇcené skripty a upravuju podle potˇreby. Zahrnuji kód z jiných dokument˚u atd. Nemusím si pak nutnˇe vzpomenout že bych mohl aktualizovat ukázky zde. A nebo se mi prostˇe nechtˇelo!
1
Kapitola 2. Co to je DocBook a procˇ vlastneˇ to všechno ˇ * Tato kapitola je jen prázdná stránka. Ceká až ji nˇekdy napíšu. Jejím primárním cílem je rozpálit do bˇela všechny ty zastánce DocBooku. * Zmínit: znaˇckovací jazyk, historické programy/systémy (runof, nrof/trof/grof, tex, ...), zmínit hlavní princip oddˇelit formátování od obsahu (svatou krávou docbooku je znaˇckovat význam a formátování provádˇet na konci), ... * Odkazy, odkaz ven, odkazy napˇríˇc, odkazy jinam odkazy .... Ó svaté odkazy.
2
Kapitola 3. Nástroje a jejich instalace Pro správnou funkˇcnost budeme potˇrebovat ˇradu nástroj˚u/balíˇck˚u/program˚u, a ˇrada další je nám pak velmi nápomocna v udržování a zpracování DocBook dokument˚u. Takže které všechny nástroje budeme potˇrebovat nebo se nám budou hodit.
ˇ stylesheety 3.1. Transformacní Tyto popisují transformaci XML/SGML dokument˚u do r˚uzných formát˚u. • docbook-xsl —
xsl stylesheety
• docbook-xsl-saxon —
rozšíˇrení pro Saxon
• docbook • docbook-dsssl —
pˇriinstaluje si docbook-utils
Nainstaloval jsem v prvním pokusu docbook-xsl. # aptitude install docbook-xsl
Je tˇreba si pak prostudovat dokument /usr/share/doc/docbook-xsl/README.Debian.gz, pˇripadnˇe se podívat ještˇe na další dokumenty v adresáˇri.
3.2. Java Urˇcitˇe budeme potˇrebovat knihovny se Saxonem a pˇríslušenstvím Tak nejdˇríve malý pr˚uzkum. V Debian 5.0 Lenny máme ˇradu balíˇck˚u které by se mohly hodit. Našel jsem: Z transformaˇcních program˚u jsou k dispozici: •
xsltproc, balíˇcky: xsltproc, libxslt1.1
•
Saxon, balíˇcek: libsaxon-java
•
Xalan, balíˇcky: xalan, libxalan110. Nebo Xalan 2 balíˇcek libxalan2-java
Pro první experimenty jsem zvolil Saxon, protože jsem jej používal na pˇredchozích verzích Debianu. Doufám že tak snáze vyˇreším pˇrípadnˇe se vyskytnuvší problémy. # aptitude install libsaxon-java
Balíˇcek obsahuje mimo dva jar balíˇcky, saxon-6.5.5.jar a saxon-jdom-6.5.5.jar i spustitelný skript /usr/bin/saxon-xslt, a opˇet nˇeco málo lidského slova v /usr/share/doc/libsaxon-java/README.Debian. Xsltproc nainstalujeme jednoduše: # aptitude install xsltproc
Použití xsltproc nemám zatím odzkoušené.
3
Kapitola 3. Nástroje a jejich instalace
3.3. OpenJade # aptitude install docbook-utils
K dispozici pak máme program docbook2ps. Pˇri práci na velkém dokumentu se mi stalo, že od jistého okamžiku hlásila transformace chybu. Na konci výpisu bylo: ! TeX capacity exceeded, sorry [save size=5000].
Chyba souvisí s tím, že jsem vložením další tabulky pˇrekroˇcil velikost vyhrazené pamˇeti. Pomhla úprava konfigurace TeXu. Vytvoˇril jsem si soubor /etc/texmf/texmf.d/01local.cnf s následujícím obsahem: % Local configuration with higher priority. save_size = 20000 % for saving values outside current group
Poté aktualizujeme konfigurace pˇríkazem update-texmf a následnˇe pˇregenerujeme TeX pˇríkazem texconfig. # update-texmf # texconfig init
3.4. xmllint * Attributy: id="xmllint"
Odkazy: • •
Xmllint je program pro kontrolování xml soubor˚u a pro práci s nimi.
4
Kapitola 4. Debian 5.0 Lenny Pokusy s používáním DocBook v Debian Lenny Postup jak sprovoznit DocBook v Debian 5.0 Lenny Nainstaloval jsem ˇradu balíˇck˚u • • • docbook-xsl-saxon-gcj • docbook-xsl • docbook-xml • docbook-utils • docbook-dsssl • libsaxon-java • docbook-xsl-saxon • libsaxon-java-gcj • sun-java6-jre
Se transformace zasekne na vloženém obrázku. Žádná chyba, žádná odezva, žádný výkon procesoru. Prostˇe se vše zastaví/zasekne. Po r˚uzných experimentech jsem došel k nastavení které projde. Je to: # Xsl instalované z Lenny DB.XSL=/usr/share/xml/docbook/stylesheet/nwalsh #SAXONEXT=/usr/share/java/docbook-xsl-saxon_1.00.jar SAXONJAR=/usr/share/java/saxon-6.5.5.jar XMLPARSER=/usr/share/java/xercesImpl.jar JOPTS=
Tím ovšem nemohu použít rozšíˇrení která jsou nutná pro nˇekteré vˇec. Napˇríklad pro nastavování šíˇrky sloupc˚u v tabulce. Pˇri bližším zkoumání jsem zjistil, že používám catalog.jar, který nemám v systému. Ani v p˚uvodní istalaci Etch jsem jej nenašel.
5
Kapitola 4. Debian 5.0 Lenny Nainstaloval jsem 4.2.1, a podstatnˇe se zrychlil start a generování HTML. # aptitude install docbook-xsl-saxon-gcj
Zdá se, že problémy s extensions se podaˇrilo vyˇrešit použitím originálních pˇrímo od Walshe. Funkˇcní nastavení v Makefile vypadá takto: DB.XSL=/usr/share/xml/docbook/stylesheet/nwalsh SAXONJAR=/usr/share/java/saxon-6.5.5.jar #SAXONEXT=/usr/share/java/docbook-xsl-saxon_1.00.jar SAXONEXT=$(HOME)/lib/docbook/docbook-xsl-1.72.0/extensions/saxon65.jar XMLPARSER=/usr/share/java/xercesImpl.jar JOPTS=
Odzkoušel jsem transformaci zdroj˚u na velké knize a s r˚uznými implementacemi javy. K pˇrepínání nainstalovaných implementací jsem používal pˇríkazy: # # # #
Odkazy: • DocBook XML to PDF on Debian Lenny (http://www.jejik.com/articles/2008/12/docbook_xml_to_pdf_on_debian_lenny/)
4.1.1. Katalog *
Pokud nemáme nainstalovaná rozšíˇrení pro javu jenž umožˇnují používat katalogy, nem˚užeme transformovat dokumenty saxonem bez pˇripojení k internetu. Saxon si totiž stahuje ... # aptitude install libxml-commons-resolver1.1-java
6
Kapitola 4. Debian 5.0 Lenny
ˇ um 4.2. Poznámky k balíck ˚ 4.2.1. docbook-xsl-saxon-gcj Pˇriinstaluje si 4.2.2. V balíˇcku byly mimo jiné soubory: • /usr/lib/gcj/docbook-xsl-saxon_1.00.jar.so • /usr/share/gcj/classmap.d/docbook-xsl-saxon_1.00.jar.db • /usr/share/doc/docbook-xsl-saxon-gcj/README
Balíˇcek obsahuje javovská rozšíˇrení pro docbook saxon65.jar pˇreložená pro gcj.
4.2.2. libsaxon-java-gcj Nainstalovalo se spoleˇcnˇe s 4.2.1. Balíˇcek obsahuje mimo jiné soubory: • /usr/lib/gcj/saxon-6.5.5.jar.so • /usr/lib/gcj/saxon-jdom-6.5.5.jar.so • /usr/share/gcj/classmap.d/saxon-6.5.5.jar.db • /usr/share/gcj/classmap.d/saxon-jdom-6.5.5.jar.db
4.2.3. arbortext-catalog V popisu balíˇcku je uveden, že se Saxonem se má používat balíˇcek saxon-catalog. Related tools that provide catalog support for the Saxon and XT xslt processors are available in the saxon-catalog and xt-catalog packages.
Takový balíˇcek ovšem neexistuje!
4.2.4. libsaxon-java Z popisu balíˇcku vybírám: Závisí na: java-gcj-compat | java1-runtime | java2-runtime Navrhuje: libjdom1-java, libsaxon-java-doc Popis: The Saxon XSLT Processor The saxon package is a collection of tools for processing XML documents and implements the XSLT 1.0 recommendation, including XPath 1.0, in its entirety. Saxon is known to work well for processing DocBook XML documents with the DocBook XSL Stylesheets. Related packages make the process straightforward. Balíˇcek obsahuje mimo jiné soubory: • /usr/bin/saxon-xslt • /usr/share/java/saxon-jdom-6.5.5.jar • /usr/share/java/saxon-6.5.5.jar
Dokumentace se nachází v balíˇcku libsaxon-java-doc.
4.2.5. xsltproc
4.2.6.
4.2.7.
8
Kapitola 5. Dokument Základní cˇ ástí mé práce s docb˚ukem je xml soubor, v kterém všechny ty žvásty jsou. Když se podíváte do hlaviˇcky zjistíte že používám deklaraci:
Zde si povšimˇete, že: • •
Používám kódování utf-8, ale ono mi to funguje i s iso8859-2. Používám verzi docbooku xml/4.4/docbookx.dtd, ono mi to s vyšší nefunguje, pozdˇeji se dozvíte proˇc.
Vˇetšinu svých dokument˚u s pokouším držet v jednom souboru. Pravda nˇekdy je to dost velké xml. Ale mojim editor˚um to zas až takový problém nedˇelá. Alespoˇn od té doby co už nepoužívám pleˇcku tˇrídy Pentium na 100MHz s neskuteˇcne velkou 32MB RAM. Tak tedy vše v jednom souboru. Má to své výhody, m˚uj Emacs s nXML mi ukazuje esli je ten zpropadenej dokument validní, a dˇelá to furt. A má to taky své nevýhody, kdo se v tom má proboha vyznat, když se nechcu uˇcit zkratky pro foldování cˇ ástí dokumentu. * Ach jo. Sem si slíbil, že si koupím nastˇenku, a když už ji budu mít, pˇrišpendlím na ní lísteˇcek s tˇema zpropadenýma klávesovýma zkratkama.
Používám také více zdrojových dokument˚u. Ozvláštˇe v jednom pˇrípadˇe kterému rˇíkám vznešenˇe „adresáˇrové databáze“. Toto má své nesporné výhody. Napˇríklad m˚užu používat více xml soubor˚u. M˚užu, tedy vlastnˇe musím to tak dˇelat, pokud použiji xml soubor který je výsledkem práce nˇekterého skriptu. Viz již výše zmínˇené „databáze“, které popíši nˇekde dále. Pokud tedy používám více soubor˚u musím je nˇejak spojit dohromady. Dˇelám to tak, že v hlaviˇcce hlavního dokumentu deklaruji tyto jako externí entity. ]> * Sem bych eštˇe mel nˇeco napsat. Mno, asi jo. Tak sem nˇeco dopíšu, ale až nˇekdy pˇríštˇe. Urˇcitˇe chcete vˇedˇet co bude dál po tˇech žvástech o xml dokumentu.
9
Kapitola 6. Zpracování Toto je asi nejd˚uležitˇejší kapitola. Fakt jo. Protože, k cˇ emu je vám vlastnˇe xml dokument. No odpovím si sám. Úplnˇe k niˇcemu. Vždyt’ já chcu ty pˇekné html stránky a to PDFko. A tady to opravud zaˇcíná být zajímavé. Ale budte si muset poˇckat. Du koneˇcnˇe spat. Zátra možná nˇeco pˇridám. * kua co je to na tˇech hodinách. mˇe chcou snad nasrat. * Druhý den, tedy vlastnˇe týž den odpoledne.
Zpracování je vlastnˇe otázka nˇekolika odlišných úloh. Záleží co chceme dostat. Já jsem zaˇcínal s docbookem kv˚uli a jen kv˚uli tˇrem vˇecem. Bylo to o psaní cˇ ehokoli, pˇrevážnˇe dokumentace ze které jsem chtˇel získat tˇri výstupy: • • •
tisknutelný formát jako je Postscript a/nebo PDF vystavitelné html stránky prostý ascii text prohlížitelný na tom nejhloupˇejším terminálu
Po ˇradˇe pokus˚u a uˇcení, kdy jsem zaˇcínal pˇred mnoha lety. Jsem se cˇ asem dopracoval od sgml verze až k nynˇejší xml ve verzi DTD XML V4.4. Na prostý ASCII text jsem už zapomˇel a vytváˇrím jen tisknutelnný Postscript a PDF a html stránky bud’to jako jednu velikou, nebo kupu malých.
6.1. Vytváˇrení HTML Toto je ta jednodušší cˇ ást. Alespoˇn se to tak zdá. Když pominu ty poˇcáteˇcní problémy jak dát dohromady všechny ty vˇeci okolo Javy, jar archivy a v˚ubec všechno. Takže co, jak sem se právˇe zmínil, potˇrebujeme javu. Jak nainstalovat javu nevím. Nedˇelám to každý den a zápisky se mi ted’ nechce prohrabávat. Tˇrebas nˇekdy pozdˇeji. Takže máme javu. Pak si musíme stáhnout všechny ty jar soubory. Takže nˇekde je tˇreba vzít Saxon, a hledej šmudlo. Používám verzi 6.5.5 je to soubor který jsem umístnil do /usr/share/java/saxon-6.5.5.jar. Ostatnˇe toto je vidˇet v makefile v balíˇcku se zdroji tohoto pamfletu (docbook.tar.bz2). Je tam ˇrádek: SAXONJAR=/usr/share/java/saxon-6.5.5.jar
Takže když si seženete jinou verzi, upravíte, a m˚užete vesele experimentovat. Pak je potˇreba Xerces. Už taky nevím kde jsem ho vzal, respektive se mi v této chvíli nad tím nechce pátrat. Rovnˇež je nakopírovnán ve stejném adresáˇri jako Saxon. V makefile je pro nˇej ˇrádek XMLPARSER=/usr/share/java/xercesImpl.jar
No a samozˇrejme budeme potˇrebovat samotné xsl. V Debianu nebyly aktuální, tak jsem si je stáhl nˇekde na netu. Mám všechny tyhle vˇeci v adresáˇri $HOME/lib/docbook. Za tu dobu se mi tam nahromadila spousta smetí. Šak kukajte. radek@belix:~/lib/docbook$ ls arch docbook-dsssl-radek cvstools docbook-dsssl-snapshot dblatex docbook-xsl-1.49 docbook5-xsl-1.72.0 docbook-xsl-1.53.0 docbook-dsssl-1.76 docbook-xsl-1.54.1 docbook-dsssl-1.77 docbook-xsl-1.55.0 docbook-dsssl-1.78 docbook-xsl-1.55.0.1 docbook-dsssl-1.79 docbook-xsl-1.57.0 docbook-dsssl-cvs docbook-xsl-1.65.1
Kapitola 6. Zpracování Doslova si tento adresáˇr sebou táhnu už mnoho let. Vždycky když jsem si instaloval nový poˇcítaˇc, pˇrenesl jsem všechno ze starého a nikdy nemazal. Je tam vidˇet z cˇ ím vším jsem za tu dobu experimentoval. V makefile je nˇekolik ˇrádk˚u, teré se odkazují sem, jsou to DB=$(HOME)/lib/docbook DB.XSL=$(HOME)/lib/docbook/docbook-xsl-1.72.0 SAXONEXT=$(DB.XSL)/extensions/saxon65.jar
Ještˇe jsou v makefile popsány argumenty a spouštˇení saxonu v javˇe. Samotné spouštˇení Saxonu je definováno v ˇrádku: SAXON=java -Xms32M -Xmx128M -cp $(JARS) $(JOPTS) com.icl.saxon.StyleSheet $*
Momentálnˇe si nevzpomenu od cˇ eho jsou parametry -Xms32M a -Xmx128M, ale cˇ asem jsem je zvˇetšoval, jak se zvˇetšovali moje dokumenty. Myslím že jsem jednou nebo dvakrát narazil na strop pamˇeti a musel jsem jej uvedenými parametry zvednout. Samotná cˇ ást jenž je v makefile zodpovˇedná za vytvoˇrení html stránek je ponˇekud divoká. Trochu ji blíže popíšu. html/index.html: $(BOOKNAME).xml $(STYLESHEET) $(GENERATED) $(BOOKNAME).css docbook.tar.bz2 -rm -r html/* # Clean working directory ➊ $(SAXON) $< book.xsl >[email protected] # Create html pages ➋ cp $(BOOKNAME).css html/ # Install Stylesheet for html ➌ rm -r html/images; mkdir html/images # install images into html -cp -a $(DB.XSL)/images/* html/images/ # install "system" images ➍ -cp imgsrc/*.jpg html/images/ # install own images ➎ -cp imgsrc/photo/*.jpg html/images/ # install own images cp $(BOOKNAME).ps html/ # Add Postscript and/or PDF to html directory. ➏ cp $(BOOKNAME).pdf html/ #+ ➐ : Insert source package into html/ cp docbook.tar.bz2 html/ ➑ : Install generated html into book cache. rsync -a --delete --delete-after html/ $(HOME)/cache/book/$(BOOKNAME)/ : Be sure public directory exists and publish the book. if [ ! -d $(PUBDIR)/$(NAME) ]; then mkdir -p $(PUBDIR)/$(NAME); fi rsync -a --delete --delete-after html/ $(PUBDIR)/$(NAME)/ : Another unrelated process copy book from publish directory : into internet servers. : rsync -a -delete --delete-after html/ server::source/directory/ ➒
➊
Vyˇcistíme si pracovní výstupní adresáˇr od všech zbytk˚u, aby se nám tam nic nehromadilo. Zejména pak semtí.
➋
Zde se vlastnˇe generují html stránky. Všechny ostatní ˇrádky už je jen omáˇcka okolo a publikování.
➌
Pokud používáme css, tak tento ˇrádek jej nakopíruje do výsledného html.
➍
Zde pˇridám obrázky z distribuce XSL. Tady jsou všechny ty standardní obrázky v navigaci stránek, a i tyhle cˇ erné knoflíky s cˇ ísílky.
➎
Nakopírování vlastních obrázk˚u, tento a ještˇe ˇrádek pod ním.
➏
K webu pˇrídám i Postsript.
➐
A PDF.
➑
A v tomto pˇrípadˇe taky pˇridám balíˇcek originálních zdrojových kód˚u.
➒
A vubec. ˚ Pˇridajte si sem co chcete.
11
Kapitola 6. Zpracování
Pˇríkazy mezi knoflíky 8 a 9 posouvají vytvoˇrený adresáˇr html stránek, obrázk˚u a vložených soubor˚u jinam. Tˇreba v rámci publikování.
6.2. Vytváˇrení postscriptu pomocí OpenJade a dsssl # Transformace do Postscriptu s pomoci OpenJade a dsssl. $(BOOKNAME).ps: $(BOOKNAME).xml print.dsssl $(GENERATED) if ! [ -f variable.pages ]; then echo "0" >variable.pages; fi ➊ SP_ENCODING=utf-8 docbook2ps -d print.dsssl -V paper-type=A4 $< ➋ rsync $(BOOKNAME).ps book.ps ➌ grep ^%%Pages: $@|head -n1|awk ’{print $$2}’ >variable.pages ➍
➊
Tento ˇrádek je ponˇekud kriptický. Jeho úˇcelem je vytvoˇrit soubor variable.pages pokud ještˇe neexistuje, a zapsat do nˇej 0 jako poˇcet stran. To souvisí s mechanismem poˇcítání stran v postscriptu. Tohle není v˚ubec tˇreba, jen to zajišt’uje mnou oblíbenou možnost uvádˇet v textu dokumentu poˇcet stran tohoto dokumentu. Myslím poˇcet stran vysázených do Postscriptu a PDF. Tento konkrétní dokument má v Postscriptu už 33 stran.
➋
V tomto ˇrádku provádím vlastní vytvoˇrení postsriptu. Použije se hlavní dokument jako koˇren všech dokument˚u, použije se print.dsssl ve kterém jsou nastaveny parametry sazby jako je velikost stránky a ˇrada dalších. D˚uležité je nastavení kódování použitého ve zdrojových dokumentech. To zajišt’uje nastavení promˇenné prostˇredí SP_ENCODING. Dˇríve jsem používal kódování iso-8859-2 které m˚uže být ještˇe ve starších dokumentech. Nyní již delší dobu používám kódování utf-8. ˇ si parametru -V paper-size=A4. Je to k nevíˇre ale nadefinování velikosti Poznámka: Povšimete papíru v souboru print.dsssl mi program docbook2ps vesele ignoroval. Pohledem do zdrojového ˇ kódu zmíneného programu jsem zjistil že se mu velikost papíru dá pˇredat pomocí -V. A to již funguje jak si pˇredstavuji.
Varování Na rozdíl id Saxonu a xml nástroju, ˚ kterým je kódování v podstateˇ jedno a naˇcítají si jej z hlaviˇcky každého dokumentu, v pˇrípadeˇ OpenJade a dsssl je kódování ˇ nastavenou jen touto promennou prostˇredí. To znamená že musí být pro všechny dokumenty stejné. U xml nástroju˚ muže ˚ mít každý dokument kódování jiné.
12
➌
Vytvoˇrení „stabilního“ dokumentu pro prohlížení. Tohle v˚ubec nepotˇrebujete. To souvisí s mým zp˚usobem práce. Mohu si na soubor book.ps spustit gv, a nastavit mu „Watch file“. Tak jak se znovu vytváˇrí postscript pˇri dalších zmˇenách v zdrojovém kódu, tak se aktualizuje stránka v gv. Takže je to takový živý pohled do postsriptu. Toto na generovaném docbook.ps nefunguje, protože ten je pˇri zpracování mazán.
➍
Tento ˇrádek souvisí s zjišt’ováním poˇctu stránek ve vytvoˇreném postsriptu. Pokud tento mechanismus který je pro mne specifický nepoužíváte, nemusíte ho mít v makefile ani tento ˇrádek. Funguje tak, že se v hlaviˇcce postsriptu najde informace o poˇctu stran, a zjištˇené cˇ íslo zapíše do souboru variable.pages. Z toho vyplývá že správný poˇcet stran v tˇele dokumentu v postsriptu a pdf bude až po druhém zpracování.
Kapitola 6. Zpracování Pˇri zpracování velkých dokument˚u m˚užeme narazit na rˇadu omezení v konfiguraci TeXu. D˚uležité je najít chybové hlášení, které nám ˇríká které omezení jsme pˇrekroˇcili. Napˇríklad jsem TeX vypsal následující hlášku utopenou v seznamu chyb. ! TeX capacity exceeded, sorry [hash size=60000]. Rozšíˇrení jsem provedl zmˇenou v konfiguraˇcním souboru /etc/texmf/texmf.d/01local.cnf, do kterého jsem pˇridal následující rádku. hash_extra = 100000
Samozˇrejmˇe, že editovat soubory v adresáˇri /etc m˚uže jen root. A nesmíme také zapomenout, poté co zmˇenu provedeme, spustit program update-texm.
6.3. Modifikování vytváˇreného HTML Název „Modifikování vytváˇreného HTML“ není právˇe pˇresný. Co mám na mysli je kombinace zmˇen v xsl souboru a použítí kaskádových style sheet˚u. Nejprve tedy úpravy v XSL souboru. Jedná se o soubor jímž pˇri 6.1 toto generování rˇídíme. Napˇríklad tahle kniha ho má v pˇriloženém balíˇcku (docbook.tar.bz2) pod názvem book.xsl. Na jménu tohoto souboru nezáleží, toto jméno se pˇredává Saxonu. Já jsem si ovšem zvykl používat toto. V pˇrípadˇe tohoto dokumentu je xml v docbook.xml, xsl v book.xsl, styly v docbook.css, . . . . Tak tedy, kde jsou jednotlivé konfiguraˇcní parametry popsány? V
trasformaˇcních
sheetech
které
jsem
si
stáhl
a
používám
je
pdf
soubor
~/lib/docbook/docbook-xsl-1.72.0/docs/reference.pdf.gz. Navíc m˚užete použít m˚uj book.xsl
soubor jako šablonu a zkoušet co jednotlivé parametry dˇelají. Bez nˇejakého dalšího rozepisování uvedu spíše nˇekteré vˇeci které jsem ˇrešil v následujících sekcích.
6.3.1. Zobrazení kousku˚ kódu Code Snipets Pro tuhle potˇrebu používám nˇekde tak programlisting jinde literallayout. Zatím jsem si neujasnil co je co, ale pomalu k tomu dospívám. Nejdˇríve tedy použítí literallayout pro kousky kódu a „textové“ cˇ máranice na kousku papíru. Ukázka použítí: for file in $FILES do process-file $file done
Do výsledného HTML se vygeneruje. <pre class="literallayout">for file in $FILES do process-file $file done
Varování Pokud nenastavíme v literlallayout class na monospaced, vygeneruje se úplneˇ jiný kód. Tento používá místo tagu <pre class="literallayout"> posloupnost
a ˇrádky jsou ukonˇcovány .
13
Kapitola 6. Zpracování Ale zpátky k našemu kousku kódu, víme že se generuje do tagu pre s tˇrídou literallayout. A právˇe za tento ho ve stylu uchopíme. Styl je v souboru docbook.css a jeho použití je nakonfigurováno v book.xsl pomocí: <xsl:param name="html.stylesheet" select="’docbook.css’"/>
Do stylového souboru m˚užem tedy napsat pre.literallayout { border: 1px solid #ccc; }
Umístnˇete nyní soubor se styly k vytvoˇreným html stránkám a uvidít okolo každého kousku kódu tenký šedý rámeˇcek. Nyní máme již vše co potˇrebujem. M˚užeme tedy vytvoˇrit vlastní styl který dodá našemu dokumentu ten správný pocit. Mˇe se podaˇrilo najít obrázek proužku papíru z kroužového zápisníku. Je velmi hezký a tak jsem si jej upravil. Mám v plánu jej ještˇe pˇredˇelat, pˇrípadnˇe si takový proužek udˇelat kompletnˇe sám. S tímto obrázkem používám styl: /* * Zobrazení které se transformuje * do <pre class="literallayout">. */ pre.literallayout { background: url(images/lined_paper.gif); margin: 30px 40px; padding: 20px 1em 1em 3em; border: 0px none; border-left: 1px solid #ccc; font-family: monospace; color: #008; font-size: 14px; line-height: 20px; overflow: auto; }
6.3.1.1. Výpisy programu˚ Pokud uvádím delší kusy z kódu programu, používám k tomu tag programlisting. V XML kódu to zapisuji <programlisting>for target_class in ps pdf; do make $NAME.$target_class done if [[ ! -d html ]]; then mkdir html; fi make html/index.html
Tento kousek se transformuje v následující. for target_class in ps pdf; do make $NAME.$target_class done if [[ ! -d html ]]; then mkdir html; fi make html/index.html
V HTML stránce je generován kód který zaˇcíná <pre class="programlisting">for target_class in ps pdf; do
Máme tedy možnost ve stylech tento výpis programu chytit pomocí pravidla pre.programlisting { border: 1px dashed red; }
14
Kapitola 6. Zpracování V pravidle jsem nechal vykreslit cˇ ervený rameˇcek aby bylo vidˇet jak nám to funguje. Nˇejakou chvíli jsem si se stylem hrál, protože jsem chtˇel hezˇcí dyzajn. Vytvoˇril jsem si obrázek pro podklad který vypadá jako starý traktorový papír z dob výpoˇcetních stˇredisek. Jen tam nejsou dírky, to možná nˇekdy pˇríštˇe. Nakonec jsem skonˇcil stylu který používám i v této knize. pre.programlisting { margin: 30px 40px; padding: 0px 1em; border: 0px none; border-left: 1px dashed #ccc; border-right: 1px dashed #ccc; background: url(images/programlisting.png); font-family: monospace; color: #333; font-size: 14px; line-height: 20px; }
6.3.1.2. Použití atributu˚ tagu programlisting * * Následující programlisting má nastaven atribut role="kousek" Toto je kousek kódu v tagu <programlisting>
Ve vygenerovaném HTML najdeme: <pre class="programlisting">Toto je kousek kódu v tagu <programlisting> Další kousek programu tentokrát s atributem condition="a"
6.3.1.3. Použití atributu˚ tagu literallayout *
Toto je kousek neˇceho s ˇrádkovou strukturou. Nastavil jsem atribut role="x". A takto to vypadá ve vytvoˇreném HTML:
Toto je kousek neˇceho s ˇrádkovou strukturou. Nastavil jsem atribut role="x".
Bˇežnˇe používám tag literallayout pro zobrazení kousk˚u kódu. Dˇelám to tak, že specifikuji atribut class="monospaced". Toto je ukázka takového kousku kódu.
V HTML najdeme pak následující kód: <pre class="literallayout">Toto je ukázka takového kousku kódu. Tak literallayout pˇripouští v atributu class jen dvˇe hodnoty. class="monospaced", jak je v pˇredchozí ukázace. A class="normal", jak uvádím zde: První ˇrádek
15
Kapitola 6. Zpracování druhý ˇrádek tˇretí ˇrádek. V HTML to pak vypadá takto:
První ˇrádek druhý ˇrádek tˇretí ˇrádek.
Následující ukázka specifikuje atribut lang="bash" #!/bin/bash sort|uniq V HTML to pak vypadá:
#!/bin/bash sort|uniq
Pokud chci nˇejak ˇrídit zobrazování budu to muset ošetˇrit vnˇejaké modifikaci xslt.
ˇ 6.3.2. Použití Google Analytics pro sledování návštevnosti Po prvních experimentech s Google Analytics jsem si ˇrekl že by bylo hezké mít takto pˇrehled o návštˇevnosti svých knih. Pˇri první volné chvilce, jako toho cˇ asu nezamˇestnaný mám sem tam volnou chvilku, jsem zaˇcal pátrat po možnostech jak toho dosáhnout. Našel jsem skript v Bashi, který modifikuje jakékoliv statické stránky, ale to nebyl to co jsem chtˇel. Nakonec jsem objevi v XSL souborech DocBooku zmínku o user.footer.content. Vytvoˇril jsem si tedy konfiguraci v Google Analytics a tuto vloží do book.xsl souboru.
Kapitola 7. Automatizace Generován textu, automatické zpracování, databáze, ... * To be done:
7.1. Posbírané entity * To be done: adresᡠrové databáze’?> <section id="databaze" status="draft">
7.2. Adresáˇrové databáze * To be done:
17
Kapitola 8. Editory * Emacs, nXML, PSGML. Dˇrív jsem používal PSGML a pˇred nˇejakou dobou pˇrešel k nXML. Nˇekteré vˇeci se mi vyˇrešit nepodaˇrilo a tak jsem si musel zvyknout.
Existují i entity pro reprezentaci nˇekterých zlomk˚u. Tyto název tˇechto entit zaˇcíná frac následovaným dvˇemi cˇ íslicemi. V tabulce jsou uvedeny entity pro zlomky které jsem našel. Tabulka 9-2. Zlomky a indexy zápis
obr.
zápis
obr.
½
½
½
½
¹
1
²
2
zápis
obr.
zápis
obr.
3
³
Tabulka 9-3. Pˇrehled zlomkových entit
1 2
2
3
½
1/3
—
2/3
3
4
5
6
¼
1/5
1/6
—
2/5
¾
3/5
7
8
—
1/8
— 3/8
4/5
4
5/6
5
5/8
6 7/8
7 Pokud
20
potˇrebujeme
vkládat
písmena
ˇrecké
abecedy,
m˚užeme
použít
entity
Kapitola 9. Nˇekteré konstrukce a zápisy z následující tabulky. V tabulce jsou jen nˇekterá písmena, pokud chceme jiná, podíváme se do ISOGRK1 (http://www.w3.org/2003/entities/iso8879doc/isogrk1.html), ISOGRK2 (http://www.w3.org/2003/entities/iso8879doc/isogrk2.html), ISOGRK3 (http://www.w3.org/2003/entities/iso8879doc/isogrk3.html) nebo ISOGRK4 (http://www.w3.org/2003/entities/iso8879doc/isogrk4.html). Tabulka 9-4. Nˇekteré písmena rˇ ecké abecedy zápis
Kapitola 9. Nˇekteré konstrukce a zápisy Obrázek 9-2. Vývojový diagram
Vývojový diagram <mediaobject>
9.3. Obrázky malované programem pic *
Obrázky si m˚užeme pˇripravovat i pomocí programu groff. Takový obrázek popisujeme v textovém tvaru v jazice programu pic a poté zpracujeme groffem. Postup zpracování je uveden v následujícím ukázkovém obrázku. Obrázek 9-3. Ukázkový obrázek v PIC
9.4. Použití simplesect Tato sekce obsahuje jednoduché sekce zapisované tagem simplesect. Takto zapisované sekce nemohou mít vlastní podsekce. Jsou to tedy z hlediska struktury dokumentu listy stromu.
9.4.1. První jednoduchá sekce Obsahem této jednoduché sekce je nic neˇríkající tlachání.
9.4.2. Druhá jednoduchá sekce Obsahem této jednoduché sekce je taky nic neˇríkající tlachání.
9.4.3. Do tˇretice tˇretí jednoduchá sekce Obsahem této jednoduché sekce je zas a opˇet nic neˇríkající tlachání.
9.5. Popis prototypu funkce Nejdˇríve zápis prototypu funkce, která nevrací žádnou hodnotu a nemá žádné parametry. void interrupts A takto to vypadá v dokumentu. void interrupts(void);
Pokud funkce vrací nˇejakou hodnotu, napˇríklad cˇ íslo
23
Kapitola 9. Nˇekteré konstrukce a zápisy int interrupts
int interrupts(void);
Další ukázka. intinterrupts
int interrupts(void);
Argumtenty funkce zapisujeme do tagu paramdef. Každý do samostatného tagu. Napˇríklad funkce se dvˇema parametry analogWrite se zapíše takto: void analogWrite <paramdef>int <parameter>pin <paramdef>int<parameter>value
void analogWrite(int pin, intvalue);
Metoda bez parametru a bez návratové hodnoty. <methodsynopsis> <methodname>begin void begin();
Metoda s jedním parametrem. <methodsynopsis> <methodname>begin <methodparam>int <parameter>cislo void begin(int cislo);
24
Kapitola 9. Nˇekteré konstrukce a zápisy
9.6. Zápis rovnic a matematických výrazu˚ *
Odkazy: • equation (http://www.docbook.org/tdg/en/html/equation.html) • inlineequation (http://www.docbook.org/tdg/en/html/inlineequation.html) • informalequation (http://www.docbook.org/tdg/en/html/informalequation.html) Pro zápis matematických výraz˚u jsou urˇceny tagy: equation, a inlineequation. Starší nástroje, tedy ty co používám, neumožˇnují jednoduše pˇrímo zapisovat matematické výrazy do XML. Pˇresnˇeji neumí je transformovat. Proto matematické výrazy a rovnice sázím v jiném systému, konktrétnˇe používám groff. Pomocí tohoto programu vytvoˇrím postscript který použiji pˇri tvorbˇe postscriptové a PDF verze a z toho postscriptu PNG obrázky rovnic pro HTML verzi. <equation> Napˇetí a proud cívkou <mediaobject>
Pokud se rozhodneme publikovat náš dokument pod licencí Creative Commons, potˇrebujeme toto zapsat na správná místa v souborech. Zaˇcneme zápisem do zdrojového docbook xml souboru. Licenci uvedeme v bookinfo tagem legalnotice. M˚užeme sem zapsat tˇreba následující odstavec (para).
<para> Toto dílo smíte užívat dle podmínek licence CC BY-NC-SA. <mediaobject>
Použitý obrázek jsem stáhl z Creative Commons (http://creativecommons.org) a pˇrevedl na mnou používané formáty. Pokud chceme, m˚užeme umístnit odkaz na licenci na každou generovanou HTML stránku. Toho dosáhneme zmˇenou v souboru book.xsl <xsl:template name="user.footer.navigation">
