LilyPond Contributor's Guide: 5.4.6 Syntax survey

[ << Documentation work ]	[Top][Contents][Index][ ? ]			[ Website work >> ]
[ < Text formatting ]		[ Up : Texinfo introduction and usage policy ]	[ Comments > ]

5.4.6 Syntax survey

[ << Documentation work ]	[Top][Contents][Index][ ? ]			[ Website work >> ]
[ < Syntax survey ]		[ Up : Syntax survey ]	[ Cross references > ]

Comments

@c … — single line comment. ‘@c NOTE:’ is a comment which should remain in the final version. (gp only command ;)
@ignore — multi-line comment:
```
@ignore
…
@end ignore
```

[ << Documentation work ]	[Top][Contents][Index][ ? ]			[ Website work >> ]
[ < Comments ]		[ Up : Syntax survey ]	[ External links > ]

Cross references

Enter the exact @node name of the target reference between the brackets (eg. ‘@ref{Syntax survey}’). Do not split a cross-reference across two lines – this causes the cross-reference to be rendered incorrectly in HTML documents.

@ref{…} — link within current manual.
@rchanges{…} — link to Changes.
@rcontrib{…} — link to Contributor’s Guide.
@ressay{…} — link to Engraving Essay.
@rextend{…} — link to Extending LilyPond.
@rglos{…} — link to the Music Glossary.
@rinternals{…} — link to the Internals Reference.
@rlearning{…} — link to Learning Manual.
@rlsr{…} — link to a Snippet section.
@rprogram{…} — link to Application Usage.
@ruser{…} — link to Notation Reference.
@rweb{…} — link to General Information.

[ << Documentation work ]	[Top][Contents][Index][ ? ]			[ Website work >> ]
[ < Cross references ]		[ Up : Syntax survey ]	[ Fixed-width font > ]

External links

@email{…} — create a mailto: E-mail link.
@uref{URL[, link text]} — link to an external url. Use within an @example ... @end example.
```
@example
@uref{URL [, link text ]}
@end example
```

[ << Documentation work ]	[Top][Contents][Index][ ? ]			[ Website work >> ]
[ < External links ]		[ Up : Syntax survey ]	[ Indexing > ]

Fixed-width font

@code{…}, @samp{…} —
Use the @code{…} command when referring to individual language-specific tokens (keywords, commands, engravers, scheme symbols, etc.) in the text. Ideally, a single @code{…} block should fit within one line in the PDF output.

Use the @samp{…} command when you have a short example of user input, unless it constitutes an entire @item by itself, in which case @code{…} is preferable. Otherwise, both should only be used when part of a larger sentence within a paragraph or @item. Do not use @code{…} or @samp{…} inside an @example block, and do not use either as a free-standing paragraph; use @example instead.

A single unindented line in the PDF has space for about 79 fixed-width characters (76 if indented). Within an @item there is space for about 75 fixed-width characters. Each additional level of @itemize or @enumerate shortens the line by about 4 columns.

However, even short blocks of @code{…} and @samp{…} can run into the margin if the Texinfo line-breaking algorithm gets confused. Additionally, blocks that are longer than this may in fact print nicely; it all depends where the line breaks end up. If you compile the docs yourself, check the PDF output to make sure the line breaks are satisfactory.

The Texinfo setting @allowcodebreaks is set to false in the manuals, so lines within @code{…} or @samp{…} blocks will only break at spaces, not at hyphens or underscores. If the block contains spaces, use @w{@code{…}} or @w{@samp{…}} to prevent unexpected line breaks.

