Examples This appendix contains example SGML files and command lines you can use to convert them from one output format to another. If you have successfully installed the Documentation Project tools then you should be able to to use these examples directly. These examples are not exhaustive—they do not contain all the elements you might want to use, particularly in your document's front matter. For more examples of DocBook markup you should examine the SGML source for this and other documents, available in the CVSup doc collection, or available online starting at http://www.FreeBSD.org/cgi/cvsweb.cgi/doc/. To avoid confusion, these examples use the standard DocBook 3.1 DTD rather than the FreeBSD extension. They also use the stock stylesheets distributed by Norm Walsh, rather than any customisations made to those stylesheets by the FreeBSD Documentation Project. This makes them more useful as generic DocBook examples. DocBook <sgmltag>book</sgmltag> DocBook <sgmltag>book</sgmltag> An Example Book Your first name Your surname
foo@example.com
 2000 Copyright string here If your book has an abstract then it should go here. Preface Your book may have a preface, in which case it should be placed here. My first chapter This is the first chapter in my book. My first section This is the first section in my book. ]]> DocBook <sgmltag>article</sgmltag> DocBook <sgmltag>article</sgmltag>
An example article Your first name Your surname
foo@example.com
 2000 Copyright string here If your article has an abstract then it should go here. My first section This is the first section in my article. My first sub-section This is the first sub-section in my article.
]]> Producing formatted output This section assumes that you have installed the software listed in the textproc/docproj port, either by hand, or by using the port. Further, it is assumed that your software is installed in subdirectories under /usr/local/, and the directory where binaries have been installed is in your PATH. Adjust the paths as necessary for your system. Using Jade Converting DocBook to HTML (one large file) &prompt.user; jade -V nochunks \ -c /usr/local/share/sgml/docbook/dsssl/modular/catalog \ -c /usr/local/share/sgml/docbook/catalog \ -c /usr/local/share/sgml/jade/catalog \ -d /usr/local/share/sgml/docbook/dsssl/modular/html/docbook.dsl -t sgml file.sgml > file.html Specifies the nochunks parameter to the stylesheets, forcing all output to be written to STDOUT (using Norm Walsh's stylesheets). Specifies the catalogs that Jade will need to process. Three catalogs are required. The first is a catalog that contains information about the DSSSL stylesheets. The second contains information about the DocBook DTD. The third contains information specific to Jade. Specifies the full path to the DSSSL stylesheet that Jade will use when processing the document. Instructs Jade to perform a transformation from one DTD to another. In this case, the input is being transformed from the DocBook DTD to the HTML DTD. Specifies the file that Jade should process, and redirects output to the specified .html file. Converting DocBook to HTML (several small files) &prompt.user; jade \ -c /usr/local/share/sgml/docbook/dsssl/modular/catalog \ -c /usr/local/share/sgml/docbook/catalog \ -c /usr/local/share/sgml/jade/catalog \ -d /usr/local/share/sgml/docbook/dsssl/modular/html/docbook.dsl -t sgml file.sgml Specifies the catalogs that Jade will need to process. Three catalogs are required. The first is a catalog that contains information about the DSSSL stylesheets. The second contains information about the DocBook DTD. The third contains information specific to Jade. Specifies the full path to the DSSSL stylesheet that Jade will use when processing the document. Instructs Jade to perform a transformation from one DTD to another. In this case, the input is being transformed from the DocBook DTD to the HTML DTD. Specifies the file that Jade should process. The stylesheets determine how the individual HTML files will be named, and the name of the root file (i.e., the one that contains the start of the document. This example may still only generate one HTML file, depending on the structure of the document you are processing, and the stylesheet's rules for splitting output. Converting DocBook to Postscript The source SGML file must be converted to a TeX file. &prompt.user; jade -Vtex-backend \ -c /usr/local/share/sgml/docbook/dsssl/modular/catalog \ -c /usr/local/share/sgml/docbook/catalog \ -c /usr/local/share/sgml/jade/catalog \ -d /usr/local/share/sgml/docbook/dsssl/modular/print/docbook.dsl -t tex file.sgml Customises the stylesheets to use various options specific to producing output for TeX. Specifies the catalogs that Jade will need to process. Three catalogs are required. The first is a catalog that contains information about the DSSSL stylesheets. The second contains information about the DocBook DTD. The third contains information specific to Jade. Specifies the full path to the DSSSL stylesheet that Jade will use when processing the document. Instructs Jade to convert the output to TeX. The generated .tex file must now be run through tex, specifying the &jadetex macro package. &prompt.user; tex "&jadetex" file.tex You have to run tex at least three times. The first run processes the document, and determines areas of the document which are referenced from other parts of the document, for use in indexing, and so on. Do not be alarmed if you see warning messages such as LaTeX Warning: Reference `136' on page 5 undefined on input line 728. at this point. The second run reprocesses the document now that certain pieces of information are known (such as the document's page length). This allows index entries and other cross-references to be fixed up. The third pass performs any final cleanup necessary. The output from this stage will be file.dvi. Finally, run dvips to convert the .dvi file to Postscript. &prompt.user; dvips -o file.ps file.dvi Converting DocBook to PDF The first part of this process is identical to that when converting DocBook to Postscript, using the same jade command line (). When the .tex file has been generated you run TeX as before. However, use the &pdfjadetex macro package instead. &prompt.user; tex "&pdfjadetex" file.tex Again, run this command three times. This will generate file.pdf, which does not need to be processed any further.