The document format
A document behaves like a rather liberal interpretation of a normal ABC file. As normal, a fieldname:value line outside of an Tune block will supply a default value for all subsequent ones, but this goes beyond the original rules by accepting it for all fields, with the exception of Title (ABC's "T:") and Key_Signature (ABC's "K:"), which are required for each tune, and thus meaningless in the wider context. Any lines treated this way will not be printed. The modifiers described for the 'tune block' below can also be used like this.
It gets passed through a program that turns it into something that can be printed. Most of these recognise various magic words that control the formatting - text will be printed according to that formatting, and the block representing a tune will be printed as a picture of the dots. The difference from an ABC file is that where an ABC file would have a block of ABC for a tune, a document here has a different block of text that points the processing at the tune in this site's database. This does away with the duplication of data that occurs if you want the same tune printed in different lists, and also makes it possible to apply some on-the-fly transformations.The text of a document is a list of 2 sorts of thing :-
The Tune block :-
If a line starts with XID: this will be followed by a number, which is the database ID for a tune. This marks the beginning of a 'tune block', which will be replaced by a suitable picture of the tune. This line can optionally be followed by others, which should start with one of the following keywords; anything not recognised will be dropped, with a warning message. The block ends with the next empty line, and anything within it affects only that image of the tune :-
• %%Transpose: [number] - transpose the tune 'value' semitones up (or down, for negative numbers) from the version in the database.
• %%Leadin: [number] - the number of bars to show for this tune when displaying the document as a leadin sheet.
• %%Hidegraces: 0 or 1 - Show the tune without, or with, any grace notes.
• %%Allowbreak: 0 or 1 - By default, a tune will start at the top of the next page if it won't fit on the current one. %%Allowbreak:1 causes it to start immediately below the previous tune and flow onto the next page where necessary. N.B. - This breaks in the the presence of various forms of textual markings in the music (tempo (Q:), part markers (P:), and probably others I haven't seen yet. This doesn't work in abc2mtex
• Field values can also be supplied for any of the tune keys - these will override the original value.
The text block :-
Everything that isn't part of a tune, as described above, is a block of text. This can contain anything you want, including formatting commands for whichever typesetting program you've chosen. There are also some things that have special meaning here and will be applied to all styles of typesetting.
• %%newpage This is a formatting command. A pagebreak is inserted at this point in the document, by generating whatever magic words are necessary for your choice of typesetter. NB - some of the typesetters use other commands ("\newpage") to insert a pagebreak - it is recommended to use "%%newpage" instead, and the processing here will generate whatever's appropriate. If leadin sheets print with one line per page, this is likely to be because you have spurious "\newpage" commands.
• %%settitle:[title] - group the following tunes together, and give that group a title. This provides display/structuring clues for the front-end website, and can also be used in a table of contents (see below).
• %%endset marks the end of such a group.
• %%tocval:[heading text for a block in the table of contents] See below - this is the marker for an inline table-of-contents heading; it persists until overridden by a subsequent value.
Table of ContentsBoth the simple and LaTeX typesetters offer the fantastically useful option of providing tables of contents, complete with correct page numbers. This is accessed via 'Options' at the top left of the document edit page. Tick the 'Include a table of contents' box, and a suitable table is generated, listing the tunes with their page numbers. They can be listed in page order or sorted by their titles, or by a few other fields :- if your document supplies values for '%%settitle' or '%%tocval', these can be shown insted of the individual tunes; otherwise the tunes' individual titles will be shown.
You have a choice of four :- the default is a simple typesetter that will just print whatever you write; it uses no special commands or magic characters. You can also use the 2 ABC typesetters, abcm2ps and abc2mtex, or LaTeX. See here for the details. [techy note - if you're using LaTeX, your text should not include the terminating '\end', it'll be supplied automatically].
Life gets complicated
Various combinations of tune and document typesetters could happen here.
• When rendering a document with 'simple' or 'latex' - these don't understand ABC, so the tunes have to be rendered in advance as eps files that can be included.
• When rendering a document with abcm2ps - abcm2ps is the default for tunes, so most of them will expect to be done this way. abcm2ps supports the inclusion of eps files, so any tune requiring to be processed by abc2mtex can be done that way. This works.
• When rendering a document with abc2mtex - abc2mtex can't include eps files, so all tunes have also to be rendered using abc2mtex. Since it doesn't necessarily support the features of many of the tunes here, this may be problematical; it'll just depend on which tunes you include in a document, and whether you're prepared to edit them to suit.