The DevEver Documentation and Specification Language (DEDOC)

Introduction

This document specifies the DevEver Documentation and Specification Language (DEDOC). DEDOC is an XML schema and markup language intended for the specification of technical specifications, standards and documentation. For more information on DEDOC and its supporting tooling, see the DEDOC website.

How DEDOC is specified. Note that this specification is itself written as a Guile Scheme program, which, when executed, outputs XHTML with embedded RELAX NG schema definitions. Thus, this document is both human and machine-readable. Generally, the RELAX NG schema will be automatically extracted from this document to facilitate its further use for validation purposes.

Because the RELAX NG schema is written as part of this document, this document is the canonical source for the RELAX NG schema definitions for DEDOC. Thus, this document constitutes the normative specification for DEDOC for the purposes of both human-readable and machine-readable expressions.

Moreover, the expression of DEDOC herein, in which narrative is interweaved with RELAX NG definitions shown inline, constitutes an application of “literate programming” methodology to XML schema definition. This is directly inspired by other attempts to both apply literate programming to XML schema definition while simultaneously having a single source of truth for schema definition, most notably TEI's “One Document Does It All” (TEI ODD) model.

The choice of XHTML as the schema for this document was made to avoid circular dependencies on DEDOC.

Purposes of DEDOC. DEDOC is intended to support writing documentation once and producing multiple production quality output formats, including:

• XHTML (multiple pages);
• XHTML (single page);
• EPUB;
• PDF via ConTeXt XML, for the highest quality typesetting for print output;
• PDF via XSL-FO (low-quality output; ConTeXt preferred);
• man pages (in mdoc format); and
• plain text (RFC-style).

There exists an existing XML-based markup language, namely DocBook, which aims to cover much of this ground, but DocBook suffers from several issues:

