A document is always a single pretext element below the root. There are two divisions, a docinfo, which is a database of sorts about the document, along with a sibling element that indicates the type of the document and contains all the content. start is the way to specify the lone top-level element as part of the schema, so it will not be used again.

letter and memo elements are not documented.

A document is typically divided into sections. But we reserve the word section for one very specific type of division. To avoid confusion, we speak generically of divisions. So, for example, a section is a division of a chapter. Here we list all of the possible divisions, even if they are not available in each document type.

An appendix looks like a chapter of a book, with the option to have a notation-list as its entire contents. It is possible this is not the best structure for an article, which might best be divided by subsection.

There are several things to note (expand this): always a title, dead-end with blocks, or subdivide with optional intro and conclusion.

The paragraphs element, which is not to be confused with a real paragraph as implemented by the p element, is an exceptional type of division (both in design and utility). It must have a title, can appear anywhere within any of the divisions, cannot be further subdivided, and is not ever numbered. Its contents are conceptually a run of paragraphs, but as described here allow much more than that.

It is especially useful in a short document (like a class handout, letter, memorandum, or short proposal) where numbered divisions might feel like overkill.

The NoNumber variant allows for light-weight sectioning of un-numbered divisions, such as a Preface.

commentary is elective, so should not have any numbered items ever, so the NoNumber provision is implicit.

We add specialized divisions, which may appear within any of the above divisions. Titles will be provided as defaults.

Most elements are about delineating structure. What you actually write happens in very few places. Principally paragraphs, but also titles, captions, index headings, and other short bursts. The shorter the burst, the more likely the text will be recycled in other places (Table of Contents, List of Figures, or Index perhaps). And the more text gets re-purposed, the more care we need to take with its contents.

Simple text is simply runs of characters, some of which is accomplished with empty elements. This is used for names of people, It should not be confused with the RELAX-NG keyword text which matches runs of (Unicode) characters, with no intervening markup. So the latter is used for things like URLs, internal identifiers, configuration parameters, and so on.

Short text is used for titles, subtitles, names, index headings, and so on. It allows a variety of characters, font styling, groupings, and convenience constructions. It does not allow for references, nor anything that typographically requires more than the linearity of a sentence. In other words, no lists, no images, no tables, no displayed equations. Because of the potential for movement, we also do not include footnotes within short text.

Long text is everything that is short text, but also allows for references, both external (internet URLs) and internal (cross-references). It is used for the content of footnotes and captions. The variant allows for variables in inline mathematics.

A paragraph is a key bottleneck between structure and prose. You can use a variety of constructs in a paragraph, and you may use a paragraph in many places. So the name of the element is very simple, just a p. Now you can include footnotes, display mathematics, display verbatim text, and lists. Note that a list can only occur in a paragraph, so to make nested lists you must structure a list item of the exterior list with a paragraph to contain the interior list. A paragraph can contain some metadata, like index entries and mathematical notation. It does not have a title, nor is it ever numbered. It can be the target of a cross-reference, but only with some care.

A lined paragraph is a variant, for use when the line-by-line structure is necessary. The variant of a p element allows for using the var element as an answer blank or generated content, possibly inside mathematics, and possibly inside lists.

Note: A paragraph effectively could have the MetaDataTarget pattern, except that we allow index elements (idx) to go anywhere within the paragraph.

Fundamentally allows for conversion to other markup languages, such as or HTML, and of course XML is a syntax for designing a markup vocabulary. As such, certain characters traditionally found on keyboards have been co-opted for special purposes. And once you actually want one of those special characters, you need an escape character to indicate a normal use. For these reasons, certain characters have empty elements to represent them.

Special characters for XML are the ampersand, less than, greater than, single quote and double quote: &, <, >, ', ". The ampersand is the escape character for XML. In practice, the first two characters are the most important, since processing of your XML will be confused by any attempt to use them directly. So in regular text (not mathematics, not verbatim), always use the the escaped versions: &amp;, &lt;, and perhaps &gt;.

