I am writing the documentation in DocBook format, but I have created a new surface syntax for XML. XML's standard surface syntax is too verbose, and I didn't want to have to write it by hand.
I'm calling the new surface syntax XXML (let's say it stands for Extra Extra Medium Large).
Here's an example:
XXML | XML |
---|---|
{\tag attr={value}: body} | <tag attr="value">body</tag> |
The curly brackets are a grouping construct which is independent from the tag. They introduces blocks. When a tag's attributes are terminated with a colon, the tag works greedily: it applies to all of the text up to the end of the block.
XXML | XML |
---|---|
{\tag1: \tag2: body} | <tag1><tag2>body</tag2></tag1> |
If you end a tag's attributes with a hyphen "-" rather than a colon ":", the tag consumes upto the end of the line. This is useful because no closing bracket is required.
XXML | XML |
---|---|
{\ul: \li- list item 1 \li- list item 2 \li- list item 3 } | <ul> <li>list item 1</li> <li>list item 2</li> <li>list item 3</li> </ul> |
Ending a tag with a tilde "~" will consume the following paragraph, ie. upto the next empty line.
XXML | XML |
---|---|
{\ul: \li~ blah blah blah \li~ paragraph list entry } | <ul> <li>blah blah blah</li> <li>paragraph list entry</li> </ul> |
Those last examples use the HTML tags "ul" and "li". DocBook has longer names for the same thing, "itemizedlist" and "listitem", and it also requires you to use "para" tags in the "listitem"s.
XXML | XML |
---|---|
{\itemizedlist: \listitem\para- list item 1 \listitem\para- list item 2 \listitem\para- list item 3 } | <itemizedlist> <listitem><para>list item 1</para></listitem> <listitem><para>list item 2</para></listitem> <listitem><para>list item 3</para></listitem> </itemizedlist> |
Note that
\listitem\para- text
is an abbreviation for
\listitem- \para- text
XXML provides some help in writing paragraphs, so you don't have to write "p" or "para" tags explicitly. The "ps" tag will treat empty lines in the input as paragraph breaks. It is expanded out by a postprocessor. This is similar to how you write paragraph breaks in TeX.
XXML | XML |
---|---|
{\ps: A paragraph. Another paragraph. } | <para>A paragraph.</para> <para>Another paragraph.</para> |
A tag without a body can be terminated with a semicolon ";".
XXML | XML |
---|---|
\hr size=4; | <hr size=4> |
There is no special escape sequence for writing XML entities. A tag whose name begins with "E" is converted into an entity. It should not have attributes or a body. (Note that tag names are case sensitive.)
XXML | XML |
---|---|
\Eamp; | & |
You can specify the literal characters '\', '{' and '}' by prefixing them with another backslash.
XXML has the following advantages:
You don't have to write the tag name in the closing tag.
It's easier to do search and replace on the name of a tag.
When writing XML, it's easy to forget that '<' and '&' are special characters that have to be escaped. '\' and '{' and '}' are perhaps a bit more unusual.