5.4 Texinfo introduction and usage policy

5.4.1 Texinfo introduction

The language is called Texinfo; you can see its manual here:

http://www.gnu.org/software/texinfo/manual/texinfo/

However, you don’t need to read those docs. The most important thing to notice is that text is text. If you see a mistake in the text, you can fix it. If you want to change the order of something, you can cut-and-paste that stuff into a new location.

5.4.2 Documentation files

All manuals live in ‘Documentation/’.

In particular, there are four user manuals, their respective master source files are ‘learning.tely’ (LM, Learning Manual), ‘notation.tely’ (NR, Notation Reference), ‘music-glossary.tely’ (MG, Music Glossary), and ‘lilypond-program’ (AU). Each chapter is written in a separate file, ending in ‘.itely’ for files containing lilypond code, and ‘.itexi’ for files without lilypond code, located in a subdirectory associated to the manual (‘learning/’ for ‘learning.tely’, and so on); list the subdirectory of each manual to determine the filename of the specific chapter you wish to modify.

Developer manuals live in ‘Documentation/’ too. Currently there is only one: the Contributor’s Guide ‘contrib-guide.texi’ you are reading.

Snippet files are part of documentation, and the Snippet List (SL) lives in ‘Documentation/’ just like the manuals. For information about how to modify the snippet files and SL, see LSR work.

5.4.3 Sectioning commands

The Notation Reference uses section headings at four, occasionally five, levels.

• Level 1: @chapter
• Level 2: @section
• Level 3: @subsection
• Level 4: @unnumberedsubsubsec
• Level 5: @subsubsubheading

The first three levels are numbered in HTML, the last two are not. Numbered sections correspond to a single HTML page in the split HTML documents.

The first four levels always have accompanying nodes so they can be referenced and are also included in the ToC in HTML.

Most of the manual is written at level 4 under headings created with

@node Foo
@unnumberedsubsubsec Foo

Level 3 subsections are created with

@node Foo
@subsection Foo

Level 4 headings and menus must be preceded by level 3 headings and menus, and so on for level 3 and level 2. If this is not what is wanted, please use:

@subsubsubheading Foo

Please leave two blank lines above a @node; this makes it easier to find sections in texinfo.

Do not use any @ commands for a @node. They may be used for any @sub... sections or headings however.

not:
@node @code{Foo} Bar
@subsection @code{Foo} Bar

but instead:
@node Foo Bar
@subsection @code{Foo} Bar

No punctuation may be used in the node names. If the heading text uses punctuation (in particular, colons and commas) simply leave this out of the node name and menu.

@menu
* Foo Bar::
@end menu

@node Foo Bar
@subsection Foo: Bar

Backslashes must not be used in node names or section headings. If the heading text should include a backslash simply leave this out of the node name and menu and replace it with @bs{} in the heading text.

@menu
* The set command
@end menu

@node The set command
@subsection The @code{@bs{}set} command

References to such a node may use the third argument of the @ref command to display the texually correct heading.

@ref{The set command,,The @code{@bs{}set command}

With the exception of @ commands, \ commands and punctuation, the section name should match the node name exactly.

Sectioning commands (@node and @section) must not appear inside an @ignore. Separate those commands with a space, ie @n ode.

Nodes must be included inside a

@menu
* foo::
* bar::
@end menu

construct. These can be constructed with scripts: see Stripping whitespace and generating menus.

5.4.4 LilyPond formatting

• Most LilyPond examples throughout the documentation can be produced with:

  @lilypond[verbatim,quote]

  If using \book{} in your example then you must also include the papersize=X variable, where X is a defined paper size from within ‘scm/paper.scm’. This is to avoid the default a4 paper size being used and leaving too much unnecessary whitespace and potentially awkward page breaks in the PDFs.

  The preferred papersizes are a5, a6 or a8landscape.

  a8landscape works best for a single measure with a single title and/or single tagline:

  @lilypond[papersize=a8landscape,verbatim] \book { \header { title = "A scale in LilyPond" } \relative { c d e f } } @end lilypond

  and can also be used to easily show features that require page breaks (i.e. page numbers) without taking large amounts of space within the documentation. Do not use the quote option with this paper size.

  a5 or a6 paper sizes are best used for examples that have more than two measures of music or require multiple staves (i.e. to illustrate cross-staff features, RH and LH parts etc.) and where \book{} constructions are required or where a8landscape produces an example that is too cramped. Depending on the example the quote option may need to be omitted.

  In rare cases, other options may be used (or omitted), but ask first.

• Please avoid using extra spacing either after or within the @lilypond parameters.

  not: @lilypond [verbatim, quote, fragment] but instead: @lilypond[verbatim,quote,fragment]

• Inspirational headwords are produced with:

  @lilypondfile[quote,ragged-right,line-width=16\cm,staffsize=16] {pitches-headword.ly}

• LSR snippets are linked with:

  @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle] {filename.ly}

