4. Usare DocBook

Una volta che tutto è installato, è tempo di verificare quanto fatto e vedere come usare openjade e gli altri strumenti.

Figura 1. File di esempio DocBook SGML - test.sgml

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN">

<article lang="en">
<articleinfo>
	<title>This is a Test</title>

	<author>
		<firstname>John</firstname>
		<surname>Doe</surname>
		<othername role="mi">L</othername>
		<affiliation>
			<address>
			<email>j.doe@jdoe dot com</email>
			</address>
		</affiliation>
	</author>

	<revhistory>
		<revision>
		<revnumber>v1.0</revnumber>
		<date>2000-12-30</date>
		<authorinitials>jld</authorinitials>
		</revision>
	</revhistory>

	<abstract>
	<para>
	This is a test DocBook document.
	</para>
	</abstract>

</articleinfo>

<sect1 id="test1">
<title>Test 1</title>
<para>
Test section 1.
</para>
	<sect2>
	<title>Test 1.1</title>
	<para>
	Test section 1.1
	</para>
	</sect2>

	<sect2>
	<title>Test 1.2</title>
	<para>
	<screen>
		-- Test section 1.2
		openjade -t sgml -d $DSLFILE test.sgml
	</screen>
	</para>
	</sect2>

</sect1>

<sect1 id="test2">
<title>Test 2</title>
<para>
Test section 2.
</para>

	<sect2>
	<title>Test 2.1</title>
	<para>
	Test section 2.1
	</para>
	</sect2>

	<sect2>
	<title>Test 2.2</title>
	<para>
	Test section 2.2
	</para>
	</sect2>

</sect1>
</article>
	
Per una guida a DocBook ed una spiegazione degli elementi DocBook, si veda:

DocBook: The Definitive Guide. http://www.docbook.org/tdg/en/

4.1. Generazione di HTML

4.1.2. ldp.dsl

Con il file ldp.dsl, il risultato sarà migliore:

  • Le informazioni sull'articolo sono contenute in un file "index" appositamente creato.

  • È stato generato automaticamente un indice.

  • Ogni sezione <sect1> è contenuta in un proprio file.

  • I nomi dei file sono derivati dagli attributi ID degli elementi <sect1>.

  • L'estensione dei file è cambiata in html.

  • Gli elementi <screen> sono ombreggiati.

Si noti come il file ldp.dsl è stato scritto nella linea di comando: vi sono aggiunti i caratteri "#html". ldp.dsl contiene due elementi <STYLE-SPECIFICATION>, uno con l'attributo ID="html" e l'altro con ID="print". Questo seleziona lo stile html all'interno del file ldp.dsl. Il DSSSL DocBook contiene il supporto per convertire i file DocBook nei formati html e per la stampa. Nella sezione 3.3, si è copiato il file ldp.dsl all'interno di entrambe le directory print e html. Quando si genera un output html, si dovrebbe selezionare lo stile html come fatto sopra. Quando si generano altri tipi di file, quali rtf e tex, questi rientrano nello stile di stampa e quindi si dovrebbe selezionare tale stile dal ldp.dsl. L'alternativa è di commentare o cancellare lo stile di stampa o lo stile html nelle copie di ldp.dsl nelle relative directory. Se un file dsl contiene più di una specifica di stile e nessuna viene selezionata, come nel precedente esempio, allora risulterà selezionato il primo stile incontrato nel file. Nel file ldp.dsl il primo stile presente è quello di stampa, che quindi è quello selezionato per definizione. Di conseguenza, nell'esempio precedente, non aggiungendo la specificazione di stile "#html" all'indicazione del file ldp.dsl quale foglio di stile dsssl, risulterà selezionata, ed utilizzata per generare html, la specifica di stile "print". Funzionerà, ma la resa sarà diversa, poiché è pensata per essere selezionata all'interno del contesto print/ldp.dsl.

Per imparare di più su come sono realizzate le personalizzazioni dei fogli di stile, si legga la documentazione per i Modular DocBook Stylesheets. Le personalizzazioni essenzialmente interessano impostazioni di parametri booleani per selezionare o deselezionare le diverse caratteristiche dello stile. Si può programmare una logica di stile completamente nuova utilizzando il linguaggio DSSSL.

