LilyPond Contributor's Guide: 5.3.6 Syntax survey

### 5.3.6 Syntax survey

#### 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

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

#### 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

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

#### Indexing

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

#### 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`’.

#### Special characters

- `--`, `---` — 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`’

#### 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{}`’.

#### LilyPond — Contributor’s Guide