This document provides an enumeration of the overarching principles in the design of Rod's pattern.dtd. This enumeration serves two purposes:
Some of these principles are implied by the others, but I thought it better to err on the side of verboseness.
Several of these principles are the same or quite similar to those used for the design of XML itself, as expressed in Design Principles for XML, which is available at http://www.textuality.com/sgml-erb/dd-1996-0001.html.
- The markup should, in general, indicate the meaning rather than the intended presentation of the text.
- It should be easy to generate applications that manipulate, utilize and render pattern documents.
Examples of such applications include, but are not limited to, pattern servers, pattern catalog generators, search engines and printable file generators (e.g. PDF).
- The markup should be author-extensible.
The principle should be seen in the context of Principle 2--It should be easy to generate applications that manipulate, utilize and render pattern documents. Author-defined extensions should not break core application functionality, and ideally applications would be capable of utilizing author-defined extensions.
- Linking and cross-referencing patterns and pattern documents as well as other resources is an important consideration.
At their core, patterns draw great power from a few core features:
Similarly, it is both common and useful to pull in external resources in the documentation of a pattern, for example, UML diagrams of an implementation of a pattern or links to source code or example applications that utilize the pattern. All of these features should be supported.
- the ability to link atomic patterns to generate pattern languages
- the utility of using patterns and pattern languages to document design decisions and issues
- Pattern documents should be human-legible and reasonably clear.
In particular, this implies that the XML source for pattern documents should be legible as is.
- Pattern documents should be easy to create.
It should be not only possible, but practical to create pattern documents with simple text editors such as vi, Notepad or SimpleText.
- The number of logical elements and options should be kept to a minimum.
This is implied by Principles 2 and 6--the markup should be easy to use by both applications and authors.
- Where appropriate, the markup should mimic HTML, but should otherwise seek to avoid naming or notation conflicts with HTML.
Most authors will be familiar with basic HTML, hence any similarity in notation can be leveraged if the intent is actually the same, but may lead to confusion if the tag (entity) exists but has a different meaning.
- The DTD should be complete.
No additional tags or DTDs should be needed to create a complete pattern document.
- Terseness is important, but only minimally important.
All things being equal, the more concise notation is preferred. All things are rarely equal.