Ace Code Editor

An AsciiDoc document is composed of several hierarchical elements:

1. Header (Optional): Contains metadata like title, author, and revision information. Must be followed by blank lines.
2. Preamble (Optional): An untitled section body located between the Header and the first Section.
3. Sections: The core content, organized into up to four levels (1 to 4). Sections are delimited by section titles.

Document Hierarchy

• Document $\rightarrow$ Header $\rightarrow$ Preamble $\rightarrow$ Sections
• Section $\rightarrow$ SectionBody $\rightarrow$ Blocks (Paragraphs, Lists, Tables, etc.)

To append block elements (like paragraphs or code blocks) to a list item, use a 'list continuation'—a separator line containing a single plus character (+). Without this, subsequent blocks are treated as new, separate elements.

1. List item one.
+
List item one continued with a second paragraph.
+
[source,python]
----
print('Hello')
----

Document attributes are used for textual substitution using the {name} syntax. They are case-insensitive and can contain alphanumeric characters, dashes, and underscores.

Defining Attributes

Attributes can be defined in the document header or via AttributeEntry blocks:

:author: Stuart Rackham
:email: srackham@gmail.com

To delete (undefine) an attribute, use:

:name!:

Attribute Precedence (Highest to Lowest)

1. Command-line attributes
2. AttributeEntry, AttributeList, Macro, and BlockId elements
3. Configuration file [attributes] sections
4. Intrinsic attributes

Conditional Inclusion

If an attribute is undefined, the line containing its reference is dropped. This is useful for conditional markup.

:author: Stuart Rackham
:email: srackham@gmail.com

See the {author} at {email}.

The theme attribute allows you to select an alternative CSS stylesheet and include additional JavaScript code.

• Usage: Set the attribute via the command line --theme <name> or as an attribute theme=<name>.
• Theme Structure: Themes must reside in a configuration directory under themes/<theme>/. A theme requires a <theme>.css file (which replaces asciidoc.css) and can optionally include a <theme>.js file.
• Built-in Themes: AsciiDoc includes flask and volnitsky themes.
• Icons: If the data-uri attribute is defined, icons are loaded from the theme's icons sub-directory.

# Using the command line option
$ asciidoc --theme foo article.txt

# Using the attribute
$ asciidoc -a theme=foo article.txt

The AsciiDoc plugin architecture allows users to add new backends, filters, and themes via Zip files.

Plugin Management

You can manage plugins using the asciidoc(1) command-line options --backend, --filter, and --theme. These options support the following management commands:

• install
• list
• remove
• build

Key Rules

• Precedence: Filter plugins take precedence over built-in filters with the same name.
• Installation Path: By default, filter plugins are installed in $HOME/.asciidoc/filters/<filter_name>.
• Naming Convention: The plugin Zip file name must begin with the name of the backend, filter, or theme it contains.

# Example plugin management commands
asciidoc --filter install <plugin_name>
asciidoc --filter list

AsciiDoc supports three primary document types. You can specify the type using the asciidoc(1) -d or --doctype option. The default type is article.

By convention, AsciiDoc source files use the .txt extension.

Ace uses the dryice build tool. Before building, ensure all submodules are initialized.

• To create a standard package: use ./Makefile.dryice.js normal.
• To create a bookmarklet version: use ./Makefile.dryice.js bm.

Output files are placed in the build directory.

# Initialize submodules first
git submodule update --init --recursive

# Build normal version
./Makefile.dryice.js normal

# Build bookmarklet version
./Makefile.dryice.js bm

Lists must always start after a blank line (a new paragraph).

Enumerated Lists

Use numbers, letters, or roman numerals followed by a period ., a right bracket ), or surrounded by brackets ( ).

Bulleted Lists

Use bullet point characters: -, +, or *.

Definition Lists

Consist of a term followed by its definition. The definition must be indented relative to the term. Blank lines are not allowed between the term and its definition.

1. numbers
A. upper-case letters
a. lower-case letters

* bullet point
  - sub-list

term
  definition of the term

While you usually don't need to build Ace (you can use ace-builds), you can package it using the dryice build tool.

First, install dependencies:

npm install

Then, run the build script:

node ./Makefile.dryice.js

Build Options:

• -m: Minify build files with uglify-js.
• -nc: Namespace require and define calls with "ace".
• -bm: Build the bookmarklet version.
• --target ./path: Specify the relative path for the output folder (default is ./build).

To generate all files for the ace-builds repository:

node Makefile.dryice.js full --target ../ace-builds