GNU LilyPond Contributor's Guide: 3.4 Documentation policy

## 3.4 Documentation policy

### 3.4.1 Books

There are four parts to the documentation: the Learning Manual, the Notation Reference, the Program Reference, and the Music Glossary.

- Learning Manual:

  The LM is written in a tutorial style which introduces the most important concepts, structure and syntax of the elements of a LilyPond score in a carefully graded sequence of steps. Explanations of all musical concepts used in the Manual can be found in the Music Glossary, and readers are assumed to have no prior knowledge of LilyPond. The objective is to take readers to a level where the Notation Reference can be understood and employed to both adapt the templates in the Appendix to their needs and to begin to construct their own scores. Commonly used tweaks are introduced and explained. Examples are provided throughout which, while being focussed on the topic being introduced, are long enough to seem real in order to retain the readers’ interest. Each example builds on the previous material, and comments are used liberally. Every new aspect is thoroughly explained before it is used.

  Users are encouraged to read the complete Learning Manual from start-to-finish.

- Notation Reference: a (hopefully complete) description of LilyPond input notation. Some material from here may be duplicated in the Learning Manual (for teaching), but consider the NR to be the "definitive" description of each notation element, with the LM being an "extra". The goal is _not_ to provide a step-by-step learning environment – do not avoid using notation that has not be introduced previously in the NR (for example, use \break if appropriate). This section is written in formal technical writing style.

  Avoid duplication. Although users are not expected to read this manual from start to finish, they should be familiar with the material in the Learning Manual (particularly “Fundamental Concepts”), so do not repeat that material in each section of this book. Also watch out for common constructs, like ^ - _ for directions – those are explained in NR 3. In NR 1, you can write: DYNAMICS may be manually placed above or below the staff, see @ref{Controlling direction and placement}.

  Most tweaks should be added to LSR and not placed directly in the .itely file. In some cases, tweaks may be placed in the main text, but ask about this first.

  Finally, you should assume that users know what the notation means; explaining musical concepts happens in the Music Glossary.

- Application Usage: information about using the program lilypond with other programs (lilypond-book, operating systems, GUIs, convert-ly, etc). This section is written in formal technical writing style.

  Users are not expected to read this manual from start to finish.

- Music Glossary: information about the music notation itself. Explanations and translations about notation terms go here.

  Users are not expected to read this manual from start to finish.

- Internals Reference: not really a documentation book, since it is automagically generated from the source, but this is its name.

### 3.4.2 Section organization

- The order of headings inside documentation sections should be:

  >     main docs
  >     @predefined
  >     @endpredefined
  >     @snippets
  >     @seealso
  >     @knownissues

- You must include a @seealso.
  - The order of items inside the @seealso section is

    >     Music Glossary:
    >     @rglos{foo},
    >     @rglos{bar}.

    >     Learning Manual:
    >     @rlearning{baz},
    >     @rlearning{foozle}.

    >     Notation Reference:
    >     @ruser{faazle},
    >     @ruser{boo}.

    >     Application Usage:
    >     @rprogram{blah}.

    >     Installed Files:
    >     @file{path/to/dir/blahz}.

    >     Snippets: @rlsr{section}.

    >     Internals Reference:
    >     @rinternals{fazzle},
    >     @rinternals{booar}.

  - If there are multiple entries, separate them by commas but do not include an ‘and’.
  - Always end with a period.
  - Place each link on a new line as above; this makes it much easier to add or remove links. In the output, they appear on a single line.

    ("Snippets" is REQUIRED; the others are optional)

  - Any new concepts or links which require an explanation should go as a full sentence(s) in the main text.
  - Don’t insert an empty line between @seealso and the first entry! Otherwise there is excessive vertical space in the PDF output.
- To create links, use @ref{} if the link is within the same manual.
- @predefined ... @endpredefined is for commands in ly/*-init.ly FIXME?
- Do not include any real info in second-level sections (ie 1.1 Pitches). A first-level section may have introductory material, but other than that all material goes into third-level sections (ie 1.1.1 Writing Pitches).

### 3.4.3 Checking cross-references

Cross-references between different manuals are heavily used in the documentation, but they are not checked during compilation. However, if you compile the documentation, a script called check_texi_refs can help you with checking and fixing these cross-references; for information on usage, cd into a source tree where documentation has been built, cd into Documentation and look for check-xrefs and fix-xrefs targets in ’make help’ output. Note that you have to find yourself the source files to fix cross-references in the generated documentation such as the Internals Reference; e.g. you can grep scm/ and lily/.

### 3.4.4 General writing

- Do not forget to create @cindex entries for new sections of text. Enter commands with @funindex, i.e.

  >     @cindex pitches, writing in different octaves
  >     @funindex \relative

  do not bother with the @code{} (they are added automatically). These items are added to both the command index and the unified index.

  Both index commands should go in front of the actual material.

  @cindex entries should not be capitalized, ie

  >     @cindex time signature

  is preferred instead of “Time signature”, Only use capital letters for musical terms which demand them, like D.S. al Fine.

  For scheme functions, only include the final part, i.e.,

  >     @funindex modern-voice-cautionary
  >          and NOT
  >     @funindex #(set-accidental-style modern-voice-cautionary)

- Preferred terms:
  - In general, use the American spellings. The internal lilypond property names use this spelling.
  - List of specific terms:

    >     canceled
    >     simultaneous    NOT concurrent
    >     measure: the unit of music
    >     bar line: the symbol delimiting a measure   NOT barline
    >     note head   NOT notehead
    >     chord construct   NOT chord (when referring to <>)

### 3.4.5 Technical writing style

These refer to the NR. The LM uses a more gentle, colloquial style.

- Do not refer to LilyPond in the text. The reader knows what the manual is about. If you do, capitalization is LilyPond.
- If you explicitly refer to ‘lilypond’ the program (or any other command to be executed), write `@command{lilypond}`.
- Do not explicitly refer to the reader/user. There is no one else besides the reader and the writer.
- Avoid contractions (don’t, won’t, etc.). Spell the words out completely.
- Avoid abbreviations, except for commonly used abbreviations of foreign language terms such as etc. and i.e.
- Avoid fluff (“Notice that,” “as you can see,” “Currently,”).
- The use of the word ‘illegal’ is inappropriate in most cases. Say ‘invalid’ instead.

#### Contributor’s Guide