L'opzione di openjade "-t tipo_di_output" specifica il tipo di output. L'opzione "-d dsssl_spec" è il percorso del foglio di stile dsssl da utilizzare. Nell'esempio precedente, il tipo di output specificato è l'sgml, che è utilizzato per le trasformazioni da SGML a SGML. L'HTML, definito attraverso la HTML Document Type Definition (DTD), è un documento di tipo SGML, come lo è DocBook, quindi "sgml" è la corretta opzione per il tipo di output. Gli altri due tipi di output comunemente usati sono "rtf" e "tex". L'opzione tex verrà usata in seguito come formato intermedio per la generazione di file nel formato pdf e ps. L'opzione dsssl_spec deve indicare un file dsl, non una directory.

4.2. Generazione di rtf e tex

bash$ ls -l
-rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
bash$ openjade -t rtf -d $SGML_SHARE/dsssl/docbook/print/ldp.dsl#print test.sgml
bash$ openjade -t tex -d $SGML_SHARE/dsssl/docbook/print/ldp.dsl#print test.sgml
bash$ ls -l
-rw-r--r--   1 reaster  users        4584 Dec 31 20:51 test.rtf
-rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
-rw-r--r--   1 reaster  users       18719 Dec 31 20:51 test.tex
	

4.3. Generazione di dvi e ps

Figura 4. Esecuzione di jadetex per generare un file Device Independent (dvi).

-rw-r--r--   1 reaster  users        4584 Dec 31 20:51 test.rtf
-rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
-rw-r--r--   1 reaster  users       18719 Dec 31 20:51 test.tex
bash$ jadetex test.tex
This is TeX, Version 3.14159 (Web2C 7.3.1)
(test.tex
JadeTeX 1999/06/29: 2.7
(/usr/share/texmf/tex/latex/psnfss/t1ptm.fd)
(/usr/share/texmf/tex/jadetex/isoents.tex)
Elements will be labelled
Jade begin document sequence at 19
No file test.aux.
(/usr/share/texmf/tex/latex/cyrillic/ot2cmr.fd)
(/usr/share/texmf/tex/latex/base/ts1cmr.fd)
(/usr/share/texmf/tex/latex/lucidabr/lmrhlcm.fd)
(/usr/share/texmf/tex/latex/hyperref/nameref.sty)
(/usr/share/texmf/tex/latex/psnfss/t1phv.fd)

LaTeX Warning: Reference `TEST1' on page 1 undefined on input line 238.


LaTeX Warning: Reference `20' on page 1 undefined on input line 262.


LaTeX Warning: Reference `23' on page 1 undefined on input line 285.


LaTeX Warning: Reference `TEST2' on page 1 undefined on input line 316.


LaTeX Warning: Reference `30' on page 1 undefined on input line 340.


LaTeX Warning: Reference `33' on page 1 undefined on input line 363.

[1.0.46] (/usr/share/texmf/tex/latex/psnfss/t1pcr.fd) [2.0.46] [3.0.46]
(test.aux)

LaTeX Warning: There were undefined references.

 )
Output written on test.dvi (3 pages, 34984 bytes).
Transcript written on test.log.
bash$ ls -l
total 80
-rw-r--r--   1 reaster  users         771 Dec 31 20:55 test.aux
-rw-r--r--   1 reaster  users       34984 Dec 31 20:55 test.dvi
-rw-r--r--   1 reaster  users        5072 Dec 31 20:55 test.log
-rw-r--r--   1 reaster  users        4584 Dec 31 20:51 test.rtf
-rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
-rw-r--r--   1 reaster  users       18719 Dec 31 20:51 test.tex
bash$ jadetex test.tex
This is TeX, Version 3.14159 (Web2C 7.3.1)
(test.tex
JadeTeX 1999/06/29: 2.7
(/usr/share/texmf/tex/latex/psnfss/t1ptm.fd)
(/usr/share/texmf/tex/jadetex/isoents.tex)
Elements will be labelled
Jade begin document sequence at 19
(test.aux) (/usr/share/texmf/tex/latex/cyrillic/ot2cmr.fd)
(/usr/share/texmf/tex/latex/base/ts1cmr.fd)
(/usr/share/texmf/tex/latex/lucidabr/lmrhlcm.fd)
(/usr/share/texmf/tex/latex/hyperref/nameref.sty)
(/usr/share/texmf/tex/latex/psnfss/t1phv.fd) [1.0.46]
(/usr/share/texmf/tex/latex/psnfss/t1pcr.fd) [2.0.46] [3.0.46] (test.aux) )
Output written on test.dvi (3 pages, 34148 bytes).
Transcript written on test.log.
You have new mail in /var/spool/mail/reaster
bash$ ls -l
total 80
-rw-r--r--   1 reaster  users         753 Dec 31 20:58 test.aux
-rw-r--r--   1 reaster  users       34148 Dec 31 20:58 test.dvi
-rw-r--r--   1 reaster  users        4433 Dec 31 20:58 test.log
-rw-r--r--   1 reaster  users        4584 Dec 31 20:51 test.rtf
-rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
-rw-r--r--   1 reaster  users       18719 Dec 31 20:51 test.tex
bash$
	

