Log in Help
Print
Home 〉 gatewiki 〉 cow 〉 doc 〉 yam 〉 yam-syntax.html
 

YAM Syntax

Contents

1. Introduction

YAM (Yet Another Markup) is a simple wiki language used in GATEWiki. The language syntax is described below.

2. Contents

Contents listings like that above are generated by '%contents'

3. Bold, italic, underline and teletype

Bold text is contained in stars: *this is bold* becomes this is bold.

Italic text is contained in underscores: _this is italic_ becomes this is italic.

Fixed-width text is contained in carat signs: ^this is teletype^ becomes this is teletype.

Underlined text is contained in doubles undercores: __this is underlined__ becomes this is underlined.

4. Horizontal lines

Horizontal lines are indicated by 3 or more dashes at the start of a line. For example:

---

and

---------------------------

both result in:

5. Lists

Unordered lists are indicated by '-' at the start of a line, and ordered lists by '#'. Nesting is indicated by increased spacing preceding the item indicator. For example:

- This is an undordered list
- Second item
  # This is a nested...
  # ...ordered list
- Back to the third item of the enclosing list

results in:

The precise size of the indentation of embedded lists doesn't matter, it just needs to be larger than that of the enclosing list.

Lists end when there is a blank line or where the next line of text is not indented. For example:

- This is a one item list
followed by
- another one item list.

results in:

followed by

Note: lists embedded in tables have to start on a new line, just like elsewhere; in tables a syntax error will result if the list starts on the same line as the rest of the row.

6. Verbatim output

Verbatim output starts with '%<' and ends with '%>'. For example:

%< This will *not* get translated. %>

When the target language is HTML, for example, the output will contain '<pre>' tags.

For code listings you can enable syntax highlighting with

%code(lang=Java)<
public void hello() {
  System.out.println("hello world");
}
%>

which produces

public void hello() {
  System.out.println("hello world");
}
Highlighting is performed in HTML using google-code-prettify and in LaTeX using the listings package. The list of supported language names is slightly different for the two packages (HTML, LaTeX) but mainstream languages including "C", "Java", "Python", "HTML", "XML", "CSS" and "TeX" are supported by both. When translating yam to HTML (but not to LaTeX) the highlighter will attempt to guess the appropriate language if you omit the lang specification altogether (%code()< ... %>).

By default, the listing does not have line numbers. Numbering can be enabled using the option numbering=on, plus an optional firstnumber=N if you want to start numbering from something other than 1. Note that in HTML only every fifth line is numbered in the default google-code-prettify CSS style.

7. Footnotes

Footnotes are like this:

%footnote(This is a footnote.)

Becomes:1.

The contents will be put in a section at the end of the document (HTML) or at the bottom of the page (LaTeX), and linked by number from where they occured.

8. Escapes

To stop a special character from being interpreted, use a '\'. For example,

 \---

will not generate a line.

