Augmented Plain Text (APT) Version 1.0

Syntax

APT uses keywords that start with a hash symbol (e.g., #AUTHOR) that occur in column 1 (i.e., the beginning of a line) to denote an APT statement. APT parsers should ignore keywords occurring elsewhere, or unknown keywords (perhaps emitting a warning when this occurs), so that other instances of hash characters followed by unknown tokens have no effect (other than to be replicated in the output file).

The APT syntax is designed according to implementation levels, to allow for varying levels of support. Level 1 is quite simple, Level 2 provides general link support, with Level 3 providing inclusions and other features.

Level 3 APT processors may optionally preserve HTML markup occurring inline but Level 1 and 2 processors should autogenerate the document title, headings, divisions and paragraphs, as well as a table of contents using heading titles. Future optional features will include autogeneration of hierarchical section numbers. Note that if necessary, a hash character can be escaped using its XML character entity equivalent ("#"). A processor should be labeled as according to its implementation level.

All APT statements start with an APT keyword beginning in column one and continue to the end of the line. Lines may be continued with a backslash onto the next line.

#LINK is a bit of a special case. APT processors will note the beginning of http: and ftp: URLs (scanning until the first whitespace or end-of-line) and autogenerate XHTML links where they exist, using the URL itself as the link text, unless the token following the URL is #LINK, in which case the link text being the content following #LINK to the end of that line.

APT Level 1

The following keywords should be supported in all APT Level 1 processors:

#APT WS version

required APT header

#AUTHOR WS content

author name

#EMAIL WS content

author email

#TITLE WS content

document title

#SUB WS content

document subtitle

#SELF WS linkURL

URL reference to this document

#TITLE WS content

document title

#COM WS content

comment (ie., as XML comment)

#SETHEAD WS [1-6]

sets top level heading (default is 1)

#HEAD WS content

document heading

#DFN WS term "|" definition

definition list item

#LI WS content

list item (unordered)

#HR WS [percentage]

horizontal rule [optional width]

#PRE WS content

preformatted content

("WS" stands for whitespace: space or tab characters)

APT Level 2

The following keywords should be supported in all APT Level 2 processors:

#LINK WS linkURL WS link text

a web link

#IMG WS imageURL WS alt text

an image

#FIG WS imageURL WS alt text

an image treated as a figure

#LOGO WS imageURL WS alt text

a logo image for top-of-page

APT Level 3

The following keywords should be supported in all APT Level 3 processors:

#INCLUDE WS linkURL

a transclusion (see note)

Additionally, Level 3 processors should allow for a subset of existing inline HTML markup to be normalized and preserved in output.

Examples:

    #APT V1.0
    #AUTHOR Igor Rostropovich
    #EMAIL igor@rostropovich.org
    #SETHEAD 2
    #HEAD It Takes a Virtual Village \
    To Make a Virtual Village Idiot

Whitespace between blocks of plaintext will automatically create paragraph breaks. The document will use #TITLE as both the document title and its first displayed <h1> heading, the remainder of headings being <h2> headings. The TOC is autocreated from headings.

Transclusions: Note that filenames or URLs must be in double quotes. For example, to include an external file as an answer to a question:

     #DFN My first question is how many monkeys? |
     #INCLUDE "answer1.html"

NOTE: currently unsupported are #INCLUDE and backslashes to continue lines.

A sample of an APT source and the generated output from Ceryle:

• sample1.apt (the APT source)
• sample1.html (the XHTML output)
• apt.css (the APT stylesheet used)