DocBox the Definitive Guide-Chapter 5. Customizing DocBook

Tham khảo tài liệu docbox the definitive guide-chapter 5. customizing docbook, công nghệ thông tin, kỹ thuật lập trình phục vụ nhu cầu học tập, nghiên cứu và làm việc hiệu quả
Nội dung trích xuất từ tài liệu:
DocBox the Definitive Guide-Chapter 5. Customizing DocBook Chapter 5. Customizing DocBookFor the applications you have in mind, DocBook out of the box may not beexactly what you need. Perhaps you need additional inline elements orperhaps you want to remove elements that you never want your authors touse. By design, DocBook makes this sort of customization easy.This chapter explains how to make your own customization layer. Youmight do this in order to: • Add new elements • Remove elements • Change the structure of existing elements • Add new attributes • Remove attributes • Broaden the range of values allowed in an attribute • Narrow the range of values in an attribute to a specific list or a fixed valueYou can use customization layers to extend DocBook or subset it. Creating aDTD that is a strict subset of DocBook means that all of your instances arestill completely valid DocBook instances, which may be important to yourtools and stylesheets, and to other people with whom you share documents.An extension adds new structures, or changes the DTD in a way that is notcompatible with DocBook. Extensions can be very useful, but might have agreat impact on your environment.Customization layers can be as small as restricting an attribute value or aslarge as adding an entirely different hierarchy on top of the inline elements.5.1. Should You Do This?Changing a DTD can have a wide-ranging impact on the tools andstylesheets that you use. It can have an impact on your authors and on yourlegacy documents. This is especially true if you make an extension. If yourely on your support staff to install and maintain your authoring andpublishing tools, check with them before you invest a lot of time modifyingthe DTD. There may be additional issues that are outside your immediatecontrol. Proceed with caution.That said, DocBook is designed to be easy to modify. This chapter assumesthat you are comfortable with SGML/XML DTD syntax, but the examplespresented should be a good springboard to learning the syntax if its notalready familiar to you.5.2. If You Change DocBook, Its Not DocBook Anymore!The DocBook DTD is usually referenced by its public identifier: -//OASIS//DTD DocBook V3.1//ENPrevious versions of DocBook, V3.0 and the V2 variants, used the owneridentifier Davenport, rather than OASIS.If you make any changes to the structure of the DTD, it is imperative thatyou alter the public identifier that you use for the DTD and the modules youchanged. The license agreement under which DocBook is distributed givesyou complete freedom to change, modify, reuse, and generally hack theDTD in any way you want, except that you must not call your alterationsDocBook.You should change both the owner identifier and the description. Theoriginal DocBook formal public identifiers use the following syntax:-//OASIS//text-class DocBook descriptionVversion//ENYour own formal public identifiers should use the following syntax in orderto record their DocBook derivation:-//your-owner-ID//text-class DocBook Vversion-Based[Subset|Extension|Variant] your-descrip-and-version//langFor example:-//OReilly//DTD DocBook V3.0-Based Subset V1.1//ENIf your DTD is a proper subset, you can advertise this status by using theSubset keyword in the description. If your DTD contains any markupmodel extensions, you can advertise this status by using the Extensionkeyword. If youd rather not characterize your variant specifically as a subsetor an extension, you can leave out this field entirely, or, if you prefer, use theVariant keyword.There is only one file that you may change without changing the publicidentifier: dbgenent.mod. And you can add only entity and notationdeclarations to that file. (You can add anything you want, naturally, but ifyou add anything other than entity and notation declarations, you mustchange the public identifier!)5.3. Customization LayersSGML and XML DTDs are really just collections of declarations. Thesedeclarations are stored in one or more files. A complete DTD is formed bycombining these files together logically. Parameter entities are used for thispurpose. Consider the following fragment: (1) (2)%dbpool; (3)%dbhier; (4)(1) This line declares the parameter entity dbpool and associates it with the file dbpool.mod.(2) This line declares the parameter entity dbhier and associates it with the file dbhier.mod.(3) This line references dbpool, which loads the file dbpool.mod and inserts its content here.(4) Similarly, this line loads dbhier.mod.It is an important feature of DTD parsing that entity declarations can berepeated. If an entity is declared more than once, then the first declaration isused. Given this fragment:The replacement text for &foo; is Lenny.These two notions, that you can break a DTD into modules referenced withparameter entities and that the first entity declaration is the one that counts,are used to build customization layers. With customization layers you canwrite a DTD that references some or all of DocBook, but adds your ownmodifications. Modifying the DTD this way means that you never have toedit the DocBook modules directly, which is a tremendous boon tomaintaining your modules. When the next release of DocBook comes out,you usually only have to make changes to your customization layer and yourmodification will be back in sync with the new version.Customization layers work particularly well in DocBook because the baseDTD makes extensive use of parameter entities that can be redefined.5.4. Understanding DocBook StructureDocBook is a large and, at first glance, fairly complex DTD. Much of theapparent complexity is caused by the prolific use ...