5.5 Documentation policy

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

5.5.2 Section organization

• The order of headings inside documentation sections should be:

  main docs @predefined @endpredefined @snippets @morerefs @knownissues

• You must include a @morerefs.
  • The order of items inside the @morerefs section is

    Music Glossary: @rglos{foo}, @rglos{bar}. Learning Manual: @rlearning{baz}, @rlearning{foozle}. Notation Reference: @ruser{faazle}, @ruser{boo}. Application Usage: @rprogram{blah}. Essay on automated music engraving: @ressay{yadda}. Extending LilyPond: @rextend{frob}. 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 @morerefs 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’
• Do not include any real info in second-level sections (i.e. 1.1 Pitches). A first-level section may have introductory material, but other than that all material goes into third-level sections (i.e. 1.1.1 Writing Pitches).
• The @knownissues should not discuss any issues that are in the tracker, unless the issue is Priority-Postponed. The goal is to discuss any overall architecture or syntax decisions which may be interpreted as bugs. Normal bugs should not be discussed here, because we have so many bugs that it would be a huge task to keep the @knownissues current and accurate all the time.

5.5.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 run:

make check-xrefs
make fix-xrefs

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

5.5.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, i.e.

  @cindex time signature

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

• For scheme function index entries, only include the final part, i.e.

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

• Use American spelling. LilyPond’s internal property names use this convention.
• Here is a list of preferred terms to be used:
  • Simultaneous NOT concurrent.
  • Measure: the unit of music.
  • Bar line: the symbol delimiting a measure NOT barline.
  • Note head NOT notehead.
  • Chord construct NOT just chord (when referring to < ... >)
  • Staff NOT stave.
  • Staves NOT Staffs: Phrases such as ‘multiple @internalsref{Staff}s’ should be rephrased to ‘multiple @internalsref{Staff} contexts’.

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

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