XML & DocBook: Structured Technical Documentation Authoring
Some documents contain too much information for a single XML file. To create entire books or guides, it might be easier to split the content among multiple files. In that case, use book as the document type in the XML file declaration lines. Each of the subfiles making up the bigger document can be called on from a central file or included at any time in one of the other subfiles. However, there should be a central file that names the ENTITY. Entities can be public or local on your system. When writing your own documentation, the most common form is <!ENTITY entity_name SYSTEM "entity_xml_file.xml">.
In the central document or wherever you want to include the extra file, call on it using the &entity_name; statement. A common use of entities is in chapters of a book, where a central file declares the entities and holds the introductory content, while the chapters of the book are individual XML files.
The content of these individual files is formed using the same tags as used for shorter documentation; refer again to the DocBook Element Reference. You do not have to declare the document type again in each subfile. Instead, specify only the type of data; for instance, put content between <chapter> and </chapter> tags when writing a book or guide.
For larger documents, you may want several introductory sections, such as Feedback, Licensing Information and Acknowledgments. These sections usually are created with <section> tags. In the chapters, you are more likely to use <sect1>, <sect2>, <sect3> and <sect4> subsection tags. Books also should also contain a Table of Contents or TOC. The TOC can be generated automatically if you use the <toc> tag around the chapter headings or whatever other headings you want included in the table of contents. The DocBook DTD specifies various other tags for glossaries, indexes, cross-references and bibliographies.
As we explained before, printable files cannot be generated directly from the XML file. We need an intermediate step that generates formatted documents, in which page layout, typography, chapter and section numbering, cross references, icon graphics and a number of other things are specified.
These basic definitions for printed formats can be configured without having to customize the XSL stylesheets. Using xsltproc, specifications are entered on the command line or in a script. Here is an example command:
xsltproc --stringparam paper.type A4 --stringparam fop.extentions 1 /usr/share/sgml/docbook/xsl-stylesheets/fo/docbook.xslarticle.xml> article.fo
This command tells the processor to generate pages that fit on the standard A4 paper size, using a locally defined stylesheet on the source XML file. It also specifies that the output should be saved in an FO file.
Once we have the FO file, the next step is to transform the file into the desired format. This is done using the fop command:
fop -fo article.fo -pdf article.pdf
Conversion to HTML is somewhat more straightforward, because all that needs to be done, simply put, is to map XML tags to HTML tags. Here's a basic example command, again using xsltproc:
xsltproc /usr/share/sgml/docbook/xsl-stylesheets-1.65.1-1/html/docbook.xsl article.xml > article.html
Of course, that would generate a rather ugly and unmanageable HTML file, so usually a Cascading Stylesheet or CSS is applied. This and the XSL stylesheet that is applied can make the same sources look totally different. An example of two different looks of the same document can be found here:
Fine-tuning stylesheets is a meticulous work. Various individuals have made their styles publicly downloadable, however, so you can apply them to your own sources.
DocBook XML is accessible to use, especially for those who have a grasp of HTML already. It is a markup language developed for writing computer documentation. It thus provides hundreds of little ways to specify content. How this content is displayed later--what fonts and font sizes are used, what colors, how the layout is done--should not be the concern of the authors. Authors can write once and publish in any desired format, which saves time, effort and, to a lesser degree, disk space and other computing resources.
This brief article really is not enough space to demonstrate fully the capabilities of DocBook. For instance, we didn't even begin to discuss DocBook's special features, such as the use of cross references, glossaries, bibliographies, automatic index generation, language settings, support for mathematical expressions and so on. Therefore, I recommend the following resources for further reading:
DocBook XSL: The Complete Guide, by Bob Stayton, ISBN: 0-9741521-1-0, published by Sagehill Enterprises.
DocBook, The Definite Guide, by Norman Walsh, ISBN: 1-56592-580-7, published by O'Reilly.
"Take My Advice: Don't Learn XML", by Michael Smith, O'Reilly XML
Practical Task Scheduling Deployment
July 20, 2016 12:00 pm CDT
One of the best things about the UNIX environment (aside from being stable and efficient) is the vast array of software tools available to help you do your job. Traditionally, a UNIX tool does only one thing, but does that one thing very well. For example, grep is very easy to use and can search vast amounts of data quickly. The find tool can find a particular file or files based on all kinds of criteria. It's pretty easy to string these tools together to build even more powerful tools, such as a tool that finds all of the .log files in the /home directory and searches each one for a particular entry. This erector-set mentality allows UNIX system administrators to seem to always have the right tool for the job.
Cron traditionally has been considered another such a tool for job scheduling, but is it enough? This webinar considers that very question. The first part builds on a previous Geek Guide, Beyond Cron, and briefly describes how to know when it might be time to consider upgrading your job scheduling infrastructure. The second part presents an actual planning and implementation framework.
Join Linux Journal's Mike Diehl and Pat Cameron of Help Systems.
Free to Linux Journal readers.Register Now!
- Introduction to Named Pipes
- Scriptwriting for ze Web and Everywhere Else
- Using tshark to Watch and Inspect Network Traffic
- diff -u: What's New in Kernel Development
- Securing Your Network against Kazaa
- Perceptions of the Linux OS Among Undergraduate System Administrators
- Kernel Korner
- Letters to the Editor
- Making TeX Work
- New Products
With all the industry talk about the benefits of Linux on Power and all the performance advantages offered by its open architecture, you may be considering a move in that direction. If you are thinking about analytics, big data and cloud computing, you would be right to evaluate Power. The idea of using commodity x86 hardware and replacing it every three years is an outdated cost model. It doesn’t consider the total cost of ownership, and it doesn’t consider the advantage of real processing power, high-availability and multithreading like a demon.
This ebook takes a look at some of the practical applications of the Linux on Power platform and ways you might bring all the performance power of this open architecture to bear for your organization. There are no smoke and mirrors here—just hard, cold, empirical evidence provided by independent sources. I also consider some innovative ways Linux on Power will be used in the future.Get the Guide