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