Writing ACE Text Pages

ACE text pages are likely to make up the bulk of a my.strathspey web site. ACE text also crops up in other places on my.strathspey (such as event descriptions and auxiliary texts in the dance database) so finding out how to write ACE text is a worthwhile endeavour.

To write ACE text, the best tool is a »text editor«. Your computer's operating system should have come with one, and they are available by the dozen for free download. Good ones include Kate (from KDE), Emacs or vi if you're on Linux; Microsoft Windows comes with a program called »Textpad« which ought to be OK in a pinch (any better suggestions?). Don't use OpenOffice.org Writer or Microsoft Word, or if you must, save your files as »plain text« – .TXT rather than .DOC or .ODT.

ACE likes its content UTF-8 encoded, so use a text editor that can handle UTF-8. (For those who must know, and to grossly oversimplify things, UTF-8 is a method of writing down unusual characters such as German umlauts or, on suitably equipped computers, Arabic, Japanese, Chinese, or Sanskrit characters.) Usually a good editor will let you pick an »encoding« for the file you're editing, so choose »UTF-8«. If you're American and don't use foreign languages anyway, don't worry – you don't need to change anything.

Basics

Here is a very simple ACE text object:

Title: My first ACE text object

Hello world
===========

This is my first ACE text object.

(We shall be showing examples of ACE text on a greenish background like so; remember that this is what you have to put into a file to see a nice HTML rendering later.)

We can observe the following:

  • At the beginning of an ACE text object there is a »metadata block« giving additional information that ACE uses to present and manage the object. This block extends from the start of the file to the first line that is entirely empty (i.e., not even spaces) – in our example, the »Title:« line. We're going to cover metadata in more detail later; for now, the »Title:« gives the page's title as it will appear in the browser title bar.

  • The remainder of the ACE text object consists of »blocks« separated by empty lines. These blocks can be paragraphs of text but they can also be other things, like the one that starts with »Hello World«, which is a header. Other types of block include tables or entries in itemised or enumerated lists.

Paragraphs of Text

You can write paragraphs of text pretty much as you would write an e-mail message. Do not worry about line breaks; web browsers will put in their own line breaks where they like, anyway. Just remember that you need to use an empty line to separate one paragraph from the next. (Any number of empty lines will do but there needs to be at least one.)

Here is a paragraph.
This paragraph consists of two input lines, one of which is fairly long.

Here is the next paragraph.
This is the second line of this paragraph.
This is the last line in this paragraph.

comes out as

Here is a paragraph. This paragraph consists of two input lines, one of which is fairly long.

Here is the next paragraph. This is the second line of this paragraph. This is the last line in this paragraph.

You can use various forms of emphasis, such as bold or italic type, to highlight words or short passages of text. This works like so:

You can use various forms of emphasis, such as _bold_
or *italic* type, ...

(Unfortunately, or maybe fortunately, ACE does not do bold italic type.)

Use a minus sign as a hyphen and a double minus sign for what typographers call an »en dash«. The difference is that a hyphen separates parts of a compound word while an en dash separates parts of a phrase:

There are three basic steps in quick tempo -- the *pas de basque*,
the skip-change-of-step and the slip step.

yields

There are three basic steps in quick tempo – the pas de basque, the skip-change-of-step and the slip step.

If you do need line breaks in particular places, for example to write down an address, put two blank spaces at the end of the line in question. You're not going to be able to easily spot the difference, (try highlighting the example input text with the mouse) but

Royal Scottish Country Dance Society  
12 Coates Crescent  
Edinburgh EH3 7AF  
Scotland

gives

Royal Scottish Country Dance Society
12 Coates Crescent
Edinburgh EH3 7AF
Scotland

Headings

ACE text supports three levels of headings – as it is not really meant for long academic treatises, that should be enough for most people. In ACE text, a heading is simply a block consisting of a line of text which is immediately followed by a line of equals signs (first-level heading), minus signs (second-level heading) or tildes (third-level heading), as in

Basic SCD Technique
===================

Foot Positions
--------------

First Position
~~~~~~~~~~~~~~

Normally Anselm uses the first-level heading only at the very beginning of a document, but suit yourselves.

Lists

It is often useful to be able to include lists of items. ACE supports »unordered« lists like

  - Reels
  - Jigs
  - Strathspeys

which gives

  • Reels
  • Jigs
  • Strathspeys

as well as »ordered lists« like

  1. Hooper's Jig
  2. The Braes of Breadalbane
  3. J. B. Milne

which comes out as

  1. Hooper's Jig
  2. The Braes of Breadalbane
  3. J. B. Milne

In fact, the numbers in the input are entirely arbitrary:

 1. Hooper's Jig
 1. The Braes of Breadalbane
 33. J. B. Milne

gives

  1. Hooper's Jig
  2. The Braes of Breadalbane
  3. J. B. Milne

just like the previous example. (This is because your browser does the actual numbering.)

The way this works is as follows:

  • ACE considers paragraphs whose first line is indented by up to three spaces and begins with a minus sign as items of unordered lists. A sequence of such paragraphs is coalesced into a single list.

  • ACE considers paragraphs whose first line is indented by up to three spaces and begins with a sequence of digits (0-9) followed by a period (dot). A sequence of such paragraphs is coalesced into a single list.

List items may consist of more than one paragraph:

- This is the first paragraph of a two-paragraph item.

  This is the next paragraph.

- This is the next item.

results in

  • This is the first paragraph of a two-paragraph item.

    This is the next paragraph.

  • This is the next item.

However, in this case the first paragraph of each item must be indented at least two spaces.

ACE also supports »definition lists«. These are handy for dance descriptions:

1-8:: 1st couple turn giving right hands, cast off (2nd couple
      move up), and turn left hand to finish facing first corners.

9-16:: 1st couple turn first corners giving right hands, partner
      giving left hands, second corners giving right hands, and
      turn giving left hand to finish facing first corners again.

gives

1-8
1st couple turn giving right hands, cast off (2nd couple move up), and turn left hand to finish facing first corners.
9-16
1st couple turn first corners giving right hands, partner giving left hands, second corners giving right hands, and turn giving left hand to finish facing first corners again.

Note the double colon at the end of each set of bar numbers! This is what separates the »label« from the actual item.

Links

It is easy to create hyperlinks that point to other resources on my.strathspey or elsewhere on the Internet. All you need is the URL (web address) of the resource that you want to link to. In ACE text, simply put that between double angle brackets, as in

<<http://www.rscds.org/>>

This will result in a link like

http://www.rscds.org/

(where the actual URL is displayed). Often one prefers a link with explanatory text in place of the slightly ugly URL, as in

<<http://www.rscds.org/|The Royal Scottish Country Dance Society>>

which gives

The Royal Scottish Country Dance Society

If you are pointing to a resource on the same site, you can leave off the »http://« and server name:

<</docs/editing/|Editing Pages on my.strathspey>>

yields

Editing Pages on my.strathspey

and as this page and that other one sit right beside each other in the »/docs« area on our server, this can be further shortened to

<<editing|Editing Pages on my.strathspey>>

giving

Editing Pages on my.strathspey

»Magic« Links

A great deal of effort has gone into making it easy to provide SCD-centric content with ACE. Much of this is done by way of »magic« links, which replace the »http:« of common hypertext links by other »schemes«. For example,

<<ddd:Braes of Breadalbane>>

will link to the page for The Braes of Breadalbane in the Strathspey SCD Database. There are magic links for referring to messages posted to Strathspey, for including images and YouTube videos, and much else. Documentation for magic links is available on a separate page (because this page is already long enough as it is).