See below for elements that can be used to form groupings with left and right delimiters. For example, a simple quotation should use a left double quote and a right double quote, and these characters should look different (so-called smart quotes). Notice that a keyboard only has a single dumb quote. If you need these characters in isolation (, not in pairs), these elements are the best way to ensure you get what you want in all possible conversions. Note that left and right braces , {, } (curly brackets); brackets, [, ]; may be used directly. To create individual, left or right, create angle brackets us the elements here, not the keyboard characters (which are different).

A space is a space. But sometimes you want a space between two associated items which will not get split across two lines (, Chapter23). An element will create a non-breaking space using the right technique for the conversion at hand.

There is a variety of dashes of various lengths. Use the keyboard character for a hyphen, use an ndash to separate a range of numbers or dates, and use an mdash as punctuation within a sentence to isolate a clause. These are implemented differently for different conversions, so their use is strongly encouraged.

A fillin blank is not really a character, but maybe a really long, low dash? The characters attribute controls the length. It is atomic, indivisible, and content-less, like all the other characters. fillin is also unusual due to its allowed use within mathematics.

We define a few characters to help with simple arithmetic expressions authored within regular text. (Perhaps you are writing a novel with .) These are for simple uses in regular text, not for actual mathematics, which is described later. The solidus is slightly different from the slash found on a keyboard and is used for fractions and ratios. The minus is for subtraction and negation, and is not a hyphen or dash. An obelus is better known as a division sign. degree, prime, and dblprime are designed for specifying coordinates in degrees, minutes, and seconds. Use the unambiguous + keyboard character for addition.

The following are largely conveniences. They are typically not available on keyboards, and their implementations for various conversions can involve some subtleties. Again, their use is encouraged for the best quality output.

Icons are available through a name attribute, which is meant to usually be more semantic than just a description of the picture, though that may sometimes be the case. These are intended for use when describing elements of computer interfaces. Icons which are decorative should be supplied as part of styling, not as part of the source language.

The kbd element will produce something akin to a calculator key or a keyboard key. It may have (simple) content, which will be reproduced as the label of the key, or it may have a name attribute which describes a key that looks more like a graphic, such as an arrow key.

We support musical notation as if they were characters: accidentals, scale degrees, notes, and chords. Implementation of these is about as complicated as inline mathematical notation, hence they have identical rules about placement.

There are empty elements to generate certain items, like the date, or names of commonly referenced tools, such as itself. These include some common Latin abbreviations, for the purpose of handling the periods properly in conversions to .

A large class of similarly indivisible items are units on physical quantities. The quantity element is allowed to be empty, and the code should silently produce no output. Expressing non-emptiness here might get a bit messy, so a Schematron warning could be a good alternative.

Some markup is for just ASCII characters, in other words, unadorned verbatim text.

Simple markup is groupings of text that gets a different typographic appearance, either through font changes or through delimiters. Examples are emphasis or paired quotations, non-examples are cross-references or footnotes.

Abbreviations are sequences of characters that shorten some longer word or words ( vs. for the Latin versus), initialisms are formed from the first letters of a sequence of words ( HTML), acronyms are pronounceable as words ( SCUBA).

Notice that long text can be part of a grouping construction, and that long text can can contain a group construction. The effect is that these groupings can be nested arbitrarily deep.

We use elements to get consistent typography when discussing itself. We could probably limit the content of these elements to lowercase letters and a hyphen. The definitions here will preclude any contained markup.

An empty taxon will match either version.

All mathematics appears inside paragraphs, and the syntax is that of , as supported by MathJax, whose supported commands and macros are meant to be very similar to those of the AMSMath package. Note that the content is typically unstructured, excepting fill-in-the-blank, variables (see variants), and internal cross-references in multi-row display mathematics. Also, md and mdn are not targets of cross-references, though their rows can be.

