Appendix A. Comparison of Markup Formats

This compares uDoc 1.0 and DITA 1.2 for publications markup:



Feature

uDoc 1.0

DITA 1.2

Language

MicroXML

XML 1.0

Content Models

None. uDoc suggests what is appropriate, but you are free to do what you want. So you can create your own schemas without having to fit them into a “standard” mold.

DTDs and XSD schemas, very restrictive. Added restrictions that are unenforceable by machine validation (and often surprising) are given in the spec.

Maps

Maps describe the overall content and specify added resources for the project.

Maps work much as in uDoc, but do not permit some content that uDoc allows, such as project-specific transitional text in <doctext>.

Topics

Topics can have whatever is best for your own use case. You can create new topic types at will to capture whatever semantics you need.

Topics are categorized based on Information Mapping principles. The general “topic” type is discouraged in favor of specialized and restricted types like “concept”, “task”, and “reference”.

Libraries

The third kind of uDoc file, which can contain anything intended for referencing from multiple docs or maps. No restrictions on content or organization.

No equivalent.

Transclusion

Content can be added at any point in the map or doc. uDoc content to be re-used can be stored in libraries without restriction.

Conrefs can only reference elements matching the content model of the referencing element, imposing a great deal of overhead to ensure that referenced elements match referencing ones.

Conditions

Conditions (in libraries) can be used based on the output type being produced and on any attribute of any element. Multiple sets can apply to different branches of the same project.

Conditions (in “ditaval” files) are based on a small set of attributes that are not allowed on many elements. Only one condition set can be used per project.

Scoping

You can define scopes for key resolution, xrefs, transclusion, and conditions within the map using named branches. This makes it very easy to use the same topic in more than one place in the project, and have each instance treated as distinct, automatically directing references between them to the correct targets.

All keys, xrefs, conrefs, and conditions are at full project scope. This makes re-use of a topic in the same project difficult, requiring a renaming hack (“copy-to”) and manual fixup of all references to the topic.

Interproject Links

References can be directed to keys defined in other projects, and automatically provide the right target for each output type.

Projects can use only keys defined within their own maps. Interproject links can only be made manually.

Related Topics

Related topics are automatically identified based on the subjects (like ALinks or #hashtags) assigned in the map or doc, so broken links are impossible. Different subjects can have different weights, supporting a ranked listing.

Related topics must be specified explicitly in <related-links> or in a <reltable>. If a topic not in the current project is listed, a broken link to it is the result. No weighting method is provided.

New Rlements

New elements can be created by simple copy/paste at will, with any attributes needed, and used anywhere immediately. Same for redefining and renaming existing elements.

New elements can only be “specialized” from existing ones, by an expert at DTDs/XSDs, and can be used only where their base element could be used. Even adding an attribute is hard.

Tag Minimization

uDoc supports several forms of tag minimization which reduce on-screen clutter and make authoring and editing much easier, even if you just have Notepad. It includes a conversion utility, udx, to go between minimized and full-tag forms (best if using XSLT for processing) at will, losslessly.

No equivalent.

Previous Topic:  6.8 Element Attributes

Next Topic:  Appendix B. uDoc Sample Files

Sibling Topics:

The uDoc Document Format

Chapter 1. Why Use uDoc?

Chapter 2. uDoc Structures

Chapter 3. uDoc Processing

Chapter 4. uDoc Addressing

Chapter 5. uDoc File Generation

Chapter 6. uDoc Elements

Appendix B. uDoc Sample Files

Appendix C. Standard uDoc Libraries

Appendix D. MXL MicroXML Parser

Appendix E. The udx Utility