• Use two spaces for indentation in lilypond examples (no tabs).
• All engravers should have double-quotes around them:

  \consists "Spans_arpeggio_engraver"

  LilyPond does not strictly require this, but it is a useful convention to follow.

• Try to avoid using #' or #` when describing context or layout properties outside of an @example or @lilypond, unless the description explicitly requires it.

  i.e. “...setting the transparent property leaves the object where it is, but makes it invisible.”

• If possible, only write one bar per line.
• If you only have one bar per line, omit bar checks. If you must put more than one bar per line (not recommended), then include bar checks.
• Tweaks should, if possible, also occur on their own line.

  not: \override TextScript.padding = #3 c1^"hi" but instead: \override TextScript.padding = #3 c1^"hi"

  excepted in Templates, where ‘doctitle’ may be omitted.

• Avoid long stretches of input code. Nobody is going to read them in print. Create small examples. However, this does not mean it has be minimal.
• Specify durations for at least the first note of every bar.
• If possible, end with a complete bar.
• Comments should go on their own line, and be placed before the line(s) to which they refer.
• For clarity, always use { } marks even if they are not technically required; i.e.

  not: \context Voice \repeat unfold 2 \relative c' { c2 d } but instead: \context Voice { \repeat unfold 2 { \relative c' { c2 d } } }

• Add a space around { } marks; i.e.

  not: \chordmode{c e g} but instead: \chordmode { c e g }

• Use { } marks for additional \markup format commands; i.e.

  not: c^\markup \tiny\sharp but instead: c^\markup { \tiny \sharp }

• Remove any space around < > marks; i.e.

  not: < c e g > 4 but instead: <c e g>4

• Beam, slur and tie marks should begin immediately after the first note with beam and phrase marks ending immediately after the last.

  a8\( ais16[ b cis( d] b) cis4~ b' cis,\)

• If you want to work on an example outside of the manual (for easier/faster processing), use this header:

  \paper { indent = 0\mm line-width = 160\mm - 2.0 * 0.4\in line-width = #(- line-width (* mm 3.000000)) } \layout { }

  You may not change any of these values. If you are making an example demonstrating special \paper{} values, contact the Documentation Editor.

5.4.5 Text formatting

• Lines should be less than 72 characters long. (We personally recommend writing with 66-char lines, but do not bother modifying existing material). Also see the recommendations for fixed-width fonts in the Syntax survey.
• Do not use tabs.
• Do not use spaces at the beginning of a line (except in @example or @verbatim environments), and do not use more than a single space between words. ‘makeinfo’ copies the input lines verbatim without removing those spaces.
• Use two spaces after a period.
• In examples of syntax, use @var{musicexpr} for a music expression.
• Don’t use @rinternals{} in the main text. If you’re tempted to do so, you’re probably getting too close to “talking through the code”. If you really want to refer to a context, use @code{} in the main text and @rinternals{} in the @morerefs.

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

(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’

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

5.4.7 Other text concerns

• References must occur at the end of a sentence, for more information see the texinfo manual. Ideally this should also be the final sentence of a paragraph, but this is not required. Any link in a doc section must be duplicated in the @morerefs section at the bottom.
• Introducing examples must be done with

  . (i.e. finish the previous sentence/paragraph) : (i.e. `in this example:') , (i.e. `may add foo with the blah construct,')

  The old “sentence runs directly into the example” method is not allowed any more.

• Abbrevs in caps, e.g., HTML, DVI, MIDI, etc.
• Colon usage
  1. To introduce lists
  2. When beginning a quote: “So, he said,...”.

     This usage is rarer. Americans often just use a comma.

  3. When adding a defining example at the end of a sentence.
• Non-ASCII characters which are in utf-8 should be directly used; this is, don’t say ‘Ba@ss{}tuba’ but ‘Baßtuba’. This ensures that all such characters appear in all output formats.

This document was generated by gub on July 13, 2020 using texi2html 1.82.