| [ << Documentation work ] | [Top][Contents] | [ Website work >> ] |
| [ < Text formatting ] | [ Up : Texinfo introduction and usage policy ] | [ Comments > ] |
5.4.6 Syntax survey
| Comments | ||
| Cross references | ||
| External links | ||
| Fixed-width font | ||
| Indexing | ||
| Lists | ||
| Special characters | ||
| Miscellany |
| [ << Documentation work ] | [Top][Contents] | [ 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] | [ 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] | [ Website work >> ] |
| [ < Cross references ] | [ Up : Syntax survey ] | [ Fixed-width font > ] |
External links
-
@email{…}— create amailto: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] | [ 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@itemby 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@exampleblock, and do not use either as a free-standing paragraph; use@exampleinstead.A single unindented line in the PDF has space for about 79 fixed-width characters (76 if indented). Within an
@itemthere is space for about 75 fixed-width characters. Each additional level of@itemizeor@enumerateshortens 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
@allowcodebreaksis set tofalsein 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
txicodequoteundirectedandtxicodequotebacktickare both set in the manuals, so backticks (`) and apostrophes (') placed within blocks of@code,@example, or@verbatimare 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@sampblock (even if it includes a nested@codeblock), 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@exampleblock. -
@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@noindentif 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
@exampleblock should not exceed 74 characters; otherwise they will run into the margin in the PDF output, and may get clipped. If an@exampleblock is part of an@item, individual lines in the@exampleblock should not exceed 70 columns. Each additional level of@itemizeor@enumerateshortens 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
@examplewhenever possible, but if needed,@smallexamplecan fit up to 90 characters per line before running into the PDF margin. Each additional level of@itemizeor@enumerateshortens a@smallexampleline by about 5 columns. -
@file{…}— Use when referring to filenames and directories in the text. Do not use inside an@exampleblock. -
@option{…}— Use when referring to command-line options in the text (eg. ‘@option{--format}’). Do not use inside an@exampleblock. -
@verbatim— Prints the block exactly as it appears in the source file (including whitespace, etc.). For program code examples, use@exampleinstead.@verbatimuses the same format as@example.Individual lines within an
@verbatimblock should not exceed 74 characters; otherwise they will run into the margin in the PDF output, and may get clipped. If an@verbatimblock is part of an@item, individual lines in the@verbatimblock should not exceed 70 columns. Each additional level of@itemizeor@enumerateshortens the line by about 4 columns.
| [ << Documentation work ] | [Top][Contents] | [ 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] | [ 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] | [ 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] | [ 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 asfoo,bar,arg1, etc.). In most cases, when the@var{…}command appears in the text (and not in an@exampleblock) 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] | [ Website work >> ] |
| [ < Special characters ] | [ Up : Syntax survey ] | [ Other text concerns > ] |