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