DHQauthor Schema

This document provides information and resources for authors on using the DHQ authoring schema to tag their own articles. Here's what you'll find on this page:

• Documentation at the Tag Library
• Schemas and other materials for download at Download Central
• How to get started with DHQ markup

Using DHQauthor

Encoding your own article is a good thing for several reasons: for one thing, it gives you a better understanding of how the journal structures and represents its information. It also lets you be clear about exactly how you intend the article to be structured, and avoids misunderstandings arising from ambiguous formatting. Finally, it saves DHQ work in preparing your article for publication.

To help DHQ get the greatest benefit from your encoding work, please bear the following points in mind:

• Please use the tags to represent the intended information; don't use a tag just because it seems to generate the formatting you want. Remember that the final formatting of articles is controlled by a stylesheet that might change, so if you mistag something, it may show up very oddly in the future. If you can't find a tag you need, please email us at editors@digitalhumanities.org to suggest it.

• Be consistent: use the same tag for the same thing throughout your article.

• When in doubt, ask for help! we're happy to provide advice and assistance to people who are learning the DHQ markup language. Email us at editors@digitalhumanities.org.

What it is and where to get it

The DHQauthor schema is the version of the DHQ markup language intended for use by authors in encoding their own articles. DHQ also maintains DHQpublish, the version that is used for published DHQ articles.

The current version of DHQauthor is modelled through several specific schema files (described in more detail below):

• DHQauthor.rng: the DHQauthor schema main module
• DHQauthor-header.rng: the module that constrains the DHQheader (the DHQ metadata component)
• cc-license.rng: the module for the Creative Commons license component of the header
• DHQauthor-ready.sch: a Schematron assertion set for additional validation; this provides certain checks for preferred practice)

You can download the schema files (in a .zip package) at Download Central.

Tools, samples, and other support

Elements and attributes supported by DHQauthor are documented in the Tag Library.

Sample encoded files are available at Download Central.

You can find tools for editing, file conversion, and other functions at the Tools page.

Information on how to get started

Other Useful Links

• Coordinate changes on DHQschemaDevelopment
• Read Getting Started with DHQauthor for step-by-step help
• Track Issues and Suggestions for DHQauthor
• Workspace: TEI Variances - which we will eventually refine into:
  • A list of changes to DHQ
  • An ODD "shell" for DHQ (TEI compliance!)
• Big picture stuff (for developers): start with Schema Requirements
• SkunkWorks for discussion of technical tasks and ideas for development

Design of the schema

The schema has a modular design intended to facilitate development by making maintenance and reuse easy.

The complete schema has two separable main modules, which can be graphed as follows:

1. DHQauthor.rng - the DHQauthor schema main module, which calls in
   • DHQauthor-header.rng - module for the header, which calls in
     • cc-license.rng - module for the Creative Commons license component of the header
2. DHQauthor-ready.sch - Schematron assertion set for additional validation

For convenience and to ensure all modules are successfully included when processing, all the files should be stored in the same subdirectory.

The main DHQauthor.rng module provides for structural validation of DHQauthor documents. Ordinarily, users should not have to be concerned with its submodules as long as they are present (though they may also be used separately).

The DHQauthor-ready.sch Schematron provides for validation of additional constraints, by providing warnings when certain conditions (either strict or loose) are not met over and above the basic DHQauthor tagging constructs. For example, if a cross-reference does not link correctly to a target, a document may still be formally valid to the DHQauthor RNG schema, but the lapse will be reported by the Schematron.

This design enables files to be valid to the Relax NG schema well before completion (and indeed, from the first moments of drafting). An author may find it useful, therefore, to validate to DHQauthor.rng while composing, and add validation to DHQauthor-ready.sch only when nearing completion to perform final checks.

Validating to both components warrants that a document has no "loose ends". ''Depending on editorial requirements, however, validation to every constraint expressed in the Schematron may not be demanded.'' (It will report warnings for certain conditions that are discouraged but not actually disallowed.) ''Validation against the Relax NG schema is, however, mandatory.''

How to help

• Making sample documents
• Contributing to discussions on dhq-tech (where you will probably be listened to) or dhq-publish (where actual decisions are more likely to emerge)
• Contributing to Issues and Suggestions
• Contributing documentation (help with this FAQ etc.)

Modifications log

for Release 2 [to be listed when 2 is released]

-- WendellPiez? - 10 Sep 2006