A text block is very similar to a paragraph. It can be an actual paragraph, a sequence of paragraphs enclosed as a block quote (with attribution, perhaps), or a large chunk of unformatted text presented typically in a monospace font. Certain atomic objects, such as an image may be placed as peers of paragraph-like objects.

A statement block is used in statements. What are those? Theorems have statements, exercises have statements, questions have statements. Some of these blocks with statements also have peers of statements that are proofs, hints, answers, and solutions. In statements, and their peers, we include text blocks, captioned items, asides, side-by-side layouts, and Sage computations, but exclude many of the numbered and titled division blocks. A slight extension is a solution block, which is everything that can go in a statement, plus one or more proof, only as part of a hint, answer, or solution.

A division block includes text blocks, statement blocks, plus topical chunks of text that can have numbered headings or numbered captions, with optional titles, and are set apart slightly from the surrounding narrative. These are placed mostly as children of divisions, and so one cannot contain another. They certainly contain paragraphs, and all that goes into them, such as mathematics (inline and display) and figures (and other captioned items). The sidebyside element can be used to illustrate a division block with a variety of images and displayed text in flexible layouts.

A fragment is used for literate programming, and is numbered, so it is allowed places where other numbered items go.

Other division blocks include poem, aside, and assemblage. These are never numbered, but can have titles. The list-of mechanism is a convenience device to automatically create lists of contents, and so we leave surrounding divisional structure to the author. A sidebyside, and its cousin, sbsgroup, are strictly layout devices. The sage element is unique for its possibilities in certain electronic formats.

demonstration is slated for removal or an overhaul, and so is in the . Avoid using them for now.

Blocks are often structured, in a light way. Hints, answers, and solutions adorn exercises, examples, and projects. A simple introduction or conclusion is sometimes useful. A prelude or postlude are authored inside a block and so are associated with it. But they are presented before and after the block visually. An interlude will be used between the statement of a theorem and its proof.

When a block is structured to allow some of the ancillary parts, a statement element is used to structure the main part. Hints, answers, and solutions can be the target of cross-references, but do not get author-supplied titles.

The introduction and conclusion containers can be used in a variety of other structured elements. They come in three levels, according to what they can contain, and are meant to be consonant with their surroundings. As children of a division, they may carry a title, which in turn allows them to be cross-referenced by that text.

A headnote is like an introduction, but does not have a symmetric concluding element, and is typically meant for specialized divisions, such as a glossary.

There are a variety of referencing mechanisms, external references, internal cross-references, index entries, and specialized support for a table of mathematical notation.

Footnotes are especially dangerous. They should contain quite a bit of content, and should be targets of cross-references. So the content is not as expansive as a regular paragraph, which is possibly too restrictive.

Index entries have two forms, simple and structured. The start and finish attributes are meant to use xml:id to create an index range that crosses XML boundaries. (Replace principal tags with idx/h/h.)

The actual index is generated within the index-part via the index-list element.

Note that we might point to another index entry as part of a see also mechanism.

A division may lead (first) with an optional list of objectives for the division and may be followed by a (final) optional list of outcomes. The element names are only chosen to reflect a pre- and post- behavior and so could be used for objectives, outcomes, and standards in a variety of ways.

These are a run of paragraphs, but may optionally have an attribution.

Large blocks of verbatim material, rather than just little bits in a sentence. A code display, cd, is an analog of a math display, and meant to be used within a paragraph, either as a single line of text, or optionally structured as several lines by using code lines, cline. pre is a block, which preserves line breaks and sanitizes whitespace to the left. It can be optionally structured as code lines. It should be thought of as a monospace analogue of a regular paragraph, minus indentation and automatic line-breaking.

Are complicated. Maybe we need a special type of paragraph which does not allow nesting a description list down into some other list?

As a container, the lists themselves get no metadata. But the numbered or titled list items do get metadata. To point to an entire list, make it a named list and point to that.

