Last updated
April 2, 2004
by Joshua Juran
with mml2html
Metamage Software Creations
Copyright 1998 Joshua Juran
Editor's note: Both this document and the mml2html script used to generate it have bugs, so please take that into consideration. While the technical details cannot be relied upon to remain operative (assuming they're even accurate, which some of them aren't), it is possible to get a clear picture of what MML is and what it's capable of, currently.
MML is a text markup language based on setext (structure-enhanced text) by Ian Feldman. It borrows the spirit of setext, many of its concepts, and even some of its syntax. MML's goal is slightly different, however. Whereas setext was meant primarily to be unobtrusive, MML allows the document author (at her option) to trade a degree of subtlety in the text display for a level of power and flexibility in the rendered display.
Even if you never use any MML-capable tools, MML offers the advantage of making your text more descriptive or easier to read -- for example, by underlining headings or setting a word in asterisks to denote emphasis. That people have been using conventions like these for years speaks to their value as tools for communication.
MML is even more useful when you need a document that can be easily digested by machines and humans alike.
Here's an example of the markup used in this section:
What does MML markup look like? =============================== Here's an example of the markup used in this section: ": What does MML markup look like? ": =============================== ": ": Here's an example of the markup used in this section:
(snip)
-- Concepts ********
MML is based on several key concepts.
A row is a sequence of characters terminated by a newline character. The newline character varies between systems, and MML agents must correctly interpret each such convention regardless of which system the interpretation occurs on.
Rows are traditionally called lines, but the term 'line' is used in a slightly different sense here.
A block is a consecutive group of rows that are interpreted in the same particular way. The specified interpretation method is then applied to the block's contents. If the interpretation includes MML block-level markup, then blocks can be nested. In fact, the entire content of an MML document occurs inside the root block.
Stripping the block markup from a row produces its corresponding line, which may itself be a row of another (nested) block.
A line is a row that does not contain block markup. A line is never part of a block, but is always inside a block. (A row may be part of a block.)
There are blank lines, text lines, and special lines.
Paragraphs are consecutive non-blank lines separated by blank lines.
(# MML-Header: value) This is removed from the text and does not appear inline, but may occur in some other way, e.g. as the filename.
(..) The entire line is ignored.
(..) Terminates the MML document. This line and everything following it is ignored. Any trailing whitespace will cause this to be treated as a comment instead.
MML uses single-character prefixes to specify block-level structure. The prefix character occurs at the beginning of each row of the block, followed by a space (which is optional if the line is a row of a sub-block). The block markup affects how the block is interpreted.
A quote or excerpt is prefixed by the double-quote character ("). Indentation or centering are both appropriate ways to render a block quotation. HTML generators should use <BLOCKQUOTE>.
This is the only block markup whose contents are interpreted normally as MML. The block quotation can contain other block markup such as preformatted and escaped blocks, but it doesn't make sense for an inclusion to appear in a quotation.
"Yields falsehood when preceded by its quotation" yields falsehood when preceded by its quotation.
Here's an example of a nested block quotation:
Fellow citizens, we shall not escape history.
That is what he said. That is what Abe Lincoln said.
Markup is not interpreted. This is useful for easily showing examples of word- or character-level markup that nonetheless wrap automatically.
Because lines still wrap, block markup gets garbled. Try preformatted.
A preformatted block can be used to display text-based graphics, or (of course) examples of line- or paragraph-level markup. Inside a preformatted block, all whitespace is left alone, and all text is displayed using a fixed-width font. HTML generators should use <PRE>.
There are two forms of preformatted block: the marked-up form (;) interprets word- and character-level markup, and the escaped form (:) does not. Mnemonic: The colon and semicolon characters are both used to mark line comments in other languages. Here, the colon indicates a full escape and the semicolon a partial one.
You can't use any block-level markup inside a preformatted block. The only one that would make sense anyway is the markup escape, and that's built into the escaped form.
The inclusion lets you include an entire document. Unlike traditional "here document" syntax, MML's inclusion prefix (|) clearly indicates where it begins and ends, and where in between it's nested (and how deeply).
Here's an example which is not in the best taste: inclusion haiku.
mml2html renders this with PRE.
Clever HTML generators might create a directory with the same root name as the HTML file, put included files there (recursively converting them as appropriate), and convert the inclusion to a link.
([n]) A footnote begins with a number inside a pair of brackets, followed by a space. The entire paragraph is considered to be the footnote. (Multi-paragraph footnotes?)
A list item line is distinguished by a bullet character (*, +, -) preceded by whitespace and followed by some text (with whitespace intervening).
Easy list:
The title element is indicated by a non-blank line, both preceded and followed by lines of equal length to itself, consisting solely of one of the heading characters (usually #).
########################################## Ethel the Aardvark Goes Quantity Surveying ########################################## Ethel the Aardvark was hopping down the...
A heading is a text line followed by a line of equal length filled with one of several characters (#, *, =, -) indicating which level it is (and preceded by a blank line).
Part Two ******** Chapter 7 ========= They were all standing in a circle...
A sequence of multiple, consecutive hyphens. Level 4 heading takes precedence.
There's emphasis...
...and then there's emphasis!
(There's even emphasis within emphasis.)
Used for foreign terms, like coup de grace.
When you need to grab some attention.
And now for the fine print.
Visit <http://www.metamage.com/> for more information.
Joshua Juran <wanderer@metamage.please.no.uce.com>
Try out these MML accessories.
See the sample footnote.[0]
[0] Please note that mml2html doesn't recognize footnotes, and MML's footnote markup is still under development.