====== Introduction ======


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> 


====== Getting started ======



===== Acquiring Amethyst =====


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 


===== Installation =====


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

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

<code>
# cmake ../doomsday/tools/amethyst</code>
  -  Compile.
  -  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.
 


===== Generating documents =====


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

<code>
# amethyst -dHTML guide.ame > guide.html</code> 

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

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

To view a list of the available command line options: 

<code>
# amethyst --help</code> 

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

^ Output filter^ Option |
| Plain text| ''[[-d_txt]]'' |
| HTML| ''[[-d_html]]'' |
| Rich text| ''[[-d_rtf]]'' |
| Unix manual page| ''[[-d_man]]'' |
| Mediawiki source| ''[[-d_wiki]]'' |
 


====== Writing a document ======



===== 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., {{cmd|@}}{{cmd|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: 

<code>
@chapter{Introduction}</code> 

In this case, "Introduction" is the parameter given to the {{cmd|@}}{{cmd|chapter}} keyword. 

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

<code>
Escaping the @@ character.</code> 

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

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


===== Preamble =====


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

  -  Set the title of the document by defining a macro called "TITLE".
  -  Include the //amestd// //.ame// definitions.
  -  Place {{cmd|@}}{{cmd|begin}} before the document content.
 

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

<code>
@macro{TITLE}{Quick Guide to Amethyst}
@require{amestd}
@begin</code> 

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


===== 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 //emphasize// a word with {{cmd|@}}{{cmd|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. 

^ Style^ Meaning |
| {{cmd|@}}{{cmd|acro}}| Acronym |
| {{cmd|@}}{{cmd|caption}}| Table caption |
| {{cmd|@}}{{cmd|cmd}}| Command |
| {{cmd|@}}{{cmd|def}}| Definition; first use of a term |
| {{cmd|@}}{{cmd|email}}| Email address |
| {{cmd|@}}{{cmd|em}}| Emphasized text |
| {{cmd|@}}{{cmd|file}}| File name or path |
| {{cmd|@}}{{cmd|header}}| Table header |
| {{cmd|@}}{{cmd|kbd}}| Keyboard; Ctrl-A |
| {{cmd|@}}{{cmd|opt}}| Command line option |
| {{cmd|@}}{{cmd|strong}}| Strong typeface |
| {{cmd|@}}{{cmd|tag}}| Verbatim HTML tag; // italic // |
| {{cmd|@}}{{cmd|url}}| URL or web link |
| {{cmd|@}}{{cmd|var}}| 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 {{cmd|@}}{{cmd|ameword}} macro is used for all keywords and macro names. See Writing macros for more information. 


===== Paragraphs =====


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

<code>
First paragraph.
Still part of the first paragraph.
    
Second paragraph.</code> 

You can use the {{cmd|@}}{{cmd|br}} keyword to force a line break and {{cmd|@}}{{cmd|break}} to force a paragraph break. 


==== Alignment ====


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

<code>
@right{This paragraph is aligned to the right.}
@center{This paragraph is centered.}</code> 


==== Styles ====


The {{cmd|@}}{{cmd|ind}} keyword is used to indent a paragraph: 

<code>
@ind{Indented.}</code> 

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

^ Style^ Meaning |
| {{cmd|@}}{{cmd|cite}}| Citation or quote |
| {{cmd|@}}{{cmd|code}}| Block of source code (see {{cmd|@}}{{cmd|pre}}) |
| {{cmd|@}}{{cmd|samp}}| Example of something |
 


==== Preformatted text ====


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

<code>
@pre{This is an 
    example of
   preformatted
  text.}</code> 

The above would produce: 

<code>
This is an 
    example of
   preformatted
  text.</code> 


===== Chapters and sections =====


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

^ Keyword^ Meaning |
| {{cmd|@}}{{cmd|part}}| Highest-level division: chapters are divided into parts |
| {{cmd|@}}{{cmd|chapter}}| Chapter; e.g., "Introduction" in this document |
| {{cmd|@}}{{cmd|section}}| Section |
| {{cmd|@}}{{cmd|subsec}}| Subsection |
| {{cmd|@}}{{cmd|sub2sec}}| 2nd-level subsection |
| {{cmd|@}}{{cmd|sub3sec}}| 3rd-level subsection |
| {{cmd|@}}{{cmd|sub4sec}}| 4th-level subsection |
 

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


===== Lists =====


A bulleted list can be created as follows: 

<code>
@list{
    @item First item.
    @item Second item.
}</code> 

To create an enumerated list, apply a style modifier. 

<code>
@list/enum{
    @item First enumerated item.
    @item Second enumerated item.
}</code> 

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

<code>
@list/enum/thin{
    @item First enumerated item, tightly packed.
    @item Second enumerated item, tightly packed.
}</code> 

A definition list is useful when you have a set of terms that need to be explained. It can be created as follows: 

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

That would produce the following: 


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


===== Tables =====


A table can be created with the {{cmd|@}}{{cmd|table}} keyword. It takes two arguments. 

  *  Widths of the table columns as percentages.
  *  Table content, with columns separated by {{cmd|@}}{{cmd|tab}} and rows separated by {{cmd|@}}{{cmd|row}}.
 

For instance, to create a table with three columns: 

<code>
@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
}</code> 

The output of this looks like: 

^ A^ B^ C |
| Cell 1| Cell 2| Cell 3 |
| Cell 4| Cell 5| Cell 6 |
 

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


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


===== 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 {{cmd|@}}{{cmd|include}} and {{cmd|@}}{{cmd|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 {{cmd|@}}{{cmd|ifdef}} or {{cmd|@}}{{cmd|ifndef}}. For instance, to only include a source file when "WIN32" is defined, you could use the following: 

<code>
@ifdef{WIN32}{@require{win32_specific_section.ame}}</code> 

<blockquote>**Note:** Amethyst does not define macros such as "WIN32". You will have to specify them with the option ''[[-d]]''.</blockquote> 

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

<code>
@ifdef{WIN32}{
    @require{win32_specific_section.ame}
}
@else {
    @require{generic_section.ame}
}</code> 


====== Macros ======



===== Standard Library macros =====



==== begin ====


The {{cmd|@}}{{cmd|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. 

^ Macro^ Meaning |
| AUTHOR| Name of the author |
| EMAIL| Email address of the author |
| LINK| Contact web address |
| ONELINER| (Man pages only) One sentence to describe the document |
| TITLE| Title of the document |
| VERSION| Version number |
 

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

<code>
@macro{AUTHOR}{John Doe}</code> 

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


==== Utilities ====


^ Purpose^ Usage^ Result |
| No space before| a {{cmd|@}}{{cmd|glue}}{b c}| ab c |
| Remove all spaces| {{cmd|@}}{{cmd|nsp}}{a b c d}| abcd |
| Force a space| a{{cmd|@}}{{cmd|sp}}{},| a , |
| Current date| {{cmd|@}}{{cmd|date}}| 2015-11-15 |
| Anchor| {{cmd|@}}{{cmd|a}}{id} |
| Reference| {{cmd|@}}{{cmd|ref}}{id}{See here}| See here |
| Underline| {{cmd|@}}{{cmd|underline}}{Text}| Text |
| Double quotes| {{cmd|@}}{{cmd|dquote}}{Hello}| "Hello" |
| Web link| {{cmd|@}}{{cmd|link}}{A}{http://a.com}| [[http://a.com|A]] |
| Email link| {{cmd|@}}{{cmd|mailto}}{b@a.com}| [[mailto:b@a.com|b@a.com]] |
| Notice| {{cmd|@}}{{cmd|notice}}{Remark.} |
| Table of Contents| {{cmd|@}}{{cmd|toc}} |
 


===== Writing macros =====


A macro is defined with the {{cmd|@}}{{cmd|macro}} keyword. It has two arguments: 

  *  Name of the macro.
  *  Content of the macro. In the content you can use {{cmd|@}}{{cmd|arg}} to refer to parameters given to the macro.
 

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

<code>
@macro{square}{@arg * @arg}</code> 

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

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

<code>
@macro{sum}{@arg{1}+@arg{2}}</code> 

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

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

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


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