(This also works for the forward quote or backtick character — ` — which is used in LaTeX but may otherwise be replaced by a normal single quote in HTML output.)

9. Titles and metadata

The title of a document is the first paragraph of the document, ending in one or more blank lines. (Often this will be a single line of text.)

Metadata can be specified using %meta(foo=bar), which in HTML will become

<meta name="foo" content="bar">

in the page header.

10. Headings

Headings are lines starting with %1 (for first level), %2, %3 or %4 and are followed by one or more blank lines. For example, the heading for this section is

%1 Headings

If a heading level is followed by "*" it is not numbered, e.g.:

%1* An unnumbered heading

Becomes:

An unnumbered heading

This heading will not appear in the contents table.

11. Links and anchors

Links can be specified in three ways:

  1. As plain text, e.g. 'http://gate.ac.uk/' will become http://gate.ac.uk/
  2. Using '%(target)', e.g. %(http://gate.ac.uk/) will become http://gate.ac.uk/
  3. Using '%(target, label)', e.g. %(http://gate.ac.uk/, GATE home) will become GATE home

Spaces or commas within the link target of %(...) format URLs must be escaped. The link text (following the first unescaped comma) may contain "inline" Yam markup such as %image(...), %cite(...), *bold*, _italic_ or ^teletype^, but not block-level markup such as tables. Parentheses are allowed within link text but left and right parentheses must be balanced, i.e. %(http://example.com, an (example) link) is OK but %(http://example.com, unbalanced ( brackets) is not unless the unmatched parenthesis is escaped.

A URL that appears in plain text must be followed by a space, tab or newline. Sometimes, you might need to follow a URL with something other than a space, tab, or newline, for example when applying other formatting characters. To do this, use a bracketed form. e.g. to teletype a URL, ^%(http://gate.ac.uk/)^ becomes http://gate.ac.uk/.

Anchors and labels are specified using '%#name'. For example,

%1 A Heading %#label

will result in a heading followed by the anchor label. To refer back (or forward) to the anchor, use a "#" in the link, e.g.

%(#tables, tables)

will result in tables.

Spaces or commas inside anchors must be escaped. An anchor that appears in plain text must be followed by a space, tab or newline.

A relative link to a non-existant file will be rendered as a link to the host application's "create" page, e.g. 

 %(../non-existant.html)

becomes:
../non-existant.html

A link to an existing file will be just link as normal, e.g. 

 %(index.html)

becomes:
index.html

12. Block quotations

Block quotations are enclosed in %" marks. For example,

  %"This is a quote%"

becomes:

This is a quote

Note that because the quote marks are treated as normal words, they can cause overlap problems (in the same way that an unclosed bold or italic mark might). For example, 

%"
- list
%"

is not a good idea as the end of the quote will preceed the end of the list. The workaround is to close the list first by adding a blank line:

%"
- list

%"

which then results in something sensible:

13. Line breaks

Line breaks are indicated by %br at the end of a line. For example:

This line is broken %br in two.

becomes:
This line is broken
in two.

14. Tables

Tables use square brackets, bars and dashes. For example:

%[
 | *header col 1*	| *header col 2*        |
 ---
 | row 1 col 1	        | col 2                 |              
 ---
 | row 2 col 1	        | col 2                 |
%]

results in:

header col 1 header col 2
row 1 col 1 col 2
row 2 col 1 col 2

To include a | in normal text escape it like this: \|.

(See also the note above about embedding lists in tables.)

15. Images

Images are like URLs:

You can also specify an ALT tag, width and height, position and border width: '%image(test-image.png, ALT tag, 500, 500, left, 0)' becomes ALT tag

16. Citations

Citations work like this: '%cite(Cun06a)' becomes Cun06a. Multiple cite keys should be separated by commas, e.g.: '%cite(Cun05a,Cun06a)' becomes Cun05a, Cun06a.

17. Inclusion

A page can include another page like this:

%include(yam-first.yam)

This results in the inclusion of all the text from yam-first.yam in this file.

An increment to be added to the heading level can be given as the first argument.

Note that the titles in the included files are ignored by default. A "useTitle" flag can be given (after the increment if it exists) to cause inclusion of the title (as a heading). For example: %include(1, useTitle, yam-first.yam).

18. Non-breaking space

Non-breaking spaces are added using %\ followed by space, e.g.

This line %\ %\ %\ %\ has spaces in the middle.

This line     has spaces in the middle.

19. Comments

Single-line comments are created by two or more percents together, e.g.

This is not commented   %% but this is

becomes:
This is not commented

Multi-line comments are created by %/* and %*/, e.g.

This is not commented   %/* but this is
and this is too %*/

becomes:
This is not commented

20. Plugins

YAM can be extended by the use of plugins. Creating plugins requires some Java programming - see the developer guide for more details.

Plugins bundled with GATEWiki:

21. Changes from version 3

YAM is currently in version 5. Since versions 3 and 4 these changes were made:

Footnotes

  1. This is a footnote.