La prima volta che viene eseguito jadetex, vengono mostrati degli avvisi. Possono essere ignorati. Lanciando il comando una seconda volta, questi non appariranno più.

Se il file ps non compare come atteso, questo può essere dovuto a bachi in htmldoc. Si guardi all'interno dello script ldp_print se si vuole utilizzarlo per creare file ps.

4.4. Generazione di pdf

Figura 7. Esecuzione di pdfjadetex per generare un file Portable Document Format (pdf).

bash$ ls -l
-rw-r--r--   1 reaster  users         753 Dec 31 20:58 test.aux
-rw-r--r--   1 reaster  users       34148 Dec 31 20:58 test.dvi
-rw-r--r--   1 reaster  users        4433 Dec 31 20:58 test.log
-rw-r--r--   1 reaster  users       34817 Dec 31 21:06 test.ps
-rw-r--r--   1 reaster  users        4584 Dec 31 20:51 test.rtf
-rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
-rw-r--r--   1 reaster  users       18719 Dec 31 20:51 test.tex
bash$ pdfjadetex test.tex
This is pdfTeX, Version 3.14159-13d (Web2C 7.3.1)
(test.tex[/usr/share/texmf/pdftex/config/pdftex.cfg]
JadeTeX 1999/06/29: 2.7
(/usr/share/texmf/tex/latex/psnfss/t1ptm.fd)
(/usr/share/texmf/tex/jadetex/isoents.tex)
Elements will be labelled
Jade begin document sequence at 19
(test.aux) (/usr/share/texmf/tex/latex/cyrillic/ot2cmr.fd)
(/usr/share/texmf/tex/latex/base/ts1cmr.fd)
(/usr/share/texmf/tex/latex/lucidabr/lmrhlcm.fd)
(/usr/share/texmf/tex/context/base/supp-pdf.tex
(/usr/share/texmf/tex/context/base/supp-mis.tex
loading : Context Support Macros / Missing
)
loading : Context Support Macros / PDF
) (/usr/share/texmf/tex/latex/hyperref/nameref.sty)
(/usr/share/texmf/tex/latex/psnfss/t1phv.fd) [1.0.46[/usr/share/texmf/dvips/con
fig/pdftex.map]] (/usr/share/texmf/tex/latex/psnfss/t1pcr.fd) [2.0.46] [3.0.46]
 (test.aux) )<8r.enc>
Output written on test.pdf (3 pages, 9912 bytes).
Transcript written on test.log.
bash$ ls -l
total 128
-rw-r--r--   1 reaster  users         753 Dec 31 21:13 test.aux
-rw-r--r--   1 reaster  users       34148 Dec 31 20:58 test.dvi
-rw-r--r--   1 reaster  users        5075 Dec 31 21:13 test.log
-rw-r--r--   1 reaster  users        9912 Dec 31 21:13 test.pdf
-rw-r--r--   1 reaster  users       34817 Dec 31 21:06 test.ps
-rw-r--r--   1 reaster  users        4584 Dec 31 20:51 test.rtf
-rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
-rw-r--r--   1 reaster  users       18719 Dec 31 20:51 test.tex
bash$
bash$ pdfjadetex test.tex
[snip]
bash$ pdfjadetex test.tex
[snip]
	