The Texinfo settings txicodequoteundirected and txicodequotebacktick are both set in the manuals, so backticks (`) and apostrophes (') placed within blocks of @code, @example, or @verbatim are not converted to left- and right-angled quotes (‘ ’) as they normally are within the text, so the apostrophes in ‘@w{@code{\relative c''}}’ will display correctly. However, these settings do not affect the PDF output for anything within a @samp block (even if it includes a nested @code block), so entering ‘@w{@samp{\relative c''}}’ wrongly produces ‘\relative c’’’ in PDF. Consequently, if you want to use a @samp{…} block which contains backticks or apostrophes, you should instead use ‘@q{@code{…}}’ (or ‘@q{@w{@code{…}}}’ if the block also contains spaces). Note that backslashes within @q{…} blocks must be entered as ‘@bs{}’, so the example above would be coded as ‘@q{@w{@code{@bs{}relative c''}}}’.
@command{…} — Use when referring to command-line commands within the text (eg. ‘@command{convert-ly}’). Do not use inside an @example block.
@example — Use for examples of program code. Do not add extraneous indentation (i.e. don’t start every line with whitespace). Use the following layout (notice the use of blank lines). Omit the @noindent if the text following the example starts a new paragraph:
```
…text leading into the example…

@example
…
@end example

@noindent
continuation of the text…
```
Individual lines within an @example block should not exceed 74 characters; otherwise they will run into the margin in the PDF output, and may get clipped. If an @example block is part of an @item, individual lines in the @example block should not exceed 70 columns. Each additional level of @itemize or @enumerate shortens the line by about 4 columns.

For long command line examples, if possible, use a trailing backslash to break up a single line, indenting the next line with 2 spaces. If this isn’t feasible, use ‘@smallexample … @end smallexample’ instead, which uses a smaller fontsize. Use @example whenever possible, but if needed, @smallexample can fit up to 90 characters per line before running into the PDF margin. Each additional level of @itemize or @enumerate shortens a @smallexample line by about 5 columns.
@file{…} — Use when referring to filenames and directories in the text. Do not use inside an @example block.
@option{…} — Use when referring to command-line options in the text (eg. ‘@option{--format}’). Do not use inside an @example block.
@verbatim — Prints the block exactly as it appears in the source file (including whitespace, etc.). For program code examples, use @example instead. @verbatim uses the same format as @example.
Individual lines within an @verbatim block should not exceed 74 characters; otherwise they will run into the margin in the PDF output, and may get clipped. If an @verbatim block is part of an @item, individual lines in the @verbatim block should not exceed 70 columns. Each additional level of @itemize or @enumerate shortens the line by about 4 columns.

[ << Documentation work ]	[Top][Contents][Index][ ? ]			[ Website work >> ]
[ < Fixed-width font ]		[ Up : Syntax survey ]	[ Lists > ]

Indexing

@cindex … — General index. Please add as many as you can. Don’t capitalize the first word.
@funindex … — is for a \lilycommand.

[ << Documentation work ]	[Top][Contents][Index][ ? ]			[ Website work >> ]
[ < Indexing ]		[ Up : Syntax survey ]	[ Special characters > ]

Lists

@enumerate — Create an ordered list (with numbers). Always put ‘@item’ on its own line. As an exception, if all the items in the list are short enough to fit on single lines, placing them on the ‘@item’ lines is also permissible. ‘@item’ and ‘@end enumerate’ should always be preceded by a blank line.
```
@enumerate

@item
A long multi-line item like this one must begin
on a line of its own and all the other items in
the list must do so too.

@item
Even short ones

@end enumerate
```
```
@enumerate

@item Short item

@item Short item

@end enumerate
```
@itemize — Create an unordered list (with bullets). Use the same format as @enumerate. Do not use ‘@itemize @bullet’.

[ << Documentation work ]	[Top][Contents][Index][ ? ]			[ Website work >> ]
[ < Lists ]		[ Up : Syntax survey ]	[ Miscellany > ]

Special characters

Note: In Texinfo, the backslash is an ordinary character, and is entered without escaping (e.g. ‘The @code{\foo} command’). However, within double-quoted Scheme and/or LilyPond strings, backslashes (including those ending up in Texinfo markup) need to be escaped by doubling them:

(define (foo x)
  "The @code{\\foo} command..."
  ...)

--, --- — Create an en dash (–) or an em dash (—) in the text. To print two or three literal hyphens in a row, wrap one of them in a @w{…} (eg. ‘-@w{-}-’).
@@, @{, @} — Create an at-sign (@), a left curly bracket ({), or a right curly bracket (}).
@bs{} — Create a backslash within a @q{…}, @qq{…}, or @warning{…} block. This is a custom LilyPond macro, not a builtin @-command in Texinfo. Texinfo would also allow ‘\\’, but this breaks the PDF output.
@tie{} — Create a variable-width non-breaking space in the text (use ‘@w{ }’ for a single fixed-width non-breaking space). Variables or numbers which consist of a single character (probably followed by a punctuation mark) should be tied properly, either to the previous or the next word. Example: ‘The letter@tie{}@q{I} is skipped’

[ << Documentation work ]	[Top][Contents][Index][ ? ]			[ Website work >> ]
[ < Special characters ]		[ Up : Syntax survey ]	[ Other text concerns > ]

Miscellany

@notation{…} — refers to pieces of notation, e.g. ‘@notation{clef}’. Also use for specific lyrics (‘the @notation{A - men} is centered’). Only use once per subsection per term.
@q{…} — Single quotes. Used for ‘vague’ terms. To get a backslash (\), you must use ‘@bs{}’.
@qq{…} — Double quotes. Used for actual quotes (“he said”) or for introducing special input modes. To get a backslash (\), you must use ‘@bs{}’.
@var{…} — Use for metasyntactic variables (such as foo, bar, arg1, etc.). In most cases, when the @var{…} command appears in the text (and not in an @example block) it should be wrapped with an appropriate texinfo code-highlighting command (such as @code, @samp, @file, @command, etc.). For example: ‘@code{@var{foo}}’, ‘@file{@var{myfile.ly}}’, ‘@samp{git checkout @var{branch}}’, etc. This improves readability in the PDF and HTML output.
@version{} — Return the current LilyPond version string. Use ‘@w{@version{}}’ if it’s at the end of a line (to prevent an ugly line break in PDF); use ‘@w{"@version{}"}’ if you need it in quotes.
@w{…} — Do not allow any line breaks.
@warning{…} — produces a “Note: ” box. Use for important messages. To get a backslash (\), you must use ‘@bs{}’.

[ << Documentation work ]	[Top][Contents][Index][ ? ]			[ Website work >> ]
[ < Special characters ]		[ Up : Syntax survey ]	[ Other text concerns > ]