Declarative markup is the practice of identifying what parts of an information object are, as opposed to identifying what the information should look like or how the information might be processed. An example is marking part of a document as the name of a drug instead of marking it as a phrase that should be displayed in italics or as something that should be linked to a specific spot in a glossary. It is the use of declarative markup that drives many of the claimed advantages of XML. It is declarative markup that can make XML documents system- and process-independent and that allows them to be displayed appropriately in print, on screen, and in voice synthesis from the same source. Most important, it is declarative markup that can make XML documents long-lived.
Documents marked up with declarative markup, regardless of the syntax, are far more likely to survive multiple generations of document processing systems and computing environments than documents that have display- or processing-based markup. This is independent of the syntax in which the documents are stored or interchanged. XML, SGML, and JSON can all be used as the syntax for documents encoded with declarative markup. They can also be used as the syntax for documents encoded with processing or display semantics. Documents that are encoded with processing or display semantics are often far easier for systems to create and ingest than documents with declarative semantics, and are appropriate for convenience interchange and documents that are intended to be short-lived and/or used only in very controlled environments.
Challenges to Learning More About Declarative Markup
One of the challenges for people trying to learn about declarative markup is that they often do not know that declarative markup is what they want. The literature on XML often talks about quality of XML encoding and gives examples that show declarative markup as being better than procedural markup, but it rarely names either style nor does it explain why some XML markup is better than others. There is nothing in the specifications for XML, SGML, or JSON that addresses what should be identified in documents or just how to encode whatever is to be encoded.
Because all of the names by which declarative markup are discussed consist of very common words, it is very difficult to find the scant existing literature on it using web-based search engines. Not only is not much written directly addressing this important topic, but it is also almost undiscoverable.
The name for this philosophy of document encoding, “Declarative Markup,” is not used consistently in the literature that discusses it; sometimes it is called “Generic Markup,” “Semantic Markup,” or “Descriptive Markup.” Often it is mentioned as a side note to a discussion of SGML or XML, and is not named at all.
Providing a Solution
MarkupDeclaration.org is “a movement for clarifying and formalizing our understanding of declarative markup.” In support of that mission, and because the literature on declarative markup is very difficult to discover using currently popular tools, I started “Declarative Markup: A Bibliography.” It started with a list of papers and other resources that I reference myself and sometimes share with others. I added to it some conference papers that have impressed me enough that I remembered them as well as a few presentations I have given. (This is the heart of the problem the bibliography is designed to solve — I was wracking my brain for articles and conference presentations that had made an impression on me because there was no current list of them.) I then scanned “The Cover Pages,” which was a listing of all-things-SGML-and-XML, maintained by Robin Cover through 2002. In its day, it was the definitive source for information, events, publications, specifications, and tools relating to SGML and XML, but a lot has happened in this field since 2002.
With this start, I shared the draft with several declarative markup practitioners, asking for comments and suggested additions. To my surprise, the first reactions were generally in two parts:
- Here are a few key items you missed, and
- Questioning why I included one or two of the items on the list.
So, it became an Annotated Bibliography. With each entry I tried to write a note explaining what that item had to do with declarative markup and why it was interesting or important. Some of the annotations are excerpts from the document or its abstract or website; many are the opinion of the contributor as to why the item is significant. The source of each annotation is identified.
Initially, the bibliography was a simple list in alphabetical order by surname of the first author of the resource. As the bibliography grew, it became clear that the list was getting too long to scan comfortably and that the items could usefully be divided into several categories:
- About Declarative Markup per se
- Declarative Markup Uses
- Other Collections of Markup-related Materials
- Related Concepts
In addition, Norm Walsh started a related resource describing events relating to declarative markup at: https://markupdeclaration.org/resources/events.html.
How to Participate
The Annotated Bibliography, like everything on MarkupDeclaration.org, is designed to be a community resource. All interested parties are invited to add entries describing materials that are directly related to declarative markup. (Materials that people who are interested in declarative markup might also be interested in, but that are not directly related to declarative markup will not be accepted.) Entries should consist of:
- as complete a bibliographic citation as possible,
- a short annotation describing the resource and its significance with respect to declarative markup, and
- the name of the contributor.
Instructions on how to add to the bibliography are at: https://markupdeclaration.org/resources/bibliography.html#contribute.
The bibliography continues to grow, and we hope will help people understand the concept of declarative markup separate from the particular syntax in which they may be using declarative markup.
