Log in Help
Homegatewikicowtestunitgateyamresources 〉 yam-comprehensive.html

YAM: Yet Another Markup


This page documents YAM's syntax and bugs/wishlist.

Yet Another Mark-up (YAM) is derived from Terrance's Mark-up Language 1. It embodies the simplicity of wiki editing languages, but it is open to extension through the use of plug-ins.

The YAM translator is easily extended with new output languages. Currently it can produce output in HTML and LaTeX and thence PDF.

Although simple YAM is rich in features. From simple text processing features like bold, emphasis. and teletype to tables, a title page, and a table of contents, there is a range of features which can help create highly presentable documents in both LaTeX and HTML:

Plug-ins in particular are very powerful and allow different extensions such as comments, boxed text, date and time support, etc.

1. YAM Syntax

1.1. Bold, italic and teletype #bold

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 equals signs: ^this is teletype^ becomes this is teletype.

1.2. Horizontal lines #hr

Horizontal lines are indicated by 2 or more '-' signs at the start of a line. For example:




both result in:

1.3. Lists #lists

Unordered lists are indicated by 'o' at the start of a line, and ordered lists by '-'. Nesting is indicated by two spaces 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:

1.4. Verbatim output #verbatim

Verbatim output starts with '%<' at the start of a line and ends with '%>'. For example:

This *will not* get translated
% > (imagine there were no space between the % and the >)

When the target language is HTML, for example, the output will contain '&lt;pre&gt;' tags. It is also possible to tell the translator to write output directly without any intervention, using '%output':%

This will not get translated either, but any markup in the target
language will be interpreted in that language.

</pre> %>

1.5. Notes #notes

Notes are like this:

\%notes("This is a note")

The contents will be output to the translation file, but will be commented out in that file. The quotation marks around the note are necessary; notes cannot contain quotation marks (even if escaped).

1.6. Escapes #escapes

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


will not generate a line.

Some syntax elements interact with each other and produce unexpected escaping behaviour. For example, in


the equals signs are translated, but not the URL they contain (with the result 'http://gate.ac.uk/').

1.7. Headings #headings

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

%2 Headings

1.8. Links and anchors #links

Links can be specified in four 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 'label', e.g. GATE home will become GATE home
  4. Using Wiki syntax % NOT DONE YET

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

%2 A Heading #label

will result in a heading followed by the anchor label.

1.9. Quotations #quotations

Quotations are enclosed in '"' marks that start are preceded by two spaces at the start of a line. For example,

  %"This is a quote%"


This is a quote

1.10. Line breaks #linebreaks

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

This line is broken%\
in two.

becomes:% This line is broken% in two.

1.11. Tables #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

1.12. Plugins #plugins


2. Development Notes

2.1. Bugs:

  1. include plugin only works from command line, otherwise it looks for the file in the plugins directory, and that's no good. get resource doesn't appear to work well either in this case
  2. the target in a url gets interpreted as an anchor when the protocol isn't specified (e.g. antlr.org/doc/lexer.html#unicode)
  3. unclosed = causes open tt with no close
  4. text at the end of a URL can get included in the URL, e.g. http://antlr.org/doc/lexer.html#unicode: includes the ":"
  5. there's no way to end an embedded list element except by another list element (embedded or higher level)
  6. percentage signs need to be escaped in latex output
  7. odd behaviour on non-native newlines (e.g. ^M on macs)
  8. URLs that contain commas don't work properly with the %() syntax
  9. URLs don't work in headings
  10. the type of the .yam character set should be output to the HTML, e.g. UTF-8; a simplified way to get better encoding treatment would be:
    • put all input files in UTF-8 (e.g. by opening them in GUK)
    • check that YAM uses Readers and Writers and sets them to use UTF-8
    • oddly enough, wc will report unusual characters

2.1.1. Completed:

  1. the citation plugin is HTML specific
  2. the citation plugin closes any embedding lists; what is needed is to be able to tell the context not to do further processing on the results of the plugin, instead of using the output mechanism
  3. an empty notes field results in null pointer exception

2.2. Wish list:

2.2.1. Completed:

I couldn't escape an underscore in this sentence

2.3. WikiLinks WikiLinks are just links, created either like other links (%(...)), or by typing a WikiWord. Some points:

2.4. New Parser

To run the JspWiki converter from the command line (from the test/resources directory):

java -classpath ../../../target/yam-1.0-SNAPSHOT.jar:../../../lib/gate.jar
gate.yam.convert.JspWiki2Yam jsp-comprehensive.txt


  1. http://www.antlr.org/TML/index.tml