Definitions are special, there is nothing else quite like them. A statement, no proof, and also a natural place for notation entries.

Theorems, corollaries, lemmas they all have statements, and should have proof(s). Otherwise they are all the same. A proof may be divided with cases, in no particular rigid way, just as a marker of any number of different, non-overlapping portions of a proof. Titles can be used to describe each case, or implication arrows may be used (typically with a proof of an equivalence). A proof is also allowed to stand on its own as a block, independent of a structure like a theorem or algorithm.

Mathematical statements that do not have proofs (in other words, no proof is known, or a proof is not appropriate).

A favorite of Inquiry-Based Learning textbooks. Numbered independently. Possibly structured with task. Three different ways to structure this, we combine the second two so that the derived XML Schema (XSD) version is less-confusing to certain tools ( the Red Hat XML schema validator used within VS Code).

Really simple blocks, they do not have much structure, and so are just runs of paragraphs, though figure, table, listing, and list may be included.

Somewhat simple blocks, they do not have much structure, but can hold more than a Remark.

An aside is a deviation from the narrative, and might physically move in the presentation (say, to a margin, or to a knowl). biographical and historical may be further developed.

Since an assemblage is meant to accumulate significant content (as a review or summary, or for initial presentation) lists are allowed here, an exception to their restriction to paragraphs. We are also mildly restrictive about what can be content herein particular blocks are excluded, despite not strictly being blocks themselves.

These are containers that all carry titles (mandatory and optional), captions for two, and numbers. They need to be filled with other (atomic) items, which we generally call planar due to their two-dimensional and rigid characteristics. These have also called captioned items in the code, even if not all allow a caption.

The guts of a table go in a tabular element.

Page width or screen width, both are at a premium. Height goes on forever (barring physical page breaks) and we have many devices for demarcating that flow. But sometimes you need to organize items horizontally, side-by-side. We place the components of a sidebyside into generic regions of specified width called panels.

This is a pure layout device. So you cannot title it, nor caption it. It does not admit a xml:id attribute, since you cannot make it the target of a cross-reference. Nor can you reference it from the index (but you can point to its surroundings from the index).

Because of its utility, it can go anywhere a block can go (, as a child of a division) and it can go many other places as a sibling of a paragraph (such as to illustrate an example).

Note that widths give on a sidebyside override any width given to the components of the panels.

A stack allows non-captioned, non-titled elements to accumulate vertically in a single panel. It is a basic container.

A group of side-by-sides is designed to stack vertically with common controls on widths, etc. Its implementation is entirely experimental right now, even if we are relatively confident of the markup.

Raster, and described by languages, plus 100% duplicates. The variant is quite different.

Note: the ImageCode pattern allows an xml:id attribute since it is used to construct a filename.

Sage is integral.

Some specific interactive goodies. These are being phased-out in favor of a more general interactive element.

Well, just video right now. The xml:id is not used as a target, but rather as a name for a static preview image that is auto-generated by the pretext script thumbnail file, hence optional. preview maybe be one of two reserved switches, or the filename of a static preview image.

Note: the Video pattern allows an xml:id attribute since it is used to construct a filename for preview images (poster), especially when scraped.

Poems!

Inline, divisional, and . Exercises use task to structure parts, where before they used ordered lists for parts of a statement (to eventually be deprecated).

This is all stop-gap and will change radically. But it seems to work for now. So these rules should not be taken as definitive, at all.

A glossary is primarly built up as a sequence of glossary items,, using the gi element, by analogy with list items.

Expository, but with solutions, etc. (Borrows from exercises and projects.)

Modified versions of various aspects to allow authoring exercises.

Notes:

• Statements, hints and solutions do not require at least one paragraph, so may be just a table or figure (say).
• Are static and set elements mutually exclusive?
• Can the usage part of the var element be split across math and paragraphs?

Literate programming is a technique for documenting programs, with code fragments rearranged to create a syntactically correct program. A root fragment is indicated by filename which could have an xml:id, otherwise the xml:id is required.

