-
Notifications
You must be signed in to change notification settings - Fork 66
XIONDoc XML
XIONDoc 1.2 was a horrible mishmash of regexes that parsed an ungodly hybrid of not-really-XML and Wiki-esque syntax. A list of the many things that it did wrong as a result were described in Issue 11 in the Google Code repository.
XIONDoc 1.3 does actual proper XML parsing, with no more Wiki-esque syntax crap. This page used to serve as a brainstorming area for what that XML syntax would be.
A term is a particular vocabulary item in an XION dialect.
A term element contains section elements.
In XIONDoc 1.2, each term had a major section in an HTML file containing all terms of a certain type. This is stupid -- it means the browser has to load the documentation for all those terms instead of just the one term we're after, and it's terrible for SEO. In XIONDoc 1.3, each term will have its own independent HTML page.
Each term should have navigation that allows you to go to the previous or next term alphabetically, both of the same type and overall.
<structure> - a control structure, such as if or repeat.
<keyword> - a miscellaneous keyword, such as of or the.
<event> - an event handler, such as keyDown or mouseUp.
<command> - a command, such as put or sort.
<function> - a function, such as sqrt or atan2.
<datatype> - a data type, such as number or string.
<property> - a property, such as itemDelimiter or textFont.
<operator> - an operator, such as + or contains.
<constant> - a constant, such as pi or ten.
<ordinal> - an ordinal, such as third or next.
<iomethod> - an I/O method, such as text or binary.
<iomanager> - an I/O manager, such as URL or file.
<extlang> - an external language, such as appleScript or perl.
<version> - something you can get the version of.
The documentation for each term can have several sections.
A section element contains block elements.
Each section is rendered with a heading in bold small caps.
<syntax> - The syntax of the term, and any notes about the metavariables. Typically includes <syn> and <p> blocks.
<examples> - Examples of the term in use. Typically includes <scr> blocks. The heading is rendered as "Example" if there is only one <scr> block, or "Examples" if there are multiple <scr> blocks.
<description> - The description of the term. Typically includes <p> and <table> blocks.
<scripts> - Scripts demonstrating use of the term. Typically includes <scr> blocks. The heading is rendered as "Script" if there is only one <scr> block, or "Scripts" if there are multiple <scr> blocks.
<notes> - Other notes about the term. Typically includes <p> and <table> blocks. The heading is rendered as "Note" if there is only one block, or "Notes" if there are multiple blocks.
<security> - Notes specifically about security. Typically includes <p> blocks.
<compatibility> - Notes specifically about compatibility. Typically includes <p> blocks.
A block is a generalization of a paragraph, basically. I don't really know how else to explain it.
Any block can have an indent attribute with a number indicating indentation level. Each indentation level is about half an inch.
Specified with the <scr> tag.
The content is verbatim text -- it cannot include any tags, as any such "tags" will appear literally.
The content is taken literally and split on line breaks. For each line, any trailing whitespace is stripped off. Then any blank lines at the beginning or end are removed.
If and only if any blank lines were removed from the beginning, the leading whitespace of the first remaining line is removed from all lines. Otherwise, all leading whitespace is removed from all lines.
Specified with the <syn> tag.
The <syn> tag can contain literal text, as well as <mv>, <opt>, <ch>, and <me/> tags.
Literal text represents a keyword, and is rendered in monospace type. Whitespace is collapsed to a single space.
The <mv> tag can contain only literal text. It represents a metavariable, and is rendered in italic type. Whitespace is collapsed to a single space.
The <opt> tag can contain anything the <syn> tag can contain. It represents optional syntax, and is rendered surrounded by brackets.
The <ch> tag can contain <ci> tags. It represents an alternation, and is rendered surrounded by parentheses, with the alternatives delimited by vertical bars.
The <ci> tag can contain anything the <syn> tag can contain. It represents an alternative inside a <ch> tag.
The <br/> tag represents a line break in the term's syntax, a common occurrence among control structures. Each line of a syntax block alternates between unindented and indented.
The <me/> tag represents the name of the term.
Specified with the <ul> or <ol> tag.
The <ul> or <ol> tag can contain <li> tags, indicating list items, and <ul> and <ol> tags, indicating nested lists.
The <li> tag can contain literal text and spans.
Specified with the <table> tag.
The <table> tag can contain <tr> tags, indicating table rows.
The <tr> tag can contain <th> and <td> tags, indicating table cells.
The <th> or <td> tag can contain literal text and spans.
Specified with the <p> tag.
Can contain literal text and spans. Cannot contain blocks. (HTML allows such a thing, but we don't, to make things simpler.)
There is no <blockquote> per se. You can use the <blockquote> tag, but the parser will turn it into a paragraph indented one further level.
Specified with the <h1>, <h2>, <h3>, <h4>, <h5>, or <h6> tag.
Can contain literal text and spans.
Specified with the <hr/> tag.
Specified with the <img/> tag.
Must have a src attribute for the image name. Can have width and height attributes for the image size. Can also have alt and title attributes.
Spans are fragments of text that are formatted.
Can contain literal text and further spans.
<img/> - An image. Must have a src attribute for the image name. Can have width and height attributes.
<b> or <strong> - bold text
<i> or <em> - italic text
<u> - underlined text
<s> - struck-through text
<sup> - superscript text
<sub> - subscript text
<big> - big text
<small> - small text
<c> or <tt> or <code> - monospaced text
<span> - A generic span. Can have a style attribute with a CSS style.
<a> - A hyperlink. Must have an href attribute for the link destination. This can be an external URL, or another term. A link to another term looks like cm:put or fn:atan2 or whatever. Links to other terms are rendered in monospace font. The content is optional; if it is empty, the URL or name of the term will be rendered instead.
<if> - Conditional text. Must have a dialect, module, or library attribute to determine which dialects, modules, libraries, and versions of same will have this text in their documentation. In addition to literal text and spans, can contain <else> tags for the negation of the condition.
The format of the dialect, module, and library attributes is a comma-delimited list of dialect, module, or library names, each of which may have a version number range appended, which would look like this:
oxn : all versions of OpenXION
oxn 1.3 : OpenXION 1.3 only
oxn 1.3+ : OpenXION 1.3 and all later versions
oxn +1.3 : all versions after, but not including, OpenXION 1.3
oxn 1.3- : OpenXION 1.3 and all earlier versions
oxn -1.3 : all versions before, but not including, OpenXION 1.3
oxn 1.0-1.2 : OpenXION versions 1.0 through 1.2, including both 1.0 and 1.2
oxn +1.0-1.2 : OpenXION versions 1.0 through 1.2, excluding 1.0 but including 1.2
oxn 1.0--1.2 : OpenXION versions 1.0 through 1.2, including 1.0 but excluding 1.2
oxn +1.0--1.2 : OpenXION versions 1.0 through 1.2, excluding both 1.0 and 1.2
oxn 1.3* : equivalent to 1.3--1.4; OpenXION 1.3 or later, but not OpenXION 1.4 or later
<else> - Valid only inside an <if> tag; text that will appear if the condition is false.
<br/> - A line break.
<dia/> or <mod/> or <lib/> - The name of this dialect, module, or library.
<ver/> - The version number of this dialect, module, or library.
<me/> - The name of this term, rendered in monospace font.
<!--
This is the XIONDoc 1.3 DTD.
XIONDoc 1.3 replaces XIONDoc 1.2's horrible mishmash
of XML and Wiki markup with clean, valid, structured XML.
Date: 2011/06/04 22:17:10 PST
Author: Rebecca Bettencourt <[email protected]>
XIONDoc 1.3 includes additional syntactic constraints
that cannot be expressed within the DTD. However,
violations of these constraints are mostly silently
ignored by the XIONDoc parser.
-->
<!ENTITY % verbatim "( #PCDATA )"><!-- actually CDATA, but that would make it not XML -->
<!ENTITY % plain "( #PCDATA )">
<!ENTITY % syntactic "( #PCDATA | mv | opt | ch | br | me )*">
<!ENTITY % formatted "( #PCDATA | img | b | strong | i | em | u | s | sup | sub | big | small | c | tt | code | span | a | if | br | dia | mod | lib | ver | me )*">
<!ENTITY % condition "( #PCDATA | img | b | strong | i | em | u | s | sup | sub | big | small | c | tt | code | span | a | if | else | br | dia | mod | lib | ver | me )*">
<!ENTITY % blockseq "( scr | syn | ul | ol | table | p | blockquote | h1 | h2 | h3 | h4 | h5 | h6 | hr | img )*">
<!ELEMENT xiondoc ( summary | description | dialect | module | library | article | structure | keyword | event | command | function | datatype | property | operator | constant | ordinal | iomethod | iomanager | extlang | version )*>
<!ELEMENT dialect ( name, title, versions, summary?, description?, article* )>
<!ELEMENT module ( name, title, versions, summary?, description?, article* )>
<!ELEMENT library ( name, title, versions, summary?, description?, article* )>
<!ELEMENT article ( name, title, summary, content )>
<!-- TERMS -->
<!ELEMENT structure ( name+, syntax, examples?, description, scripts?, notes?, security?, compatibility?, see-also? )>
<!ELEMENT keyword ( name+, applies-to?, syntax, examples?, description, scripts?, notes?, security?, compatibility?, see-also? )>
<!ELEMENT event ( name+, syntax, examples?, description, scripts?, notes?, security?, compatibility?, see-also? )>
<!ELEMENT command ( name+, syntax, examples?, description, scripts?, notes?, security?, compatibility?, see-also? )>
<!ELEMENT function ( name+, syntax, examples?, description, scripts?, notes?, security?, compatibility?, see-also? )>
<!ELEMENT datatype ( name+, syntax, examples?, description, descriptors, properties, scripts?, notes?, security?, compatibility?, see-also? )>
<!ELEMENT property ( name+, applies-to, syntax, examples?, description, scripts?, notes?, security?, compatibility?, see-also? )>
<!ELEMENT operator ( name+, precedence, description-short, syntax, examples?, description, scripts?, notes?, security?, compatibility?, see-also? )>
<!ELEMENT constant ( name+, type, value, examples?, description, scripts?, notes?, security?, compatibility?, see-also? )>
<!ELEMENT ordinal ( name+, value, examples?, description, scripts?, notes?, security?, compatibility?, see-also? )>
<!ELEMENT iomethod ( name+, examples?, description, scripts?, notes?, security?, compatibility?, see-also? )>
<!ELEMENT iomanager ( name+, examples?, description, scripts?, notes?, security?, compatibility?, see-also? )>
<!ELEMENT extlang ( name+, examples?, description, scripts?, notes?, security?, compatibility?, see-also? )>
<!ELEMENT version ( name+, examples?, description, scripts?, notes?, security?, compatibility?, see-also? )>
<!-- SECTIONS -->
<!ELEMENT name %plain;>
<!ATTLIST name
dialects CDATA #IMPLIED
modules CDATA #IMPLIED
libraries CDATA #IMPLIED
>
<!ELEMENT title %plain;>
<!ELEMENT versions %plain;>
<!ELEMENT summary %plain;>
<!ELEMENT description %blockseq;>
<!ELEMENT content %blockseq;>
<!-- TERM SECTIONS -->
<!ELEMENT applies-to %plain;>
<!ELEMENT precedence %plain;>
<!ELEMENT description-short %plain;>
<!ELEMENT type %plain;>
<!ELEMENT value %plain;>
<!ELEMENT syntax %blockseq;>
<!ELEMENT examples %blockseq;>
<!ELEMENT descriptors %plain;>
<!ELEMENT properties %plain;>
<!ELEMENT scripts %blockseq;>
<!ELEMENT notes %blockseq;>
<!ELEMENT security %blockseq;>
<!ELEMENT compatibility %blockseq;>
<!ELEMENT see-also %plain;>
<!-- SCRIPT BLOCKS -->
<!ELEMENT scr %verbatim;>
<!ATTLIST scr indent CDATA #IMPLIED>
<!-- SYNTAX BLOCKS -->
<!ELEMENT syn %syntactic;>
<!ATTLIST syn indent CDATA #IMPLIED>
<!ELEMENT mv %plain;>
<!ELEMENT opt %syntactic;>
<!ELEMENT ch ( ci )*>
<!ELEMENT ci %syntactic;>
<!-- LIST BLOCKS -->
<!ELEMENT ul ( li | ul | ol )*>
<!ATTLIST ul
indent CDATA #IMPLIED
border CDATA #IMPLIED
>
<!ELEMENT ol ( li | ul | ol )*>
<!ATTLIST ol
indent CDATA #IMPLIED
border CDATA #IMPLIED
>
<!ELEMENT li %formatted;>
<!-- TABLE BLOCKS -->
<!ELEMENT table ( tr )*>
<!ATTLIST table
indent CDATA #IMPLIED
border CDATA #IMPLIED
>
<!ELEMENT tr ( th | td )*>
<!ELEMENT th %formatted;>
<!ATTLIST th
colspan CDATA #IMPLIED
rowspan CDATA #IMPLIED
>
<!ELEMENT td %formatted;>
<!ATTLIST td
colspan CDATA #IMPLIED
rowspan CDATA #IMPLIED
>
<!-- PARAGRAPH BLOCKS -->
<!ELEMENT p %formatted;>
<!ATTLIST p indent CDATA #IMPLIED>
<!ELEMENT blockquote %formatted;>
<!ATTLIST blockquote indent CDATA #IMPLIED>
<!-- HEADING BLOCKS -->
<!ELEMENT h1 %formatted;>
<!ATTLIST h1 indent CDATA #IMPLIED>
<!ELEMENT h2 %formatted;>
<!ATTLIST h2 indent CDATA #IMPLIED>
<!ELEMENT h3 %formatted;>
<!ATTLIST h3 indent CDATA #IMPLIED>
<!ELEMENT h4 %formatted;>
<!ATTLIST h4 indent CDATA #IMPLIED>
<!ELEMENT h5 %formatted;>
<!ATTLIST h5 indent CDATA #IMPLIED>
<!ELEMENT h6 %formatted;>
<!ATTLIST h6 indent CDATA #IMPLIED>
<!-- HR BLOCKS -->
<!ELEMENT hr EMPTY>
<!-- IMAGES -->
<!ELEMENT img EMPTY>
<!ATTLIST img
indent CDATA #IMPLIED
src CDATA #REQUIRED
width CDATA #IMPLIED
height CDATA #IMPLIED
alt CDATA #IMPLIED
title CDATA #IMPLIED
>
<!-- SPANS -->
<!ELEMENT b %formatted;>
<!ELEMENT strong %formatted;>
<!ELEMENT i %formatted;>
<!ELEMENT em %formatted;>
<!ELEMENT u %formatted;>
<!ELEMENT s %formatted;>
<!ELEMENT sup %formatted;>
<!ELEMENT sub %formatted;>
<!ELEMENT big %formatted;>
<!ELEMENT small %formatted;>
<!ELEMENT c %formatted;>
<!ELEMENT tt %formatted;>
<!ELEMENT code %formatted;>
<!ELEMENT span %formatted;>
<!ATTLIST span style CDATA #IMPLIED>
<!ELEMENT a %formatted;>
<!ATTLIST a href CDATA #IMPLIED>
<!ELEMENT if %condition;>
<!ATTLIST if
dialect CDATA #IMPLIED
module CDATA #IMPLIED
library CDATA #IMPLIED
>
<!ELEMENT else %formatted;>
<!ELEMENT br EMPTY>
<!ELEMENT dia EMPTY>
<!ELEMENT mod EMPTY>
<!ELEMENT lib EMPTY>
<!ELEMENT ver EMPTY>
<!ELEMENT me EMPTY>
Home - Downloads - Installation - Sample Code