• it is an expansive and extremely complex taxonomy, with a massive number of features unlikely to be fully supported by any given transformation toolchain;
• the available open source tooling for typesetting DocBook into print cannot produce output of as high a quality as TeX can (for production typesetting, commercially available XSL-FO implementations such as Antenna House's appear to be used);
• DEDOC aims to have better support for the high-fidelity yet ergonomic expression of figures and diagrams.

When designing a universal source format for documentation which aims to target the production of multiple output forms, the means by which diagrams are to be expressed becomes a potentially complicated question. In particular:

• production-quality PDF outputs require diagrams be incorporated in vector (PDF) form for acceptable quality;
• modern XHTML outputs require diagrams in SVG form if they are to be resolution-independent;
• older web or EPUB devices might require diagrams be provided in raster (e.g. PNG) form.

What complicates this matter further is that diagrams may contain text. Where a specific typesetting system is used such as TeX, it is likely to be jarring if text in a diagram is rendered differently to the main body text, as there can be distinctive differences in rendering. Conversely, if a diagram has its text typeset in TeX, because the diagram was generate via TeX, it may be jarring for such a diagram to appear inside a web page.

Thus, the following determinations are made:

• Firstly, that it may be inevitably necessary for different input representations to be used for generation of different output formats. For example, a diagram might be provided as two files, one to be used for XHTML output and one to be used for PDF output.

  This is not constrained to just diagrams. For example, a piece of mathematics might need to be expressed both as TeX code (for use when generating PDF output) and as MathML code (for web use). (Though ConTeXt does support MathML input, it is anticipated that there will be cases where its MathML support is inadequate for complex formulas.)

  Thus a general solution of forks is adopted. A fork is a construct inside a DEDOC document whereby a processor consuming a DEDOC document chooses exactly one of the forks, and is free to choose the fork most appropriate to it. For example, a math formula might be expressed in a fork containing both MathML and TeX representations, or a diagram might be expressed in a fork containing SVG, PDF and PNG representations.

• Secondly, support for diagrams receive specific attention. A diagram is essentially expressed as a fork (though it may be a degenerate fork containing only one representation). Diagrams may be expressed in a variety of formats, such as external SVG, PDF or raster files, or as some kind of program or program fragment which, when executed, generates the desired diagram. An example of the latter is the TikZ DSL for drawing diagrams which has been implemented on top of TeX, but there are also countless other examples of non-TeX programs which are designed to consume some kind of textual input and generate diagrammatic outputs, such as Asymptote. This constitutes a very convenient and time-saving way for developers to express (and version control) diagrams which might otherwise have to be created manually inside a graphical editor and versioned as opaque binary files created by graphical editing tools.

  A diagram fork thus specifies one or more representations; each representation specifies its format, and either its text or a filename containing the representation data. If multiple representations are provided, an output generator is free to choose the one best suited to its output format.

  In some cases, the desired output format may be especially “aligned” with a provided representation. For example, if a diagram is provided as TikZ code, and the output is being produced using a TeX processor, rather than generating the diagram as a vector file and embedding it, the TikZ code can be directly executed inside the TeX environment during the typesetting process. This has the advantage that the diagram inherits any font and other settings applied to the TeX document and thus matches the look and feel of the rest of the output as closely as possible.

  In other cases, the only provided representations may be “unaligned”. If the provided representation is a raster or vector image, it is simply included directly. Another example of an unaligned representation is TikZ input code where the desired output is XHTML; in this case, TeX must be invoked for each such diagram to produce SVG output for that diagram alone. Compare this with when TeX is being used for typesetting, where the TikZ code is simply included into the document and does not result in a separate invocation of TeX. This process should be managed automatically, so that TikZ can be used to generate diagrams for both XHTML and TeX (PDF) output methods.

  Numerous other text-input diagram generators are available and it is anticipated that these will generally require the invocation of some external program for both the TeX and XHTML output pathways; thus the diagram support in DEDOC must be extensible to arbitrary external processing tools.

  Although diagrams are modelled as forks and thus can have an author write or provide multiple input representations if truly necessary to maintain acceptable fidelity across all output formats, it is anticipated that in the majority of cases it will be possible to generate acceptable quality diagrams from a single source and DEDOC focuses on ensuring that this is the case.

Schema Resources

The namespace URI for DEDOC is “https://www.devever.net/ns/dedoc”.

Where used, namespace prefixes in this document refer to the following namespaces:

namespace mml = "http://www.w3.org/1998/Math/MathML"
namespace xlink = "http://www.w3.org/1999/xlink"
namespace bib = https://www.devever.net/ns/bib
namespace local = ""
datatypes xsd = "http://www.w3.org/2001/XMLSchema-datatypes"

This page is RDDL-enabled. The following schema artifacts generated from this document are available:

• RELAX NG schema for this namespace
• RELAX NG compact schema for this namespace

For more information on the tooling surrounding DEDOC, see the DEDOC website.

Overall Structure

The DEDOC language is composed of three layers:

• inline-level constructs, the lowest layer;
• block-level constructs;
• structural constructs, the highest layer.

Inline constructs contain text and other inline constructs, block-level constructs contain other block constructs and inline constructs, and structural constructs contain other structural constructs or block-level constructs. Inline constructs are constructs which occur inside a single paragraph and often tend to relate to the horizontal formatting of text. Block constructs include the paragraph (p) element and other constructs and tend to relate to the vertical layout of text. Structural constructs group blocks and create a hierarchical logical document structure.

The remainder of this document introduces the three layers, starting with the lowest layer and building upwards.

The root element is doc:

Structural Constructs

Block Constructs

Block constructs contain other block constructs, inline constructs or text, and generally relate to the vertical layout of text in a document.

Inline Constructs

Inline constructs contain text and other inline constructs, and generally relate to the horizontal formatting of text within a given paragraph.

Escape Hatches

Provides constructs which should not be used unless absolutely necessary, because they expose the semantics of underlying typesetting systems.

Miscellaneous Definitions