Frequently used items, with no natural place to associate them.

Used on the end of prefaces to sign them, and on block quotes.

There is a handful of elements which describe an item, but do not necessarily get processed as content. Titles are an obvious example, and index entries are another. Here we isolate a few common patterns to use for consistency throughout.

Notes:

• Language tags go on the root element to affect variants of names of objects, like theorems.
• permid is part of managing editions, and is supplied by a script. You should not be adding these manually as an author. (You do want to manually author xml:id.)
• The xinlude mechanism may pass language tags down through the root element of included files to make them universally available.
• The xinclude mechanism inserts a @xml:base attribute on the root element of an included file. So we allow this attribute on any element that allows a title.
• These are not unordered specifications since they contain several attributes, and we enforce a title, subtitle, shorttitle, plaintitle, creator, caption, idx order.
• MetaDataTarget is for items that are targets of cross-references, but without even optional titles. Since they will be knowled, they can appear in an index. But without the potential to be titled, we do not set them up as possible root elements of a file to xinclude.
• MetaDataTitle has a required title.
• MetaDataAltTitle has a required title, and allows optional shorttitle and plaintitle.
• MetaDataSubtitle implicitly has a required title, and allows optional subtitle, shorttitle and plaintitle.
• A plaintitle means no markup whatsoever in the content, this is what plain means.
• MetaDataLinedTitle and MetaDataLinedSubtitle are variants of the AltTitle or Subtitle versions for use on larger divisions with line elements used to suggest line breaks in titles.
• MetaDataCaption implicitly has an optional title.
• Titles may contain external references (url) or internal cross-references (xref), but implementers need not make them active (, they maybe text only), since titles are prone to migrating to other locations.

Provisional items, with uncertain futures.

A list generator is a convenient device. It can create appendices, or smaller table-of-contents at the start of divisions.

Notation can be automatically generated. We restrict its locations to appendices.

Articles and books have material at the start, which gets organized in interesting ways. minilicense is very restrictive, shortlicense allows references ( URLs). titlepage is like a very small databasefor HTML it migrates to the top of the page for the frontmatter, and for it migrates to the half-title and title pages. Since it generally makes no sense as the target of a cross-reference, titlepage does not allow an @xml:id attribute.

A single contributors element may be placed into a preface and is a list of contributor. It can be optionally preceded, or followed, by all the usual things that can go into any preface. An AuthorByline is a special instance of acknowledging a contributor on a division.

Articles and books have material at the end, structured as a sequence of appendix. A solutions division should be numbered and rendered as if it was one of the appendix, and so can mix-in in any order.

The docinfo section is like a small database for the document.

A nice icon near the top of an electronic version is a nice touch, and can link back to a project landing page.

We add some items to the preamble for , latex-image, and asymptote. For a package to be in a latex-preamble, it needs to have an identical implementation, and be of the same name, as a version that exists for MathJax. Images specified by or Asymptote syntax sometimes need extra information in their preambles.

Macros for are shared across implementations. This should move under some general section, the name is too vague.

The style of text used in a cross-reference (the xref element) is contained in the source and uses the same per-item choices.

An initialism is a useful short version of a book title.

Online versions can request feedback via a URL for some form. Maybe this should really be an href for consistency. There should be a device to provide text to go with the link.

Some elements can be renamed. This should be a rare event. Since the content of this element can (optionally) be specified in different languages, the xml:lang attribute is appropriate.

Image archives have some global specification. The from attribute gives a root for only working on a subtree of the document. The content is a comma-separated list of file extensions.

An author biography (or several) might be a paragraph or two each, or each one might be several pages. This style can be controlled.

Many aspects of numbering are configurable. These choices affect the numbers printed, and so are an author's decision, and hence run with the source.

We collect all the specifications, roughly in a top-down order, so the generated schema files have a rational ordering to them, even if the order presented here is different.