| |
| The APT format |
| ~~~~~~~~~~~~~~ |
| |
| In the following section, boxes containing text in typewriter-like font are |
| examples of APT source. |
| |
| * Document structure |
| ~~~~~~~~~~~~~~~~~~~~ |
| |
| A short APT document is contained in a single text file. A longer document |
| may be contained in a ordered list of text files. For instance, first text |
| file contains section 1, second text file contains section 2, and so on. |
| |
| [Note:] Splitting the APT document in several text files on a section |
| boundary is not mandatory. The split may occur anywhere. |
| However doing so is recommended because a text file containing a |
| section is by itself a valid APT document. |
| |
| A file contains a sequence of paragraphs and ``displays'' (non paragraphs |
| such as tables) separated by open lines. |
| |
| A paragraph is simply a sequence of consecutive text lines. |
| |
| +------------------------------------------------------------------------+ |
| First line of first paragraph. |
| Second line of first paragraph. |
| Third line of first paragraph. |
| |
| Line 1 of paragraph 2 (separated from first paragraph by an open line). |
| Line 2 of paragraph 2. |
| +------------------------------------------------------------------------+ |
| |
| The indentation of the first line of a paragraph is the main method used by |
| an APT processor to recognize the type of the paragraph. For example, a |
| section title must not be indented at all. |
| |
| A ``plain'' paragraph must be indented by a certain amount of space. For |
| example, a plain paragraph which is not contained in a list may be indented |
| by two spaces. |
| |
| +-------------------------------------------------+ |
| My section title (not indented). |
| |
| My paragraph first line (indented by 2 spaces). |
| +-------------------------------------------------+ |
| |
| Indentation is not rigid. Any amount of space will do. You don't even need |
| to use a consistent indentation all over your document. What really matters |
| for an APT processor is whether the paragraph is not indented at all or, |
| when inside a list, whether a paragraph is more or less indented than the |
| first item of the list (more about this later). |
| |
| +-------------------------------------------------------+ |
| First paragraph has its first line indented by four |
| spaces. Then the author did even bother to indent the |
| other lines of the paragraph. |
| |
| Second paragraph contains several lines which are all |
| indented by two spaces. This style is much nicer than |
| the one used for the previous paragraph. |
| +-------------------------------------------------------+ |
| |
| Note that tabs are expanded with a tab width set to 8. |
| |
| * Document elements |
| ~~~~~~~~~~~~~~~~~~~ |
| |
| ** Block level elements |
| ~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| *** Title |
| ~~~~~~~~~~ |
| |
| A title is optional. If used, it must appear as the first block of the |
| document. |
| |
| +----------------------------------------------------------------------------+ |
| ------ |
| Title |
| ------ |
| Author |
| ------ |
| Date |
| +----------------------------------------------------------------------------+ |
| |
| A title block is indented (centering it is nicer). It begins with a line |
| containing at least 3 dashes (<<<--->>>). |
| |
| After the first <<<--->>> line, one or several consecutive lines of text |
| (implicit line break after each line) specify the title of the document. |
| |
| This text may immediately be followed by another <<<--->>> line and one or |
| several consecutive lines of text which specifies the author of the |
| document. |
| |
| The author sub-block may optionaly be followed by a date sub-block using the |
| same syntax. |
| |
| The following example is used for a document with an title and a date but |
| with no declared author. |
| |
| +----------------------------------------------------------------------------+ |
| ------ |
| Title |
| ------ |
| ------ |
| Date |
| ------ |
| +----------------------------------------------------------------------------+ |
| |
| The last line is ignored. It is just there to make the block nicer. |
| |
| *** Paragraph |
| ~~~~~~~~~~~~~ |
| |
| Paragraphs other than the title block may appear before the first section. |
| |
| +----------------------+ |
| Paragraph 1, line 1. |
| Paragraph 1, line 2. |
| |
| Paragraph 2, line 1. |
| Paragraph 2, line 2. |
| +----------------------+ |
| |
| Paragraphs are indented. They have already been described in the {{document |
| structure}} section. |
| |
| *** Section |
| ~~~~~~~~~~~ |
| |
| Sections are created by inserting section titles into the document. Simple |
| documents need not contain sections. |
| |
| +-----------------------------------+ |
| Section title |
| |
| * Sub-section title |
| |
| ** Sub-sub-section title |
| |
| *** Sub-sub-sub-section title |
| |
| **** Sub-sub-sub-sub-section title |
| +-----------------------------------+ |
| |
| Section titles are not indented. A sub-section title begins with one |
| asterisk (<<<*>>>), a sub-sub-section title begins with two asterisks |
| (<<<**>>>), and so forth up to four sub-section levels. |
| |
| *** List |
| ~~~~~~~~ |
| |
| +---------------------------------------+ |
| * List item 1. |
| |
| * List item 2. |
| |
| Paragraph contained in list item 2. |
| |
| * Sub-list item 1. |
| |
| * Sub-list item 2. |
| |
| * List item 3. |
| +---------------------------------------+ |
| |
| List items are indented and begin with a asterisk (<<<*>>>). |
| |
| Plain paragraphs more indented than the first list item are nested in that |
| list. Displays such as tables (not indented) are always nested in the |
| current list. |
| |
| To nest a list inside a list, indent its first item more than its parent |
| list. To end a list, add a paragraph or list item less indented than the |
| current list. |
| |
| Section titles always end a list. Displays cannot end a list but the |
| <<<[]>>> pseudo-element may be used to force the end of a list. |
| |
| +------------------------------------+ |
| * List item 3. |
| Force end of list: |
| |
| [] |
| |
| -------------------------------------------- |
| Verbatim text not contained in list item 3 |
| -------------------------------------------- |
| +------------------------------------+ |
| |
| In the previous example, without the <<<[]>>>, the verbatim text (not |
| indented as all displays) would have been contained in list item 3. |
| |
| A single <<<[]>>> may be used to end several nested lists at the same |
| time. The indentation of <<<[]>>> may be used to specify exactly which |
| lists should be ended. Example: |
| |
| +------------------------------------+ |
| * List item 1. |
| |
| * List item 2. |
| |
| * Sub-list item 1. |
| |
| * Sub-list item 2. |
| |
| [] |
| |
| ------------------------------------------------------------------- |
| Verbatim text contained in list item 2, but not in sub-list item 2 |
| ------------------------------------------------------------------- |
| +------------------------------------+ |
| |
| There are three kind of lists, the bulleted lists we have already described, |
| the numbered lists and the definition lists. |
| |
| +-----------------------------------------+ |
| [[1]] Numbered item 1. |
| |
| [[A]] Numbered item A. |
| |
| [[B]] Numbered item B. |
| |
| [[2]] Numbered item 2. |
| +-----------------------------------------+ |
| |
| A numbered list item begins with a label beetween two square brackets. The |
| label of the first item establishes the numbering scheme for the whole list: |
| |
| [<<<[[1\]\]>>>] Decimal numbering: 1, 2, 3, 4, etc. |
| |
| [<<<[[a\]\]>>>] Lower-alpha numbering: a, b, c, d, etc. |
| |
| [<<<[[A\]\]>>>] Upper-alpha numbering: A, B, C, D, etc. |
| |
| [<<<[[i\]\]>>>] Lower-roman numbering: i, ii, iii, iv, etc. |
| |
| [<<<[[I\]\]>>>] Upper-roman numbering: I, II, III, IV, etc. |
| |
| The labels of the items other than the first one are ignored. It is |
| recommended to take the time to type the correct label for each item in |
| order to keep the APT source document readable. |
| |
| +-------------------------------------------+ |
| [Defined term 1] of definition list 2. |
| |
| [Defined term 2] of definition list 2. |
| +-------------------------------------------+ |
| |
| A definition list item begins with a defined term: text between square |
| brackets. |
| |
| *** Verbatim text |
| ~~~~~~~~~~~~~~~~~ |
| |
| +----------------------------------------+ |
| ---------------------------------------- |
| Verbatim |
| text, |
| preformatted, |
| escaped. |
| ---------------------------------------- |
| +----------------------------------------+ |
| |
| A verbatim block is not indented. It begins with a non indented line |
| containing at least 3 dashes (<<<--->>>). It ends with a similar line. |
| |
| <<<+-->>> instead of <<<--->>> draws a box around verbatim text. |
| |
| Like in HTML, verbatim text is preformatted. Unlike HTML, verbatim text is |
| escaped: inside a verbatim display, markup is not interpreted by the APT |
| processor. |
| |
| *** Figure |
| ~~~~~~~~~~ |
| |
| +---------------------------+ |
| [Figure name] Figure caption |
| +---------------------------+ |
| |
| A figure block is not indented. It begins with the figure name between |
| square brackets. The figure name is optionally followed by some text: the |
| figure caption. |
| |
| The figure name is the pathname of the file containing the figure but |
| without an extension. Example: if your figure is contained in |
| <<</home/joe/docs/mylogo.jpeg>>>, the figure name is |
| <<</home/joe/docs/mylogo>>>. |
| |
| If the figure name comes from a relative pathname (recommended practice) |
| rather than from an absolute pathname, this relative pathname is taken to be |
| relative to the directory of the current APT document (a la HTML) |
| rather than relative to the current working directory. |
| |
| Why not leave the file extension in the figure name? This is better |
| explained by an example. You need to convert an APT document to PostScript |
| and your figure name is <<</home/joe/docs/mylogo>>>. A APT processor will |
| first try to load <<</home/joe/docs/mylogo.eps>>>. When the desired format |
| is not found, a APT processor tries to convert one of the existing |
| formats. In our example, the APT processor tries to convert |
| <<</home/joe/docs/mylogo.jpeg>>> to encapsulated PostScript. |
| |
| *** Table |
| ~~~~~~~~~ |
| |
| A table block is not indented. It begins with a non indented line containing |
| an asterisk and at least 2 dashes (<<<*-->>>). It ends with a |
| similar line. |
| |
| The first line is not only used to recognize a table but also to specify |
| column justification. In the following example, |
| |
| * the second asterisk (<<<*>>>) is used to specify that column 1 is |
| centered, |
| |
| * the plus sign (<<<+>>>) specifies that column 2 is left aligned, |
| |
| * the colon (<<<:>>>) specifies that column 3 is right aligned. |
| |
| [] |
| |
| +---------------------------------------------+ |
| *----------*--------------+----------------: |
| | Centered | Left-aligned | Right-aligned | |
| | cell 1,1 | cell 1,2 | cell 1,3 | |
| *----------*--------------+----------------: |
| | cell 2,1 | cell 2,2 | cell 2,3 | |
| *----------*--------------+----------------: |
| Table caption |
| +---------------------------------------------+ |
| |
| Rows are separated by a non indented line beginning with <<<*-->>>. |
| |
| An optional table caption (non indented text) may immediately follow the |
| table. |
| |
| Rows may contain single line or multiple line cells. Each line of cell text |
| is separated from the adjacent cell by the pipe character (<<<|>>>). |
| (<<<|>>> may be used in the cell text if quoted: <<<\\|>>>.) |
| |
| The last <<<|>>> is only used to make the table nicer. The first <<<|>>> is |
| not only used to make the table nicer, but also to specify that a grid is to |
| be drawn around table cells. |
| |
| The following example shows a simple table with no grid and no caption. |
| |
| +---------------+ |
| *-----*------* |
| cell | cell |
| *-----*------* |
| cell | cell |
| *-----*------* |
| +---------------+ |
| |
| *** Horizontal rule |
| ~~~~~~~~~~~~~~~~~~~ |
| |
| +---------------------+ |
| ===================== |
| +---------------------+ |
| |
| A non indented line containing at least 3 equal signs (<<<===>>>). |
| |
| *** Page break |
| ~~~~~~~~~~~~~~ |
| |
| +---+ |
| ^L |
| +---+ |
| |
| A non indented line containing a single form feed character (Control-L). |
| |
| ** Text level elements |
| ~~~~~~~~~~~~~~~~~~~~~~ |
| |
| *** Font |
| ~~~~~~~~ |
| |
| +-----------------------------------------------------+ |
| <Italic> font. <<Bold>> font. <<<Monospaced>>> font. |
| +-----------------------------------------------------+ |
| |
| Text between \< and > must be rendered in italic. Text between \<\< and >> |
| must be rendered in bold. Text between \<\<\< and >>> must be rendered using |
| a monospaced, typewriter-like font. |
| |
| Font elements may appear anywhere except inside other font elements. |
| |
| It is not recommended to use font elements inside titles, section titles, |
| links and defined terms because a APT processor automatically applies |
| appropriate font styles to these elements. |
| |
| *** Anchor and link |
| ~~~~~~~~~~~~~~~~~~~ |
| |
| +-----------------------------------------------------------------+ |
| {Anchor}. Link to {{anchor}}. Link to {{http://www.pixware.fr}}. |
| Link to {{{anchor}showing alternate text}}. |
| Link to {{{http://www.pixware.fr}Pixware home page}}. |
| +-----------------------------------------------------------------+ |
| |
| Text between curly braces (<<<\{}>>>) specifies an anchor. Text between |
| double curly braces (<<<\{\{}}>>>) specifies a link. |
| |
| It is an error to create a link element that does not refer to an anchor of |
| the same name. The name of an anchor/link is its text with all non |
| alphanumeric characters stripped. |
| |
| This rule does not apply to links to <external> anchors. Text beginning |
| with <<<http:/>>>, <<<https:/>>>, <<<ftp:/>>>, <<<file:/>>>, <<<mailto:>>>, |
| <<<../>>>, <<<./>>> (<<<..\\>>> and <<<.\\>>> on Windows) is recognized as |
| an external anchor name. |
| |
| When the construct <<\{\{\{>><name><<}>><text><<}}>> is used, the link text |
| <text> may differ from the link name <name>. |
| |
| Anchor/link elements may appear anywhere except inside other anchor/link |
| elements. |
| |
| Section titles are implicitly defined anchors. |
| |
| *** Line break |
| ~~~~~~~~~~~~~~ |
| |
| +-------------+ |
| Force line\ |
| break. |
| +-------------+ |
| |
| A backslash character (<<<\\>>>) followed by a newline character. |
| |
| Line breaks must not be used inside titles and tables (which are line |
| oriented blocks with implicit line breaks). |
| |
| *** Non breaking space |
| ~~~~~~~~~~~~~~~~~~~~~~ |
| |
| +----------------------+ |
| Non\ breaking\ space. |
| +----------------------+ |
| |
| A backslash character (<<<\\>>>) followed by a space character. |
| |
| *** Special character |
| ~~~~~~~~~~~~~~~~~~~~~ |
| |
| +---------------------------------------------------------------------------+ |
| Escaped special characters: \~, \=, \-, \+, \*, \[, \], \<, \>, \{, \}, \\. |
| +---------------------------------------------------------------------------+ |
| |
| In certain contexts, these characters have a special meaning and therefore |
| must be escaped if needed as is. They are escaped by adding a backslash in |
| front of them. The backslash may itself be escaped by adding another |
| backslash in front of it. |
| |
| Note that an asterisk, for example, needs to be escaped only if its begins a |
| paragraph. (<<<*>>> has no special meaning in the middle of a paragraph.) |
| |
| +--------------------------------------+ |
| Copyright symbol: \251, \xA9, \u00a9. |
| +--------------------------------------+ |
| |
| Latin-1 characters (whatever is the encoding of the APT document) may be |
| specified by their codes using a backslash followed by one to three octal |
| digits or by using the <<<\x>>><NN> notation, where <NN> are two hexadecimal |
| digits. |
| |
| Unicode characters may be specified by their codes using the <<<\u>>><NNNN> |
| notation, where <NNNN> are four hexadecimal digits. |
| |
| *** Comment |
| ~~~~~~~~~~~ |
| |
| +---------------+ |
| ~~Commented out. |
| +---------------+ |
| |
| Text found after two tildes (<<<\~~>>>) is ignored up to the end of line. |
| |
| A line of <<<~>>> is often used to ``underline'' section titles in order to |
| make them stand out of other paragraphs. |
| |
| |
| * The APT format at a glance |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| ------------------------------------------------------------------------------ |
| ------ |
| Title |
| ------ |
| Author |
| ------ |
| Date |
| |
| Paragraph 1, line 1. |
| Paragraph 1, line 2. |
| |
| Paragraph 2, line 1. |
| Paragraph 2, line 2. |
| |
| Section title |
| |
| * Sub-section title |
| |
| ** Sub-sub-section title |
| |
| *** Sub-sub-sub-section title |
| |
| **** Sub-sub-sub-sub-section title |
| |
| * List item 1. |
| |
| * List item 2. |
| |
| Paragraph contained in list item 2. |
| |
| * Sub-list item 1. |
| |
| * Sub-list item 2. |
| |
| * List item 3. |
| Force end of list: |
| |
| [] |
| |
| +------------------------------------------+ |
| Verbatim text not contained in list item 3 |
| +------------------------------------------+ |
| |
| [[1]] Numbered item 1. |
| |
| [[A]] Numbered item A. |
| |
| [[B]] Numbered item B. |
| |
| [[2]] Numbered item 2. |
| |
| List numbering schemes: [[1]], [[a]], [[A]], [[i]], [[I]]. |
| |
| [Defined term 1] of definition list. |
| |
| [Defined term 2] of definition list. |
| |
| +-------------------------------+ |
| Verbatim text |
| in a box |
| +-------------------------------+ |
| |
| --- instead of +-- suppresses the box around verbatim text. |
| |
| [Figure name] Figure caption |
| |
| *----------*--------------+----------------: |
| | Centered | Left-aligned | Right-aligned | |
| | cell 1,1 | cell 1,2 | cell 1,3 | |
| *----------*--------------+----------------: |
| | cell 2,1 | cell 2,2 | cell 2,3 | |
| *----------*--------------+----------------: |
| Table caption |
| |
| No grid, no caption: |
| |
| *-----*------* |
| cell | cell |
| *-----*------* |
| cell | cell |
| *-----*------* |
| |
| Horizontal line: |
| |
| ======================================================================= |
| |
| ^L |
| New page. |
| |
| <Italic> font. <<Bold>> font. <<<Monospaced>>> font. |
| |
| {Anchor}. Link to {{anchor}}. Link to {{http://www.pixware.fr}}. |
| Link to {{{anchor}showing alternate text}}. |
| Link to {{{http://www.pixware.fr}Pixware home page}}. |
| |
| Force line\ |
| break. |
| |
| Non\ breaking\ space. |
| |
| Escaped special characters: \~, \=, \-, \+, \*, \[, \], \<, \>, \{, \}, \\. |
| |
| Copyright symbol: \251, \xA9, \u00a9. |
| |
| ~~Commented out. |
| |
| ------------------------------------------------------------------------------ |
| |