Prepared initial project tree.
[staff/due1/sed-hs15-srs-purple.git] / src / site / apt / format.apt
1 -----
2 The APT format
3 -----
4 The Maven Team
5 -----
6 -----
7
8 The APT format
9 ~~~~~~~~~~~~~~
10
11 In the following section, boxes containing text in typewriter-like font are
12 examples of APT source.
13
14 * Document structure
15 ~~~~~~~~~~~~~~~~~~~~
16
17 A short APT document is contained in a single text file. A longer document
18 may be contained in a ordered list of text files. For instance, first text
19 file contains section 1, second text file contains section 2, and so on.
20
21 [Note:] Splitting the APT document in several text files on a section
22 boundary is not mandatory. The split may occur anywhere.
23 However doing so is recommended because a text file containing a
24 section is by itself a valid APT document.
25
26 A file contains a sequence of paragraphs and ``displays'' (non paragraphs
27 such as tables) separated by open lines.
28
29 A paragraph is simply a sequence of consecutive text lines.
30
31 +------------------------------------------------------------------------+
32 First line of first paragraph.
33 Second line of first paragraph.
34 Third line of first paragraph.
35
36 Line 1 of paragraph 2 (separated from first paragraph by an open line).
37 Line 2 of paragraph 2.
38 +------------------------------------------------------------------------+
39
40 The indentation of the first line of a paragraph is the main method used by
41 an APT processor to recognize the type of the paragraph. For example, a
42 section title must not be indented at all.
43
44 A ``plain'' paragraph must be indented by a certain amount of space. For
45 example, a plain paragraph which is not contained in a list may be indented
46 by two spaces.
47
48 +-------------------------------------------------+
49 My section title (not indented).
50
51 My paragraph first line (indented by 2 spaces).
52 +-------------------------------------------------+
53
54 Indentation is not rigid. Any amount of space will do. You don't even need
55 to use a consistent indentation all over your document. What really matters
56 for an APT processor is whether the paragraph is not indented at all or,
57 when inside a list, whether a paragraph is more or less indented than the
58 first item of the list (more about this later).
59
60 +-------------------------------------------------------+
61 First paragraph has its first line indented by four
62 spaces. Then the author did even bother to indent the
63 other lines of the paragraph.
64
65 Second paragraph contains several lines which are all
66 indented by two spaces. This style is much nicer than
67 the one used for the previous paragraph.
68 +-------------------------------------------------------+
69
70 Note that tabs are expanded with a tab width set to 8.
71
72 * Document elements
73 ~~~~~~~~~~~~~~~~~~~
74
75 ** Block level elements
76 ~~~~~~~~~~~~~~~~~~~~~~~
77
78 *** Title
79 ~~~~~~~~~~
80
81 A title is optional. If used, it must appear as the first block of the
82 document.
83
84 +----------------------------------------------------------------------------+
85 ------
86 Title
87 ------
88 Author
89 ------
90 Date
91 +----------------------------------------------------------------------------+
92
93 A title block is indented (centering it is nicer). It begins with a line
94 containing at least 3 dashes (<<<--->>>).
95
96 After the first <<<--->>> line, one or several consecutive lines of text
97 (implicit line break after each line) specify the title of the document.
98
99 This text may immediately be followed by another <<<--->>> line and one or
100 several consecutive lines of text which specifies the author of the
101 document.
102
103 The author sub-block may optionally be followed by a date sub-block using the
104 same syntax.
105
106 The following example is used for a document with an title and a date but
107 with no declared author.
108
109 +----------------------------------------------------------------------------+
110 ------
111 Title
112 ------
113 ------
114 Date
115 ------
116 +----------------------------------------------------------------------------+
117
118 The last line is ignored. It is just there to make the block nicer.
119
120 *** Paragraph
121 ~~~~~~~~~~~~~
122
123 Paragraphs other than the title block may appear before the first section.
124
125 +----------------------+
126 Paragraph 1, line 1.
127 Paragraph 1, line 2.
128
129 Paragraph 2, line 1.
130 Paragraph 2, line 2.
131 +----------------------+
132
133 Paragraphs are indented. They have already been described in the
134 {{{#Document_structure}Document structure}} section.
135
136 *** Section
137 ~~~~~~~~~~~
138
139 Sections are created by inserting section titles into the document. Simple
140 documents need not contain sections.
141
142 +-----------------------------------+
143 Section title
144
145 * Sub-section title
146
147 ** Sub-sub-section title
148
149 *** Sub-sub-sub-section title
150
151 **** Sub-sub-sub-sub-section title
152 +-----------------------------------+
153
154 Section titles are not indented. A sub-section title begins with one
155 asterisk (<<<*>>>), a sub-sub-section title begins with two asterisks
156 (<<<**>>>), and so forth up to four sub-section levels.
157
158 *** List
159 ~~~~~~~~
160
161 +---------------------------------------+
162 * List item 1.
163
164 * List item 2.
165
166 Paragraph contained in list item 2.
167
168 * Sub-list item 1.
169
170 * Sub-list item 2.
171
172 * List item 3.
173 +---------------------------------------+
174
175 List items are indented and begin with a asterisk (<<<*>>>).
176
177 Plain paragraphs more indented than the first list item are nested in that
178 list. Displays such as tables (not indented) are always nested in the
179 current list.
180
181 To nest a list inside a list, indent its first item more than its parent
182 list. To end a list, add a paragraph or list item less indented than the
183 current list.
184
185 Section titles always end a list. Displays cannot end a list but the
186 <<<[]>>> pseudo-element may be used to force the end of a list.
187
188 +------------------------------------+
189 * List item 3.
190 Force end of list:
191
192 []
193
194 --------------------------------------------
195 Verbatim text not contained in list item 3
196 --------------------------------------------
197 +------------------------------------+
198
199 In the previous example, without the <<<[]>>>, the verbatim text (not
200 indented as all displays) would have been contained in list item 3.
201
202 A single <<<[]>>> may be used to end several nested lists at the same
203 time. The indentation of <<<[]>>> may be used to specify exactly which
204 lists should be ended. Example:
205
206 +------------------------------------+
207 * List item 1.
208
209 * List item 2.
210
211 * Sub-list item 1.
212
213 * Sub-list item 2.
214
215 []
216
217 -------------------------------------------------------------------
218 Verbatim text contained in list item 2, but not in sub-list item 2
219 -------------------------------------------------------------------
220 +------------------------------------+
221
222 There are three kind of lists, the bullet lists we have already described,
223 the numbered lists and the definition lists.
224
225 +-----------------------------------------+
226 [[1]] Numbered item 1.
227
228 [[A]] Numbered item A.
229
230 [[B]] Numbered item B.
231
232 [[2]] Numbered item 2.
233 +-----------------------------------------+
234
235 A numbered list item begins with a label beetween two square brackets. The
236 label of the first item establishes the numbering scheme for the whole list:
237
238 [<<<[[1\]\]>>>] Decimal numbering: 1, 2, 3, 4, etc.
239
240 [<<<[[a\]\]>>>] Lower-alpha numbering: a, b, c, d, etc.
241
242 [<<<[[A\]\]>>>] Upper-alpha numbering: A, B, C, D, etc.
243
244 [<<<[[i\]\]>>>] Lower-roman numbering: i, ii, iii, iv, etc.
245
246 [<<<[[I\]\]>>>] Upper-roman numbering: I, II, III, IV, etc.
247
248 The labels of the items other than the first one are ignored. It is
249 recommended to take the time to type the correct label for each item in
250 order to keep the APT source document readable.
251
252 +-------------------------------------------+
253 [Defined term 1] of definition list 2.
254
255 [Defined term 2] of definition list 2.
256 +-------------------------------------------+
257
258 A definition list item begins with a defined term: text between square
259 brackets.
260
261 *** Verbatim text
262 ~~~~~~~~~~~~~~~~~
263
264 +----------------------------------------+
265 ----------------------------------------
266 Verbatim
267 text,
268 preformatted,
269 escaped.
270 ----------------------------------------
271 +----------------------------------------+
272
273 A verbatim block is not indented. It begins with a non indented line
274 containing at least 3 dashes (<<<--->>>). It ends with a similar line.
275
276 <<<+-->>> instead of <<<--->>> draws a box around verbatim text.
277
278 Like in HTML, verbatim text is preformatted. Unlike HTML, verbatim text is
279 escaped: inside a verbatim display, markup is not interpreted by the APT
280 processor.
281
282 *** Figure
283 ~~~~~~~~~~
284
285 +---------------------------+
286 [Figure name] Figure caption
287 +---------------------------+
288
289 A figure block is not indented. It begins with the figure name between
290 square brackets. The figure name is optionally followed by some text: the
291 figure caption.
292
293 The figure name is the pathname of the file containing the figure but
294 without an extension. Example: if your figure is contained in
295 <<</home/joe/docs/mylogo.jpeg>>>, the figure name is
296 <<</home/joe/docs/mylogo>>>.
297
298 If the figure name comes from a relative pathname (recommended practice)
299 rather than from an absolute pathname, this relative pathname is taken to be
300 relative to the directory of the current APT document (a la HTML)
301 rather than relative to the current working directory.
302
303 Why not leave the file extension in the figure name? This is better
304 explained by an example. You need to convert an APT document to PostScript
305 and your figure name is <<</home/joe/docs/mylogo>>>. A APT processor will
306 first try to load <<</home/joe/docs/mylogo.eps>>>. When the desired format
307 is not found, a APT processor tries to convert one of the existing
308 formats. In our example, the APT processor tries to convert
309 <<</home/joe/docs/mylogo.jpeg>>> to encapsulated PostScript.
310
311 *** Table
312 ~~~~~~~~~
313
314 A table block is not indented. It begins with a non indented line containing
315 an asterisk and at least 2 dashes (<<<*-->>>). It ends with a
316 similar line.
317
318 The first line is not only used to recognize a table but also to specify
319 column justification. In the following example,
320
321 * the second asterisk (<<<*>>>) is used to specify that column 1 is
322 centered,
323
324 * the plus sign (<<<+>>>) specifies that column 2 is left aligned,
325
326 * the colon (<<<:>>>) specifies that column 3 is right aligned.
327
328 []
329
330 +---------------------------------------------+
331 *----------*--------------+----------------:
332 | Centered | Left-aligned | Right-aligned |
333 | cell 1,1 | cell 1,2 | cell 1,3 |
334 *----------*--------------+----------------:
335 | cell 2,1 | cell 2,2 | cell 2,3 |
336 *----------*--------------+----------------:
337 Table caption
338 +---------------------------------------------+
339
340 Rows are separated by a non indented line beginning with <<<*-->>>.
341
342 An optional table caption (non indented text) may immediately follow the
343 table.
344
345 Rows may contain single line or multiple line cells. Each line of cell text
346 is separated from the adjacent cell by the pipe character (<<<|>>>).
347 (<<<|>>> may be used in the cell text if quoted: <<<\\|>>>.)
348
349 The last <<<|>>> is only used to make the table nicer. The first <<<|>>> is
350 not only used to make the table nicer, but also to specify that a grid is to
351 be drawn around table cells.
352
353 The following example shows a simple table with no grid and no caption.
354
355 +---------------+
356 *-----*------*
357 cell | cell
358 *-----*------*
359 cell | cell
360 *-----*------*
361 +---------------+
362
363 *** Horizontal rule
364 ~~~~~~~~~~~~~~~~~~~
365
366 +---------------------+
367 =====================
368 +---------------------+
369
370 A non indented line containing at least 3 equal signs (<<<===>>>).
371
372 *** Page break
373 ~~~~~~~~~~~~~~
374
375 +---+
376 ^L
377 +---+
378
379 A non indented line containing a single form feed character (Control-L).
380
381 ** Text level elements
382 ~~~~~~~~~~~~~~~~~~~~~~
383
384 *** Font
385 ~~~~~~~~
386
387 +-----------------------------------------------------+
388 <Italic> font. <<Bold>> font. <<<Monospaced>>> font.
389 +-----------------------------------------------------+
390
391 Text between \< and > must be rendered in italic. Text between \<\< and >>
392 must be rendered in bold. Text between \<\<\< and >>> must be rendered using
393 a mono-spaced, typewriter-like font.
394
395 Font elements may appear anywhere except inside other font elements.
396
397 It is not recommended to use font elements inside titles, section titles,
398 links and defined terms because a APT processor automatically applies
399 appropriate font styles to these elements.
400
401 *** Anchor and link
402 ~~~~~~~~~~~~~~~~~~~
403
404 +-----------------------------------------------------------------+
405 {Anchor}. Link to {{anchor}}. Link to {{http://www.pixware.fr}}.
406 Link to {{{anchor}showing alternate text}}.
407 Link to {{{http://www.pixware.fr}Pixware home page}}.
408 +-----------------------------------------------------------------+
409
410 Text between curly braces (<<<\{}>>>) specifies an anchor. Text between
411 double curly braces (<<<\{\{}}>>>) specifies a link.
412
413 It is an error to create a link element that does not refer to an anchor of
414 the same name. The name of an anchor/link is its text with all non
415 alphanumeric characters stripped.
416
417 This rule does not apply to links to <external> anchors. Text beginning
418 with <<<http:/>>>, <<<https:/>>>, <<<ftp:/>>>, <<<file:/>>>, <<<mailto:>>>,
419 <<<../>>>, <<<./>>> (<<<..\\>>> and <<<.\\>>> on Windows) is recognized as
420 an external anchor name.
421
422 When the construct <<\{\{\{>><name><<}>><text><<}}>> is used, the link text
423 <text> may differ from the link name <name>.
424
425 Anchor/link elements may appear anywhere except inside other anchor/link
426 elements.
427
428 Section titles are implicitly defined anchors.
429
430 *** Line break
431 ~~~~~~~~~~~~~~
432
433 +-------------+
434 Force line\
435 break.
436 +-------------+
437
438 A backslash character (<<<\\>>>) followed by a newline character.
439
440 Line breaks must not be used inside titles and tables (which are line
441 oriented blocks with implicit line breaks).
442
443 *** Non breaking space
444 ~~~~~~~~~~~~~~~~~~~~~~
445
446 +----------------------+
447 Non\ breaking\ space.
448 +----------------------+
449
450 A backslash character (<<<\\>>>) followed by a space character.
451
452 *** Special character
453 ~~~~~~~~~~~~~~~~~~~~~
454
455 +---------------------------------------------------------------------------+
456 Escaped special characters: \~, \=, \-, \+, \*, \[, \], \<, \>, \{, \}, \\.
457 +---------------------------------------------------------------------------+
458
459 In certain contexts, these characters have a special meaning and therefore
460 must be escaped if needed as is. They are escaped by adding a backslash in
461 front of them. The backslash may itself be escaped by adding another
462 backslash in front of it.
463
464 Note that an asterisk, for example, needs to be escaped only if its begins a
465 paragraph. (<<<*>>> has no special meaning in the middle of a paragraph.)
466
467 +--------------------------------------+
468 Copyright symbol: \251, \xA9, \u00a9.
469 +--------------------------------------+
470
471 Latin-1 characters (whatever is the encoding of the APT document) may be
472 specified by their codes using a backslash followed by one to three octal
473 digits or by using the <<<\x>>><NN> notation, where <NN> are two hexadecimal
474 digits.
475
476 Unicode characters may be specified by their codes using the <<<\u>>><NNNN>
477 notation, where <NNNN> are four hexadecimal digits.
478
479 *** Comment
480 ~~~~~~~~~~~
481
482 +---------------+
483 ~~Commented out.
484 +---------------+
485
486 Text found after two tildes (<<<\~~>>>) is ignored up to the end of line.
487
488 A line of <<<~>>> is often used to ``underline'' section titles in order to
489 make them stand out of other paragraphs.
490
491 \f
492 * The APT format at a glance
493 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
494
495 ------------------------------------------------------------------------------
496 ------
497 Title
498 ------
499 Author
500 ------
501 Date
502
503 Paragraph 1, line 1.
504 Paragraph 1, line 2.
505
506 Paragraph 2, line 1.
507 Paragraph 2, line 2.
508
509 Section title
510
511 * Sub-section title
512
513 ** Sub-sub-section title
514
515 *** Sub-sub-sub-section title
516
517 **** Sub-sub-sub-sub-section title
518
519 * List item 1.
520
521 * List item 2.
522
523 Paragraph contained in list item 2.
524
525 * Sub-list item 1.
526
527 * Sub-list item 2.
528
529 * List item 3.
530 Force end of list:
531
532 []
533
534 +------------------------------------------+
535 Verbatim text not contained in list item 3
536 +------------------------------------------+
537
538 [[1]] Numbered item 1.
539
540 [[A]] Numbered item A.
541
542 [[B]] Numbered item B.
543
544 [[2]] Numbered item 2.
545
546 List numbering schemes: [[1]], [[a]], [[A]], [[i]], [[I]].
547
548 [Defined term 1] of definition list.
549
550 [Defined term 2] of definition list.
551
552 +-------------------------------+
553 Verbatim text
554 in a box
555 +-------------------------------+
556
557 --- instead of +-- suppresses the box around verbatim text.
558
559 [Figure name] Figure caption
560
561 *----------*--------------+----------------:
562 | Centered | Left-aligned | Right-aligned |
563 | cell 1,1 | cell 1,2 | cell 1,3 |
564 *----------*--------------+----------------:
565 | cell 2,1 | cell 2,2 | cell 2,3 |
566 *----------*--------------+----------------:
567 Table caption
568
569 No grid, no caption:
570
571 *-----*------*
572 cell | cell
573 *-----*------*
574 cell | cell
575 *-----*------*
576
577 Horizontal line:
578
579 =======================================================================
580
581 ^L
582 New page.
583
584 <Italic> font. <<Bold>> font. <<<Monospaced>>> font.
585
586 {Anchor}. Link to {{anchor}}. Link to {{http://www.pixware.fr}}.
587 Link to {{{anchor}showing alternate text}}.
588 Link to {{{http://www.pixware.fr}Pixware home page}}.
589
590 Force line\
591 break.
592
593 Non\ breaking\ space.
594
595 Escaped special characters: \~, \=, \-, \+, \*, \[, \], \<, \>, \{, \}, \\.
596
597 Copyright symbol: \251, \xA9, \u00a9.
598
599 ~~Commented out.
600
601 ------------------------------------------------------------------------------
602