With an XML catalog, you can have the best of both local and network access. The catalog lets you map the standard network URL to a local file. If the catalog processor finds the local file during processing, it will use it. Otherwise, it falls back to using the network URL. With this arrangement, you get the speed of local access with the reliability and portability of network access. If not, then the URL is used through network access. You can achieve a similar mapping with an SGML catalog, which is an older technology using a simpler syntax.
Depending on the source for your DTD download, the files that define the character entity names may not be included. Create a directory named ent in the directory where the DocBook DTD files are, and extract the entity files into ent. Validation is the act of checking your document against the element names and rules in the DTD.
If it does find the DTD, it will read and use an entity declarations in it. If you use any DocBook character entities, the processor must be able to find the DTD to resolve those entity references. Since the XSL processor does not automatically validate your document, it is possible to process invalid but well-formed DocBook documents. But you do so at your own risk, because the DocBook stylesheets expect to be processing a valid document.
Your output may not be what you expect if you do not follow the rules. You will have fewer mysterious problems if you validate your documents before processing them. Some of the XSLT processors described in later sections include validation utilities. For example, xsltproc includes a program called xmllint that can validate an XML document using a command like the following:. If you are looking for a Java-based validation tool, there is a XML validation tool hidden in the distribution of Xalan 2.
What a great feeling. The reality of failing silently, though, is that it still failed. You might have gotten output, and most of it might look just fine, but what about the error that wasn't caught?
Maybe it renders something incorrectly, but if it's buried in page 42 of a page document, when will you notice? Maybe the error rendered correctly in the web version of your document, but incorrectly for the print version.
DocBook, like all XML, is famously strict. Experiencing errors is never easy. It's not fun to watch your work fizzle out in a pool of illegal tags and syntax errors instead of building into a beautifully rendered EPUB, webpage, or PDF. To get around that disappointment, most processors accept an option to temporarily ignore errors, such as --skip-validation , but ultimately failure is important.
Failure identifies imperfections in your source and protects you from unpleasant surprises in your product. DocBook sometimes has a reputation for being hard to learn.
I have found that more often it's not DocBook, but the unique tool chains people build around it, that have the steep learning curve. Do you want to write an article or a book? Compared to Markdown and AsciiDoc , DocBook appears complex, but if you consider all the rules that aren't intuitive in structured text, DocBook's rules don't seem so bad. Learning syntax from the original Markdown spec was often a process of trial and error, followed by a series of desperate internet searches, which meant wading through all the different Markdown flavors and parsers for the best applicable candidate for a correct answer.
CommonMark , a project dedicated to defining a more arduous and strict specification, has helped, but users are often lulled into a false sense of security by how easy it is to learn the basics, only to find that achieving advanced results introduces a surprise learning curve. Luckily, Markdown accepts HTML as a fallback markup option, and there are several tools and Markdown variants out there to make up for what the original spec lacks.
Even so, if you're writing complex documents for several different output targets, it may not be as easy as it looks in all the "learn Markdown in just 15 minute"-style blogs. That's all there is to it. It's about the same as learning HTML: learn the basics in the first few minutes, and keep a reference handy to learn more as needed. Depending on how much you know about XML, there can be a few surprises, but the DocBook website clearly defines valid parent and child relationships for each and every tag, and each entry for each tag provides big blocks of examples.
Finally, DocBook is important because it provides data about your data. DocBook tags aren't meant to dictate a style over your content, but to classify the information you are trying to convey.
DocBook tags provide semantic meaning to your words. Semantics might not seem that important to you now, but here are two great examples of times that metadata became truly important in the real world:. Here's a quick and easy way to get started with DocBook. This method emphasizes learning DocBook tags and syntax rather than building a complex and flexible tool chain.
If you are ever in doubt about whether or not a tag is required, just refer to the tag's documentation. The synopsis section tells you what is required and what is optional. And that's all there is to it. The more you write in DocBook, the more tags and attributes you learn, and eventually you'll probably find it hard to go back to a less explicit format.
The default DocBook render from most processors aside from Pandoc looks a little something like this:. It's professional, but painfully so. Still, it's an important foundation upon which additional styles can be applied. Otherwise, here's a brief introduction to XSL and the xsltproc command.
If you install DocBook from your Linux distribution or from the DocBook website, you are installing all the default DocBook stylesheets. These serve as the fallback styles whenever you use a tool like xsltproc or xmlto. If you cannot or choose not to install DocBook, you can point to the stylesheets manually in your xsltproc command. Building a PDF with xsltproc is a two-step process. First, you must generate the.
Then you process the. An easy modification to make when just getting started with styling DocBook is your font choice.
Fonts are easy to change and make a noticeable difference in your end product. This registers all the TTF fonts in your personal or system fonts directory. You don't have to point it to standard font directories, but it must be an absolute, not relative, path.
I use both methods, depending on the gravity of the change. It's no longer being actively developed, and has gone out of print, but it is still available online.
It provides the necessary documentation to realize the full potential of DocBook publishing. It covers all aspects of DocBook publishing tools, including installing, using, and customizing the stylesheets and processing tools. Also available : buttons, shirts, and other swag. Wear your duck on your sleeve! Well, your chest anyway. DocBook V5. This release updates the Schematron rules to match the Schematron standard that changed after 5.
The 5. DocBook Version 5.
0コメント