pdfjadetex deve essere eseguito fino a tre volte per risolvere tutti i riferimenti interni per cose come i numeri di pagina dell'indice.

Se abilitato all'interno dello script ldp_print, questo dovrebbe generare anche un file ps.

4.5. Utilizzare make

Ripetere i comandi per generare i file in uscita può essere noioso. Il comando make funziona perfettamente per automatizzare il procedimento.

Figura 9. File: Makefile - generazione automatica di documenti.

# Generazione di versioni per la visualizzazione e la stampa da file sorgente SGML

BASENAME=DocBook-Install

# File sorgente SGML
SGML_FILE=$(BASENAME).sgml

# Fogli di stile
DSL_PRINT=$(SGML_SHARE)/dsssl/docbook/print/ldp.dsl\#print
DSL_HTML=$(SGML_SHARE)/dsssl/docbook/html/ldp.dsl\#html

# File prodotti
HTML_FILE=index.html
HTM_FILE=$(BASENAME).htm
TEX_FILE=$(BASENAME).tex
RTF_FILE=$(BASENAME).rtf
PDF_FILE=$(BASENAME).pdf
DVI_FILE=$(BASENAME).dvi
PS_FILE=$(BASENAME).ps


# Regole di costruzione

html: $(HTML_FILE)

htm: $(HTM_FILE)

tex: $(TEX_FILE)

rtf: $(RTF_FILE)

pdf: $(PDF_FILE)

dvi: $(DVI_FILE)

ps: $(PS_FILE)

all: html htm tex rtf pdf dvi ps

clean:
	rm -f $(BASENAME).{htm,log,aux,ps,pdf,tex,dvi,rtf,fot}
	rm -f *.html

distclean: clean
	rm -f $(BASENAME).tgz

package:
	rm -f $(BASENAME).tgz
	tar -C .. -czf /tmp/$(BASENAME).tgz $(BASENAME)
	mv /tmp/$(BASENAME).tgz .

dist: clean package

distall: all package


# Regole di compilazione

$(HTML_FILE): $(SGML_FILE)
	openjade -t sgml -d $(DSL_HTML) $(SGML_FILE)

$(HTM_FILE): $(SGML_FILE)
	openjade -t sgml -V nochunks -d $(DSL_HTML) \
	$(SGML_FILE) > $(HTM_FILE)

$(TEX_FILE): $(SGML_FILE)
	openjade -t tex -d $(DSL_PRINT) $(SGML_FILE)

$(RTF_FILE): $(SGML_FILE)
	openjade -t rtf -d $(DSL_PRINT) $(SGML_FILE)

# [pdf]jadetex deve essere eseguito 3 volte per risolvere tutti i riferimenti.
#$(PDF_FILE): $(TEX_FILE)
#	pdfjadetex $(TEX_FILE)
#	pdfjadetex $(TEX_FILE)
#	pdfjadetex $(TEX_FILE)

# Questo *dovrebbe* funzionare, ma htmldoc ha dei bachi...
#$(PDF_FILE): $(SGML_FILE)
#	openjade -t sgml -V nochunks -d $(DSL_HTML) \
#	$(SGML_FILE) | htmldoc -f $(PDF_FILE) -

# Si deve usare ldp_print per aggirare i bachi di htmldoc
# ldp_print può anche creare il file ps - si veda lo script
$(PDF_FILE): $(HTM_FILE)
	ldp_print $(HTM_FILE)

$(DVI_FILE): $(TEX_FILE)
	jadetex $(TEX_FILE)
	jadetex $(TEX_FILE)
	jadetex $(TEX_FILE)

$(PS_FILE): $(DVI_FILE)
	dvips $(DVI_FILE)

#$(PS_FILE): $(SGML_FILE)
#	openjade -t sgml -V nochunks -d $(DSL_HTML) \
#	$(SGML_FILE) | htmldoc -f $(PS_FILE) -
	

L'uso è analogo alla maggior parte dei progetti:

Si notino le regole di compilazione commentate per pdf e ps, che forniscono una via alternativa per generare questi file.

4.6. Generazione di una pagina man

