/
guide.ame
458 lines (334 loc) · 15.4 KB
/
guide.ame
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
$ License: http://www.gnu.org/licenses/fdl-1.3.txt
$ Copyright (c) 2011 Jaakko Keränen <jaakko.keranen@iki.fi>
@macro{TITLE}{Quick Guide to Amethyst}
@macro{AUTHOR}{Jaakko Keränen}
@macro{EMAIL}{jaakko.keranen@@iki.fi}
@require{amestd}
@begin
@macro{stdlib}{@em{amestd}}
@macro{ameword}{@cmd{@@}@glue{@cmd{@arg}}}
@macro{amearg}{@glue{@{}@glue{@arg}@glue{@}}}
@toc
@chapter{Introduction}
@def{Amethyst} is a macro-based text document processor that allows you to
write documents using a simple, generic syntax and convert them to plain text,
HTML, rich text, Unix manual page, or Mediawiki source format. It has been
implemented as a Unix-style command line tool.
This short guide describes the use of Amethyst and the Amethyst Standard
Library (@stdlib{}). It is for people who wish to write documentation but are
not interested in the internal workings of the text processor.
@notice{Amethyst is actually a macro-based text filter language and as such
its behavior can be extended or modified extensively. The output formats
defined in @stdlib contain no hard-coded functionality: everything has been
defined using @file{.ame} macros.}
@chapter{Getting started}
@section{Acquiring Amethyst}
Before you grab a copy of the sources you should make sure you have the
following software installed on your system:
@list/thin{
@item Git.
@item Qt libraries.
@item CMake.
}
The Amethyst source code is included in the Doomsday Engine Git repository:
@ind{@url{http://github.com/skyjake/Doomsday-Engine/tree/master/doomsday/tools/amethyst}}
@section{Installation}
Even though Amethyst is part of the Doomsday @file{tools} subdirectory, it can
be built independently from the rest of the CMake projects.
@list/enum{
@item Create a build directory. This should be outside the Doomsday source
tree.
@item Run CMake to configure the build. For example:
@samp{@pre{# cmake ../doomsday/tools/amethyst}}
@item Compile.
@item Run the @dquote{install} rule defined in the project file. On a Unix
this will install @file{amethyst} and @stdlib into the appropriate directories.
On Windows the installation is done to a subdirectory called @file{inst}
under the Amethyst source directory.
}
@section{Generating documents}
To generate an HTML version of this guide on Unix, run this command in the
Amethyst @file{doc} directory:
@samp{@pre{# amethyst -dHTML guide.ame > guide.html}}
To generate a plain text version of this guide on Windows, run this command in
the @file{inst} directory:
@samp{@pre{# amethyst -dTXT -i../lib -oguide.txt ../doc/guide.ame}}
To view a list of the available command line options:
@samp{@pre{# amethyst --help}}
@stdlib defines the following output filters, chosen with a command line
option.
@table{50 50}{
@header{Output filter} @tab @header{Option} @row{single}
Plain text @tab @opt{-dTXT} @row
HTML @tab @opt{-dHTML} @row
Rich text @tab @opt{-dRTF} @row
Unix manual page @tab @opt{-dMAN} @row
Mediawiki source @tab @opt{-dWIKI}
}
@chapter{Writing a document}
@section{Basic syntax}
When you write a document with Amethyst, you are giving the text processor two
types of information: document content and processing instructions. Document
content is most often written as plain text. The processing instructions are
defined using Amethyst keywords (e.g., @ameword{section}) and @stdlib macros.
The characters @@, @{ and @} have a special meaning in Amethyst. Every word
that begins with @@ is treated as an Amethyst keyword or macro call.
Parameters for keywords and macros are specified in one or more blocks of @{
@} delimited content. For instance, a document might begin with an
introduction:
@samp{@pre{@@chapter@{Introduction@}}}
In this case, @dquote{Introduction} is the parameter given to the
@ameword{chapter} keyword.
If you wish to use the characters @@, @{ or @} for normal document content,
they need to be escaped by putting another @@ in front.
@samp{@pre{Escaping the @@@@ character.}}
Lines that begin with @cmd{@$} are comments. To begin a longer commented
section, use @cmd{@$}@glue{@cmd{*}}. The comment section ends at
@cmd{*}@glue{@cmd{@$}}.
@samp{@pre{$ This is a line of comment.
$* Begin a longer comment...
...inside the comment...
and end here. *$}}
@section{Preamble}
When using @stdlib{} the document needs to have the following preamble:
@list/enum/thin{
@item Set the title of the document by defining a macro called
@dquote{TITLE}.
@item Include the @stdlib @file{.ame} definitions.
@item Place @ameword{begin} before the document content.
}
For instance, the source of this document could begin like this:
@samp{@pre{@@macro@{TITLE@}@{Quick Guide to Amethyst@}
@@require@{amestd@}
@@begin}}
See the @ref{std_begin}{begin macro} for more information about what
information is added to the beginning of the document.
@section{Styles}
When writing a document with Amethyst, you should not concern yourself with
the visual appearance of the final output. Instead, you should focus on the
structure of the text. While there is a number of text styles defined in
Amethyst, you should only use them for marking the meaning of selected words
and sections. For instance, you might @em{emphasize} a word with @ameword{em}
but you cannot rely on it always appearing as, e.g., an italic typeface in the
final output.
The following table lists all the available styles.
@table{25 75}{
@header{Style} @tab @header{Meaning} @row{single}
@ameword{acro} @tab Acronym @row
@ameword{caption} @tab Table caption @row
@ameword{cmd} @tab Command @row
@ameword{def} @tab Definition; first use of a term @row
@ameword{email} @tab Email address @row
@ameword{em} @tab Emphasized text @row
@ameword{file} @tab File name or path @row
@ameword{header} @tab Table header @row
@ameword{kbd} @tab Keyboard; @kbd{Ctrl-A} @row
@ameword{opt} @tab Command line option @row
@ameword{strong} @tab Strong typeface @row
@ameword{tag} @tab Verbatim HTML tag; @tag{<i>}italic@tag{</i>} @row
@ameword{url} @tab URL or web link @row
@ameword{var} @tab Variable or identifier
}
If you would like to mark certain words with a meaning not included in the
predefined styles, you should define your own macro for it. For instance, in
this document the @ameword{ameword} macro is used for all keywords and macro
names. See @ref{writing_macros}{Writing macros} for more information.
@section{Paragraphs}
Whitespace is mostly ignored in Amethyst source files. The exception is that
one or more empty lines separate paragraphs.
@samp{@pre{First paragraph.
Still part of the first paragraph.
Second paragraph.}}
You can use the @ameword{br} keyword to force a line break and @ameword{break}
to force a paragraph break.
@subsec{Alignment}
By default, text is left-aligned inside a paragraph. You may also use right
alignment or centered text.
@samp{@pre{@@right@{This paragraph is aligned to the right.@}
@@center@{This paragraph is centered.@}}}
@subsec{Styles}
The @ameword{ind} keyword is used to indent a paragraph:
@samp{@pre{@@ind@{Indented.@}}}
There are three other indented paragraph styles, useful for different kinds of
content:
@table{25 75}{
@header{Style} @tab @header{Meaning} @row{single}
@ameword{cite} @tab Citation or quote @row
@ameword{code} @tab Block of source code (see @ameword{pre}) @row
@ameword{samp} @tab Example of something
}
@subsec{Preformatted text}
The @ameword{pre} keyword is used for preformatted text. The special
characters @@, @{ and @} still need to be escaped inside @ameword{pre}, but
any whitespace is used verbatim in the output document and no macro expansion
occurs. A line break is automatically added before and after the preformatted
paragraph.
@samp{@pre{@@pre@{This is an
example of
preformatted
text.@}}}
The above would produce:
@samp{@pre{This is an
example of
preformatted
text.}}
@section{Chapters and sections}
The structure of the document is marked with the following keywords.
@table{20 80}{
@header{Keyword} @tab @header{Meaning} @row{single}
@ameword{part} @tab Highest-level division: chapters are divided into parts @row
@ameword{chapter} @tab Chapter; e.g., @dquote{Introduction} in this document @row
@ameword{section} @tab Section @row
@ameword{subsec} @tab Subsection @row
@ameword{sub2sec} @tab 2nd-level subsection @row
@ameword{sub3sec} @tab 3rd-level subsection @row
@ameword{sub4sec} @tab 4th-level subsection
}
A table of contents is generated by @ameword{toc} based on the titles defined
with the keywords above. @ameword{toc} is defined in @stdlib and its output
varies depending on the chosen filter.
@section{Lists}
A bulleted list can be created as follows:
@samp{@pre{@@list@{
@@item First item.
@@item Second item.
@}}}
To create an enumerated list, apply a @def{style modifier}.
@samp{@pre{@@list/enum@{
@@item First enumerated item.
@@item Second enumerated item.
@}}}
Some output filters support using a @cmd{thin} modifier to remove whitespace
between items. This is useful for a list of short items.
@samp{@pre{@@list/enum/thin@{
@@item First enumerated item, tightly packed.
@@item Second enumerated item, tightly packed.
@}}}
A definition list is useful when you have a set of terms that need to be
explained. It can be created as follows:
@samp{@pre{@@deflist@{
@@item@{Term one@} Description of the first term.
@@item@{Another term@} Explanation of the second one.
@}}}
That would produce the following:
@samp{@deflist{
@item{Term one} Description of the first term.
@item{Another term} Explanation of the second one.
}}
@section{Tables}
A table can be created with the @ameword{table} keyword. It takes two arguments.
@list/thin{
@item Widths of the table columns as percentages.
@item Table content, with columns separated by @ameword{tab} and rows separated by @ameword{row}.
}
For instance, to create a table with three columns:
@samp{@pre{@@table@{30 40 30@}@{
@@header@{A@} @@tab @@header@{B@} @@tab @@header@{C@} @@row
Cell 1 @@tab Cell 2 @@tab Cell 3 @@row
Cell 4 @@tab Cell 5 @@tab Cell 6
@}}}
The output of this looks like:
@table{30 40 30}{
@header{A} @tab @header{B} @tab @header{C} @row
Cell 1 @tab Cell 2 @tab Cell 3 @row
Cell 4 @tab Cell 5 @tab Cell 6
}
@notice{Some output filters have restrictions on what the table looks like and
what content can be placed in table cells. For instance, Unix manual pages
have no support for line wrapping for text in cells.}
@section{Images}
Because Amethyst supports text document formats including plain text, it does
not support images at the moment. However, you may define filter-specific
content that generates the necessary output for a particular filter (e.g.,
HTML).
@section{Multiple source files}
It may be a good idea to split very long documents or ones that contain
optional parts into multiple source files. For instance, if a document has a
section that is specific to one operating system, that section could be
omitted when preparing the document for any other operating system.
The keywords @ameword{include} and @ameword{require} instruct Amethyst to load
additional content from another file. When using the latter, processing of the
document will be aborted if the file is not found. When Amythyst encounters
one of these keywords, it loads the included file and parses it fully before
continuing with the original source file.
The command line option @opt{-i} adds a directory to the search path for
included files.
Optional sections should be marked with @ameword{ifdef} or @ameword{ifndef}.
For instance, to only include a source file when @dquote{WIN32} is defined,
you could use the following:
@samp{@pre{@@ifdef@{WIN32@}@{@@require@{win32_specific_section.ame@}@}}}
@notice{Amethyst does not define macros such as @dquote{WIN32}. You will have
to specify them with the option @opt{-d}.}
The @ameword{else} keyword is used together with @ameword{ifdef} and
@ameword{ifndef} to handle the case where the original condition fails. For
instance:
@samp{@pre{@@ifdef@{WIN32@}@{
@@require@{win32_specific_section.ame@}
@}
@@else @{
@@require@{generic_section.ame@}
@}}}
@chapter{Macros}
@section{Standard Library macros}
@subsec{begin}
@a{std_begin}
The @ameword{begin} macro generates the title of the document.
It must be placed before the document content. The following macros provide
additional information to be placed in the beginning of the document.
@table{20 80}{
@header{Macro} @tab @header{Meaning} @row{single}
AUTHOR @tab Name of the author @row
EMAIL @tab Email address of the author @row
LINK @tab Contact web address @row
ONELINER @tab (Man pages only) One sentence to describe the document @row
TITLE @tab Title of the document @row
VERSION @tab Version number
}
For instance, the following would specify the author name for the document:
@samp{@pre{@@macro@{AUTHOR@}@{John Doe@}}}
@notice{The macros above must to be defined before @file{amestd} is included
or they have no effect.}
@subsec{Utilities}
@table{32 38 30}{
@header{Purpose} @tab @header{Usage} @tab @header{Result} @row{single}
No space before @tab a @ameword{glue}@amearg{b c} @tab a @glue{b c} @row
Remove all spaces @tab @ameword{nsp}@amearg{a b c d} @tab @nsp{a b c d} @row
Force a space @tab a@glue{@ameword{sp}}@nsp{@{@}}, @tab a@sp{}, @row
Current date @tab @ameword{date} @tab @date @row
Anchor @tab @ameword{a}@amearg{id} @tab @a{example_id} @row
Reference @tab @ameword{ref}@amearg{id}@amearg{See here} @tab @ref{example_id}{See here} @row
Underline @tab @ameword{underline}@amearg{Text} @tab @underline{Text} @row
Double quotes @tab @ameword{dquote}@amearg{Hello} @tab @dquote{Hello} @row
Web link @tab @ameword{link}@amearg{A}@amearg{http://a.com} @tab @link{A}{http://a.com} @row
Email link @tab @ameword{mailto}@amearg{@nsp{b@@a.com}} @tab @mailto{b@@a.com} @row
Notice @tab @ameword{notice}@amearg{Remark.} @tab @row
Table of Contents @tab @ameword{toc} @tab
}
@section{Writing macros}
@a{writing_macros}
A macro is defined with the @ameword{macro} keyword. It has two arguments:
@list{
@item Name of the macro.
@item Content of the macro. In the content you can use @ameword{arg} to
refer to parameters given to the macro.
}
The following defines a simple macro that has a single parameter:
@samp{@pre{@@macro@{square@}@{@@arg * @@arg@}}}
@macro{square}{@arg * @arg}
When this macro is invoked as @ameword{square}@amearg{x}, the output is
@square{x}.
The following is an example of a macro with two parameters:
@samp{@pre{@@macro@{sum@}@{@@arg@{1@}+@@arg@{2@}@}}}
@macro{sum}{@arg{1}+@arg{2}}
The output of @ameword{sum}@amearg{x}@amearg{y} would be @sum{x}{y}.
@notice{When using @ameword{ifdef} or @ameword{ifndef} inside a macro, the
identifiers in the conditions must be defined before the macro definition is
parsed. Defining the identifier afterwards does not affect the macro contents.
In other words, @ameword{ifdef} acts like a preprocessor @cmd{#ifdef} in C.}
@notice{See the @file{.ame} files in @stdlib for examples of more complex
macros.}
@chapter{Bugs}
Amethyst is a work in progress and contains a number of bugs. The filters in
the Standard Library may not cover all the scenarios you apply them to, or
some unexpected circumstances may lead to unwanted output being generated.
Contact @mailto{@EMAIL} if you are experiencing any problems or have questions.