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 (amestd). It is for people who wish to write documentation but are not interested in the internal workings of the text processor.

<blockquote>Note: 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 amestd contain no hard-coded functionality: everything has been defined using .ame macros.</blockquote>

Before you grab a copy of the sources you should make sure you have the following software installed on your system:

• Git.
• Qt libraries.
• CMake.

The Amethyst source code is included in the Doomsday Engine Git repository:

http://github.com/skyjake/Doomsday-Engine/tree/master/doomsday/tools/amethyst

Even though Amethyst is part of the Doomsday tools subdirectory, it can be built independently from the rest of the CMake projects.

1. Create a build directory. This should be outside the Doomsday source tree.
2. Run CMake to configure the build. For example:

# cmake ../doomsday/tools/amethyst

1. Compile.
2. Run the “install” rule defined in the project file. On a Unix this will install amethyst and amestd into the appropriate directories. On Windows the installation is done to a subdirectory called inst under the Amethyst source directory.

To generate an HTML version of this guide on Unix, run this command in the Amethyst doc directory:

# amethyst -dHTML guide.ame > guide.html

To generate a plain text version of this guide on Windows, run this command in the inst directory:

# amethyst -dTXT -i../lib -oguide.txt ../doc/guide.ame

To view a list of the available command line options:

# amethyst --help

amestd defines the following output filters, chosen with a command line option.

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., @section) and amestd 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:

@chapter{Introduction}

In this case, “Introduction” is the parameter given to the @chapter keyword.

If you wish to use the characters @, {or} for normal document content, they need to be escaped by putting another @ in front.

Escaping the @@ character.

Lines that begin with $ are comments. To begin a longer commented section, use $*. The comment section ends at *$.

$ This is a line of comment.
$* Begin a longer comment...
...inside the comment...
and end here. *$

When using amestd the document needs to have the following preamble:

1. Set the title of the document by defining a macro called “TITLE”.
2. Include the amestd .ame definitions.
3. Place @begin before the document content.

For instance, the source of this document could begin like this:

@macro{TITLE}{Quick Guide to Amethyst}
@require{amestd}
@begin

See the begin macro for more information about what information is added to the beginning of the document.

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 emphasize a word with @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.

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 macro is used for all keywords and macro names. See Writing macros for more information.

Whitespace is mostly ignored in Amethyst source files. The exception is that one or more empty lines separate paragraphs.

First paragraph.
Still part of the first paragraph.
    
Second paragraph.

You can use the @br keyword to force a line break and @break to force a paragraph break.

By default, text is left-aligned inside a paragraph. You may also use right alignment or centered text.

@right{This paragraph is aligned to the right.}
@center{This paragraph is centered.}

The @ind keyword is used to indent a paragraph:

@ind{Indented.}

There are three other indented paragraph styles, useful for different kinds of content:

The @pre keyword is used for preformatted text. The special characters @, {and} still need to be escaped inside @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.

@pre{This is an 
    example of
   preformatted
  text.}

The above would produce:

This is an 
    example of
   preformatted
  text.

The structure of the document is marked with the following keywords.

A table of contents is generated by @toc based on the titles defined with the keywords above. @toc is defined in amestd and its output varies depending on the chosen filter.

A bulleted list can be created as follows:

@list{
    @item First item.
    @item Second item.
}

To create an enumerated list, apply a style modifier.

@list/enum{
    @item First enumerated item.
    @item Second enumerated item.
}

Some output filters support using a thin modifier to remove whitespace between items. This is useful for a list of short items.

@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:

@deflist{
    @item{Term one} Description of the first term.
    @item{Another term} Explanation of the second one.
}

That would produce the following:

Term one
Description of the first term. Another term
Explanation of the second one.

A table can be created with the @table keyword. It takes two arguments.

• Widths of the table columns as percentages.
• Table content, with columns separated by @tab and rows separated by @row.

For instance, to create a table with three columns:

@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:

<blockquote>Note: 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.</blockquote>

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).

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 @include and @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 -i adds a directory to the search path for included files.

Optional sections should be marked with @ifdef or @ifndef. For instance, to only include a source file when “WIN32” is defined, you could use the following:

@ifdef{WIN32}{@require{win32_specific_section.ame}}

<blockquote>Note: Amethyst does not define macros such as “WIN32”. You will have to specify them with the option -d.</blockquote>

The @else keyword is used together with @ifdef and @ifndef to handle the case where the original condition fails. For instance:

@ifdef{WIN32}{
    @require{win32_specific_section.ame}
}
@else {
    @require{generic_section.ame}
}

The @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.

For instance, the following would specify the author name for the document:

@macro{AUTHOR}{John Doe}

<blockquote>Note: The macros above must to be defined before amestd is included or they have no effect.</blockquote>

A macro is defined with the @macro keyword. It has two arguments:

• Name of the macro.
• Content of the macro. In the content you can use @arg to refer to parameters given to the macro.

The following defines a simple macro that has a single parameter:

@macro{square}{@arg * @arg}

When this macro is invoked as @square{x}, the output is x * x.

The following is an example of a macro with two parameters:

@macro{sum}{@arg{1}+@arg{2}}

The output of @sum{x}{y} would be x + y.

<blockquote>Note: When using @ifdef or @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, @ifdef acts like a preprocessor #ifdef in C.</blockquote>

<blockquote>Note: See the .ame files in amestd for examples of more complex macros.</blockquote>

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 jaakko.keranen@iki.fi if you are experiencing any problems or have questions.