Durante la sezione sull'installazione, si è installato anche il modulo perl versione 5 SGMLS.pm. Quindi si è installato Docbook2X che fornisce i file spec.pl per trasformare documenti DocBook <refentry> nel formato nroff (pagine man) con sgmlspl.

Un esempio di documento Docbook <refentry>, per il comando foo, è dato di seguito.

Figura 11. Pagina man per il comando foo, sorgente docbook <refentry> (foo-ref.sgml)

<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<refentry>
<refentryinfo>
	<date>2001-01-01</date>
</refentryinfo>
<refmeta>
	<refentrytitle>
		<application>foo</application>
	</refentrytitle>
	<manvolnum>1</manvolnum>
	<refmiscinfo>foo 1.0</refmiscinfo>
</refmeta>
<refnamediv>
	<refname>
		<application>foo</application>
	</refname>
	<refpurpose>
	Does nothing useful.
	</refpurpose>
</refnamediv>
<refsynopsisdiv>
	<refsynopsisdivinfo>
		<date>2001-01-01</date>
	</refsynopsisdivinfo>
	<cmdsynopsis>
	<command>foo</command>
<arg><option>-f </option><replaceable class="parameter">bar</replaceable></arg>
<arg><option>-d<replaceable class="parameter">n</replaceable></option></arg>
<arg rep="repeat"><replaceable class="parameter">file</replaceable></arg>
	</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
	<refsect1info>
		<date>2001-01-01</date>
	</refsect1info>
	<title>DESCRIPTION</title>
	<para>
	<command>foo</command> does nothing useful.
	</para>
</refsect1>
<refsect1>
	<title>OPTIONS</title>
	<variablelist>
	<varlistentry>
		<term>-f <replaceable class="parameter">bar</replaceable></term>
		<listitem>
			<para>
			Takes <filename>bar</filename> as it's run
			control file. If this were a real program,
			there might be more to say here about what
			bar is and how it will be used.
			</para>
		</listitem>
	</varlistentry>
	<varlistentry>
		<term>-d<replaceable class="parameter">n</replaceable></term>
		<listitem>
			<para>
			Do something, where integer
			<replaceable class="parameter">n</replaceable>
			specifies how many times.
			</para>
		</listitem>
	</varlistentry>
	<varlistentry>
		<term><replaceable class="parameter">file...</replaceable></term>
		<listitem>
			<para>
			Processes the files in the order listed,
			sending all output to stdout.
			</para>
		</listitem>
	</varlistentry>
	</variablelist>
</refsect1>
<refsect1>
	<title>USAGE</title>
	<para>
	<command>foo</command> -f foo.conf -d2 foodata.foo
	</para>
</refsect1>
<refsect1>
	<title>CAVEATS</title>
	<para>
	Other programs named <command>foo</command> may exist and actually
	do something!
	</para>
</refsect1>
<refsect1>
	<title>BUGS</title>
	<para>
	None.  Program does nothing.
	</para>
</refsect1>
<refsect1>
	<title>AUTHOR</title>
	<para>
	<author>
		<firstname>Foo</firstname>
		<othername role="mi">E</othername>
		<surname>Bar</surname>
		<contrib>Original author</contrib>
	</author>
	</para>
</refsect1>
</refentry>
	

La pagina man, foo.1, viene generata come pagina della sezione 1. Il comando groff è stato utilizzato per dare un rapido sguardo all'aspetto formattato.

Per installare questa pagina man, essa deve essere sistemata in una directory man/man1, con la directory man/ che è stata aggiunta alla variabile di ambiente $MANPATH. La collocazione convenzionale è /usr/local/man/man1. Le sezioni convenzionali nel sistema delle pagine man vanno da 1 a 9. Ognuna di esse è pensata per contenere specifiche categorie di documenti.

Suggerimento

Il file sorgente per una pagina man, come foo-ref.sgml, può essere trasformato in tutti gli altri formati, come per ogni altro file DocBook. Quindi, utilizzando gli stessi comandi discussi precedentemente per generare output in html e per la stampa, una pagina man può essere trasformata in html e rtf, tex, pdf, dvi e ps. Questo può consentire di risparmiare molto lavoro di conversione!

Buon divertimento!