« back to all changes in this revision
Viewing changes to src/site/apt/format.apt
- browse files at revision 2
- compare with another revision
- download diff
- download tarball
- view history from revision 2
- Committer: wattazoum
- Date: 2009-10-30 06:56:46 UTC
- Revision ID: wattazoum-20091030065646-l6mypab1wnk9onmi
Succeeded uploading to the FTP site.
- files removed:
- src/site/apt/format.apt
- files modified:
- pom.xml
added
removed
src/site/apt/format.apt
1
2
The APT format
3
~~~~~~~~~~~~~~
4
5
In the following section, boxes containing text in typewriter-like font are
6
examples of APT source.
7
8
* Document structure
9
~~~~~~~~~~~~~~~~~~~~
10
11
A short APT document is contained in a single text file. A longer document
12
may be contained in a ordered list of text files. For instance, first text
13
file contains section 1, second text file contains section 2, and so on.
14
15
[Note:] Splitting the APT document in several text files on a section
16
boundary is not mandatory. The split may occur anywhere.
17
However doing so is recommended because a text file containing a
18
section is by itself a valid APT document.
19
20
A file contains a sequence of paragraphs and ``displays'' (non paragraphs
21
such as tables) separated by open lines.
22
23
A paragraph is simply a sequence of consecutive text lines.
24
25
+------------------------------------------------------------------------+
26
First line of first paragraph.
27
Second line of first paragraph.
28
Third line of first paragraph.
29
30
Line 1 of paragraph 2 (separated from first paragraph by an open line).
31
Line 2 of paragraph 2.
32
+------------------------------------------------------------------------+
33
34
The indentation of the first line of a paragraph is the main method used by
35
an APT processor to recognize the type of the paragraph. For example, a
36
section title must not be indented at all.
37
38
A ``plain'' paragraph must be indented by a certain amount of space. For
39
example, a plain paragraph which is not contained in a list may be indented
40
by two spaces.
41
42
+-------------------------------------------------+
43
My section title (not indented).
44
45
My paragraph first line (indented by 2 spaces).
46
+-------------------------------------------------+
47
48
Indentation is not rigid. Any amount of space will do. You don't even need
49
to use a consistent indentation all over your document. What really matters
50
for an APT processor is whether the paragraph is not indented at all or,
51
when inside a list, whether a paragraph is more or less indented than the
52
first item of the list (more about this later).
53
54
+-------------------------------------------------------+
55
First paragraph has its first line indented by four
56
spaces. Then the author did even bother to indent the
57
other lines of the paragraph.
58
59
Second paragraph contains several lines which are all
60
indented by two spaces. This style is much nicer than
61
the one used for the previous paragraph.
62
+-------------------------------------------------------+
63
64
Note that tabs are expanded with a tab width set to 8.
65
66
* Document elements
67
~~~~~~~~~~~~~~~~~~~
68
69
** Block level elements
70
~~~~~~~~~~~~~~~~~~~~~~~
71
72
*** Title
73
~~~~~~~~~~
74
75
A title is optional. If used, it must appear as the first block of the
76
document.
77
78
+----------------------------------------------------------------------------+
79
------
80
Title
81
------
82
Author
83
------
84
Date
85
+----------------------------------------------------------------------------+
86
87
A title block is indented (centering it is nicer). It begins with a line
88
containing at least 3 dashes (<<<--->>>).
89
90
After the first <<<--->>> line, one or several consecutive lines of text
91
(implicit line break after each line) specify the title of the document.
92
93
This text may immediately be followed by another <<<--->>> line and one or
94
several consecutive lines of text which specifies the author of the
95
document.
96
97
The author sub-block may optionaly be followed by a date sub-block using the
98
same syntax.
99
100
The following example is used for a document with an title and a date but
101
with no declared author.
102
103
+----------------------------------------------------------------------------+
104
------
105
Title
106
------
107
------
108
Date
109
------
110
+----------------------------------------------------------------------------+
111
112
The last line is ignored. It is just there to make the block nicer.
113
114
*** Paragraph
115
~~~~~~~~~~~~~
116
117
Paragraphs other than the title block may appear before the first section.
118
119
+----------------------+
120
Paragraph 1, line 1.
121
Paragraph 1, line 2.
122
123
Paragraph 2, line 1.
124
Paragraph 2, line 2.
125
+----------------------+
126
127
Paragraphs are indented. They have already been described in the {{document
128
structure}} section.
129
130
*** Section
131
~~~~~~~~~~~
132
133
Sections are created by inserting section titles into the document. Simple
134
documents need not contain sections.
135
136
+-----------------------------------+
137
Section title
138
139
* Sub-section title
140
141
** Sub-sub-section title
142
143
*** Sub-sub-sub-section title
144
145
**** Sub-sub-sub-sub-section title
146
+-----------------------------------+
147
148
Section titles are not indented. A sub-section title begins with one
149
asterisk (<<<*>>>), a sub-sub-section title begins with two asterisks
150
(<<<**>>>), and so forth up to four sub-section levels.
151
152
*** List
153
~~~~~~~~
154
155
+---------------------------------------+
156
* List item 1.
157
158
* List item 2.
159
160
Paragraph contained in list item 2.
161
162
* Sub-list item 1.
163
164
* Sub-list item 2.
165
166
* List item 3.
167
+---------------------------------------+
168
169
List items are indented and begin with a asterisk (<<<*>>>).
170
171
Plain paragraphs more indented than the first list item are nested in that
172
list. Displays such as tables (not indented) are always nested in the
173
current list.
174
175
To nest a list inside a list, indent its first item more than its parent
176
list. To end a list, add a paragraph or list item less indented than the
177
current list.
178
179
Section titles always end a list. Displays cannot end a list but the
180
<<<[]>>> pseudo-element may be used to force the end of a list.
181
182
+------------------------------------+
183
* List item 3.
184
Force end of list:
185
186
[]
187
188
--------------------------------------------
189
Verbatim text not contained in list item 3
190
--------------------------------------------
191
+------------------------------------+
192
193
In the previous example, without the <<<[]>>>, the verbatim text (not
194
indented as all displays) would have been contained in list item 3.
195
196
A single <<<[]>>> may be used to end several nested lists at the same
197
time. The indentation of <<<[]>>> may be used to specify exactly which
198
lists should be ended. Example:
199
200
+------------------------------------+
201
* List item 1.
202
203
* List item 2.
204
205
* Sub-list item 1.
206
207
* Sub-list item 2.
208
209
[]
210
211
-------------------------------------------------------------------
212
Verbatim text contained in list item 2, but not in sub-list item 2
213
-------------------------------------------------------------------
214
+------------------------------------+
215
216
There are three kind of lists, the bulleted lists we have already described,
217
the numbered lists and the definition lists.
218
219
+-----------------------------------------+
220
[[1]] Numbered item 1.
221
222
[[A]] Numbered item A.
223
224
[[B]] Numbered item B.
225
226
[[2]] Numbered item 2.
227
+-----------------------------------------+
228
229
A numbered list item begins with a label beetween two square brackets. The
230
label of the first item establishes the numbering scheme for the whole list:
231
232
[<<<[[1\]\]>>>] Decimal numbering: 1, 2, 3, 4, etc.
233
234
[<<<[[a\]\]>>>] Lower-alpha numbering: a, b, c, d, etc.
235
236
[<<<[[A\]\]>>>] Upper-alpha numbering: A, B, C, D, etc.
237
238
[<<<[[i\]\]>>>] Lower-roman numbering: i, ii, iii, iv, etc.
239
240
[<<<[[I\]\]>>>] Upper-roman numbering: I, II, III, IV, etc.
241
242
The labels of the items other than the first one are ignored. It is
243
recommended to take the time to type the correct label for each item in
244
order to keep the APT source document readable.
245
246
+-------------------------------------------+
247
[Defined term 1] of definition list 2.
248
249
[Defined term 2] of definition list 2.
250
+-------------------------------------------+
251
252
A definition list item begins with a defined term: text between square
253
brackets.
254
255
*** Verbatim text
256
~~~~~~~~~~~~~~~~~
257
258
+----------------------------------------+
259
----------------------------------------
260
Verbatim
261
text,
262
preformatted,
263
escaped.
264
----------------------------------------
265
+----------------------------------------+
266
267
A verbatim block is not indented. It begins with a non indented line
268
containing at least 3 dashes (<<<--->>>). It ends with a similar line.
269
270
<<<+-->>> instead of <<<--->>> draws a box around verbatim text.
271
272
Like in HTML, verbatim text is preformatted. Unlike HTML, verbatim text is
273
escaped: inside a verbatim display, markup is not interpreted by the APT
274
processor.
275
276
*** Figure
277
~~~~~~~~~~
278
279
+---------------------------+
280
[Figure name] Figure caption
281
+---------------------------+
282
283
A figure block is not indented. It begins with the figure name between
284
square brackets. The figure name is optionally followed by some text: the
285
figure caption.
286
287
The figure name is the pathname of the file containing the figure but
288
without an extension. Example: if your figure is contained in
289
<<</home/joe/docs/mylogo.jpeg>>>, the figure name is
290
<<</home/joe/docs/mylogo>>>.
291
292
If the figure name comes from a relative pathname (recommended practice)
293
rather than from an absolute pathname, this relative pathname is taken to be
294
relative to the directory of the current APT document (a la HTML)
295
rather than relative to the current working directory.
296
297
Why not leave the file extension in the figure name? This is better
298
explained by an example. You need to convert an APT document to PostScript
299
and your figure name is <<</home/joe/docs/mylogo>>>. A APT processor will
300
first try to load <<</home/joe/docs/mylogo.eps>>>. When the desired format
301
is not found, a APT processor tries to convert one of the existing
302
formats. In our example, the APT processor tries to convert
303
<<</home/joe/docs/mylogo.jpeg>>> to encapsulated PostScript.
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 monospaced, 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
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
Loggerhead is a web-based interface for Breezy
Version: 2.0.1