[Prev] [Next]

2.2 Interchanging DocBook Documents

Simply using DocBook or a subset of it is not enough to ensure successful interchange. If you send someone your DocBook files, you must also tell the recipient about the markup your documents use and any of your additional markup conventions and processing expectations that impose constraints on processing.

Delivered DocBook documents should be accompanied by a filled-out interchange questionnaire. Because each situation is unique, you may need to supply additional information (such as layout specifications) in order to deliver a complete package.DocBook and SGML Usage

1. What version of the DTD are you using?

2. Did you use any markup features of the DTD that have been flagged as obsolescent (to be removed at the next major version of DocBook)? If so, which ones?

3. Did you extend DocBook in any way, inside or outside the provided customization mechanisms? How? All extensions must be negotiated with the recipient.

4. Did you remove markup from DocBook to create a subset? If you used a subset of DocBook, supply the subset you used. (Note that even the removal of references to ISO entity sets creates a subset.)

5. Did you use the supplied SGML declaration or another one? If you used another one, provide it.

6. Did you use the supplied catalog or another one, or none at all? If you used a catalog other than the supplied one, provide it.

7. If your documents bear no document type declaration, and you parsed them with a document declaration (with or without an internal subset), supply it.

8. Did you add NOTATION declarations? If so, what are they? List all data content notations used in your documents.

9. Did you use the SUBDOC feature? If so, how did you manage the name spaces of their IDs, if you did manage them at all?

10. Did you use character sets other than ISO 8859-1 (Latin 1)? If so, which ones? How did you use them?

11. Did you declare and use character entities and other general entities besides the ISO entity sets? If so, supply the entity declarations and the desired appearance for the additional character entities.

12. Are your document files normalized to include all markup explicitly?

13. Are you supplying a document fragment? If so, have you provided any necessary auxiliary information (such as metainformation) for the fragment? Are there any attribute values that haven't been specified that are expected to inherit from a parent that isn't present?

Processing Requirements and Markup Interpretation

1. What formatting do you require your interchange partner to do in the fashion you did? For example, where and how must text be generated in order for the documents to make sense?

2. Supply your style sheet and information regarding its format and version.

3. How did you create tables of contents, lists of titles, and indices? Are they stored in DocBook form? If so, did you generate them (and according to what rules) or create them by hand?

4. If you used the Lang common attribute, why and to what effect?

5. If you used the Remap common attribute, why and to what effect?

6. If you used the Role common attribute, why and to what effect?

7. If you used the effectivity attributes, which did you use, why, and to what effect?

8. What values did you give to the Label attribute and how are they to be interpreted for rendering?

9. What values did you give to the Mark and Override attributes for lists and how are they to be interpreted for rendering?

10. Did you use the Renderas attribute on sections and/or BridgeHeads?

11. Supply all keyword values you used for attributes whose declared values are not enumerated tokens, along with the expected processing for the occurrence of each keyword.

12. Did you use markup to control width, size, and/or positioning settings (such as ``fold-out'' or ``centered'') for graphics, linespecific regions, and tables? If so, how?

13. For rendering of Sidebars, must these appear in the flow of the text where they appear in your files, or may they float?

14. For Graphic and InlineGraphic, what method(s) did you use for providing graphic data: element content, Fileref attribute, or Entityref attribute?

15. How did you specify column widths in tables? Did you use vertical spans? Did you use horizontal spans?

16. If you used the Type attribute on the link elements, why and to what effect?

17. Did you use the Subject attribute on GlossDef? If so, did you use a thesaurus of terms? If so, what is it?

18. If you used the Class attribute on RefMiscInfo, why and to what effect?

19. If you used ULink and provided URLs that are queries, what back-end processing is required to resolve those queries?

20. Did you use any processing instructions? Were they in entities? What copyfitting have you already done, and for what outputs?

Miscellaneous

1. Have you checked your files for viruses?

2. If you used BridgeHead, have you joined a recovery support group?

[Prev] Quick Start
[Next] Using New Releases of DocBook
[Overview Home] [Davenport Group Home]