This shows you the differences between two versions of the page.
— | devel:quick_guide_to_amethyst [2015-11-15 11:56] (current) – created - external edit 127.0.0.1 | ||
---|---|---|---|
Line 1: | Line 1: | ||
+ | |||
+ | |||
+ | ====== 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 (// | ||
+ | |||
+ | < | ||
+ | |||
+ | |||
+ | ====== 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: | ||
+ | |||
+ | | ||
+ | |||
+ | |||
+ | ===== Installation ===== | ||
+ | |||
+ | |||
+ | Even though Amethyst is part of the Doomsday //tools// subdirectory, | ||
+ | |||
+ | - Create a build directory. This should be outside the Doomsday source tree. | ||
+ | - Run CMake to configure the build. For example: | ||
+ | |||
+ | < | ||
+ | # cmake ../ | ||
+ | - Compile. | ||
+ | - Run the " | ||
+ | |||
+ | |||
+ | |||
+ | ===== Generating documents ===== | ||
+ | |||
+ | |||
+ | 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 ../ | ||
+ | |||
+ | To view a list of the available command line options: | ||
+ | |||
+ | < | ||
+ | # amethyst --help</ | ||
+ | |||
+ | //amestd// defines the following output filters, chosen with a command line option. | ||
+ | |||
+ | ^ Output filter^ Option | | ||
+ | | Plain text| '' | ||
+ | | HTML| '' | ||
+ | | Rich text| '' | ||
+ | | Unix manual page| '' | ||
+ | | Mediawiki source| '' | ||
+ | |||
+ | |||
+ | |||
+ | ====== Writing a document ====== | ||
+ | |||
+ | |||
+ | |||
+ | ===== Basic syntax ===== | ||
+ | |||
+ | |||
+ | When you write a document with Amethyst, you are giving the text processor two types of information: | ||
+ | |||
+ | 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, " | ||
+ | |||
+ | 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 {{cmd|$}} are comments. To begin a longer commented section, use {{cmd|$}}{{cmd|*}}. The comment section ends at {{cmd|*}}{{cmd|$}}. | ||
+ | |||
+ | < | ||
+ | $ This is a line of comment. | ||
+ | $* Begin a longer comment... | ||
+ | ...inside the comment... | ||
+ | and end here. *$</ | ||
+ | |||
+ | |||
+ | ===== Preamble ===== | ||
+ | |||
+ | |||
+ | When using //amestd// the document needs to have the following preamble: | ||
+ | |||
+ | - Set the title of the document by defining a macro called " | ||
+ | - Include the //amestd// //.ame// definitions. | ||
+ | - Place {{cmd|@}}{{cmd|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. | ||
+ | |||
+ | |||
+ | ===== 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 // | ||
+ | |||
+ | 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. | ||
+ | |||
+ | < | ||
+ | First paragraph. | ||
+ | Still part of the first paragraph. | ||
+ | | ||
+ | Second paragraph.</ | ||
+ | |||
+ | 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. | ||
+ | |||
+ | < | ||
+ | @right{This paragraph is aligned to the right.} | ||
+ | @center{This paragraph is centered.}</ | ||
+ | |||
+ | |||
+ | ==== Styles ==== | ||
+ | |||
+ | |||
+ | The {{cmd|@}}{{cmd|ind}} keyword is used to indent a paragraph: | ||
+ | |||
+ | < | ||
+ | @ind{Indented.}</ | ||
+ | |||
+ | 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}}, | ||
+ | |||
+ | < | ||
+ | @pre{This is an | ||
+ | example of | ||
+ | | ||
+ | text.}</ | ||
+ | |||
+ | The above would produce: | ||
+ | |||
+ | < | ||
+ | This is an | ||
+ | example of | ||
+ | | ||
+ | text.</ | ||
+ | |||
+ | |||
+ | ===== 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., " | ||
+ | | {{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: | ||
+ | |||
+ | < | ||
+ | @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 {{cmd|thin}} modifier to remove whitespace between items. This is useful for a list of short items. | ||
+ | |||
+ | < | ||
+ | @list/ | ||
+ | @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. | ||
+ | |||
+ | |||
+ | ===== 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: | ||
+ | |||
+ | < | ||
+ | @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: | ||
+ | |||
+ | ^ A^ B^ C | | ||
+ | | Cell 1| Cell 2| Cell 3 | | ||
+ | | Cell 4| Cell 5| Cell 6 | | ||
+ | |||
+ | |||
+ | < | ||
+ | |||
+ | |||
+ | ===== 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 '' | ||
+ | |||
+ | Optional sections should be marked with {{cmd|@}}{{cmd|ifdef}} or {{cmd|@}}{{cmd|ifndef}}. For instance, to only include a source file when " | ||
+ | |||
+ | < | ||
+ | @ifdef{WIN32}{@require{win32_specific_section.ame}}</ | ||
+ | |||
+ | < | ||
+ | |||
+ | 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: | ||
+ | |||
+ | < | ||
+ | @ifdef{WIN32}{ | ||
+ | @require{win32_specific_section.ame} | ||
+ | } | ||
+ | @else { | ||
+ | @require{generic_section.ame} | ||
+ | }</ | ||
+ | |||
+ | |||
+ | ====== 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: | ||
+ | |||
+ | < | ||
+ | @macro{AUTHOR}{John Doe}</ | ||
+ | |||
+ | < | ||
+ | |||
+ | |||
+ | ==== 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}}{}, | ||
+ | | 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}| " | ||
+ | | Web link| {{cmd|@}}{{cmd|link}}{A}{http:// | ||
+ | | Email link| {{cmd|@}}{{cmd|mailto}}{b@a.com}| [[mailto: | ||
+ | | 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: | ||
+ | |||
+ | < | ||
+ | @macro{square}{@arg * @arg}</ | ||
+ | |||
+ | When this macro is invoked as {{cmd|@}}{{cmd|square}}{x}, | ||
+ | |||
+ | The following is an example of a macro with two parameters: | ||
+ | |||
+ | < | ||
+ | @macro{sum}{@arg{1}+@arg{2}}</ | ||
+ | |||
+ | The output of {{cmd|@}}{{cmd|sum}}{x}{y} would be x + y. | ||
+ | |||
+ | < | ||
+ | |||
+ | < | ||
+ | |||
+ | |||
+ | ====== 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: | ||