GNU LilyPond Contributor's Guide: 3.3 Texinfo introduction and usage policy

## 3.3 Texinfo introduction and usage policy

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

Note: Rule of thumb: follow the examples in the existing docs. You can learn most of what you need to know from this; if you want to do anything fancy, discuss it on `lilypond-devel` first.

### 3.3.2 Documentation files

The user manuals lives in ‘`Documentation/user/`’. In particular, the files ‘`lilypond-learning.ly`’ (LM), ‘`lilypond.itely`’ (NR), ‘`music-glossary.tely`’ (MG), 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); see the “main” file for each manual to determine the filename of the specific chapter you wish to modify.

Developer manuals live in ‘`Documentation/devel`’. Currently there is only one; ‘`contrib-guide.texi`’.

Although snippets are part of documentation, they are not (directly) part of the manuals. For information about how to modify them, see LSR work.

### 3.3.3 Sectioning commands

Most of the manual operates at the

>     @node Foo
>     @subsubsection Foo

level. Sections are created with

>     @node Foo
>     @subsection Foo

- Please leave two blank lines above a @node; this makes it easier to find sections in texinfo.
- Sectioning commands (@node and @section) must not appear inside an @ignore. Separate those commands with a space, ie @n ode.

### 3.3.4 LilyPond formatting

- Use two spaces for indentation in lilypond examples. (no tabs)
- All text strings should be prefaced with #. LilyPond does not strictly require this, but it is helpful to get users accustomed to this scheme construct. ie `\set Staff.instrumentName = #"cello"`
- All engravers should have double-quotes around them:

  >     \consists "Spans_arpeggio_engraver"

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

- Examples should end with a complete bar if possible.
- If possible, only write one bar per line. The notes on each line should be an independent line – tweaks should occur on their own line if possible. Bad:

  >     \override textscript #'padding = #3 c1^"hi"

  Good:

  >     \override textscript #'padding = #3
  >     c1^"hi"

- Most LilyPond input should be produced with:

  >     @lilypond[verbatim,quote,relative=2]

  or

  >     @lilypond[verbatim,quote,relative=1]

  If you want to use \layout{} or define variables, use

  >     @lilypond[verbatim,quote]

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

- 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,lilyquote,ragged-right,texidoc,doctitle]
  >     {filename.ly}

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

- Avoid long stretches of input code. Noone is going to read them in print. Please create a smaller example. (the smaller example does not need to be minimal, however)
- 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.
- Add extra spaces around { } marks; ie

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

- If you only have one bar per line, omit bar checks. If you put more than one bar per line (not recommended), then include bar checks.
- If you want to work on an example outside of the manual (for easier/faster processing), use this header:

  >     \paper {
  >       #(define dump-extents #t)
  >       indent = 0\mm
  >       line-width = 160\mm - 2.0 * 0.4\in
  >       ragged-right = ##t
  >       force-assignment = #""
  >       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.

### 3.3.5 Text formatting

- Lines should be less than 72 characters long. (I personally recommend writing with 66-char lines, but don’t bother modifying existing material.)
- 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 @seealso.
- 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 variable@tie{}@var{a} ...

- To get consistent indentation in the DVI output it is better to avoid the @verbatim environment. Use the @example environment instead if possible, but without extraneous indentation. For example, this

  >     @example
  >       foo {
  >         bar
  >       }
  >     @end example

  should be replaced with

  >     @example
  >     foo {
  >       bar
  >     }
  >     @end example

  where ‘@example’ starts the line (without leading spaces).

- Do not compress the input vertically; this is, do not use

  >         Beginning of logical unit
  >         @example
  >         ...
  >         @end example
  >         continuation of logical unit

  but instead do

  >     Beginning of logical unit

  >     @example
  >     ...
  >     @end example

  >     @noindent
  >     continuation of logical unit

  This makes it easier to avoid forgetting the ‘@noindent’. Only use @noindent if the material is discussing the same material; new material should simply begin without anything special on the line above it.

- in @itemize use @item on a separate line like this:

  >     @itemize
  >     @item
  >     Foo

  >     @item
  >     Bar

  Do not use @itemize @bullet.

- To get LilyPond version, use @version{} (this does not work inside LilyPond snippets). If you write "@version{}" (enclosed with quotes), or generally if @version{} is not followed by a space, tere will be an ugly line break in PDF output unless you enclose it with

  >     @w{ ... }

  >       e.g.

  >     @w{"@version{}"}

### 3.3.6 Syntax survey

- @c - single line comments "@c NOTE:" is a comment which should remain in the final version. (gp only command ;)
- @ignore ... @end ignore - multi-line comment
- @cindex - General index. Please add as many as you can. Don’t capitalize the first word.
- @funindex - is for a \lilycommand.
- @example ... @end ignore - example text that should be set as a blockquote. Any {} must be escaped with @{ }@
- @itemize @item A @item B ... @end itemize - for bulleted lists. Do not compress vertically like this.
- @code{} - typeset in a tt-font. Use for actual lilypond code or property/context names. If the name contains a space, wrap the entire thing inside @w{@code{ }}.
- @notation{} - refers to pieces of notation, e.g. "@notation{cres.}". Also use to specific lyrics ("the @notation{A - men} is centered"). Only use once per subsection per term.
- @q{} - Single quotes. Used for ‘vague’ terms.
- @qq{} - Double quotes. Used for actual quotes ("he said") or for introducing special input modes.
- @tie{} - 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"
- @var - Use for variables.
- @warning{} - produces a "Note: " box. Use for important messages.
- @bs - Generates a backslash inside @warning. Any ‘\’ used inside @warning (and @q or @qq) must be written as ‘@bs{}’ (texinfo would also allow \\, but this breaks with PDF output).
- @ref{} - normal references (type the exact node name inside the {}).
- @ruser{} - link to the NR.
- @rlearning{} - link to the LM.
- @rglos{} - link to the MG.
- @rprogram{} - link to the AU.
- @rlsr{} - link to a Snippet section.
- @rinternals{} - link to the IR.
- @uref{} - link to an external url.

### 3.3.7 Other text concerns

- References must occur at the end of a sentence, for more information see @ref{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 @seealso section at the bottom.
- Introducing examples must be done with

  >          . (ie finish the previous sentence/paragaph)
  >          : (ie `in this example:')
  >          , (ie `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.

#### Contributor’s Guide