5.6.1 Working on subsections

In the NR, we highly recommend focusing on one subsection at a time. For each subsection,

• check the mundane formatting. Are the headings (@predefined, @morerefs, etc.) in the right order?
• add any appropriate index entries.
• check the links in the @morerefs section – links to the Music Glossary, the Internals Reference, and other NR sections are the main concern. Check for potential additions.
• move LSR-worthy material into the LSR. Add the snippet, delete the material from the .itely file, and replace it with a @lilypondfile command.
• check the examples and descriptions. Do they still work? Do not assume that the existing text is accurate or complete; some parts of the manual are highly out of date due to the constant lack of manpower.
• is the material in the @knownissues block still accurate?
• can the examples be improved (for example, made more explanatory), or is there any missing information? Feel free to ask specific questions on the lilypond-user mailing list; a couple of people claimed to be interesting in being “consultants” who would help with such questions.

  We favor short text explanations with good examples – “an example is worth a thousand words”. However, producing good, tiny LilyPond examples can be quite time-consuming; making easily-understandable examples is much harder than it looks.

Tweaks

In general, any \set or \override command should go in the “selected snippets” section, which means that they should be added to the LSR and not to the .itely file. For some cases, the command obviously belongs in the “main text” (i.e., not inside @predefined or @morerefs or whatever) – instrument names are a good example of this:

\set Staff.instrumentName = "foo"

On the other side of this,

\override Score.Hairpin.after-line-breaking = ##t

clearly belongs to the LSR.

One place where a documentation writer can profitably spend time writing or upgrading tweaks is creating code to deal with known issues. It would be ideal if every significant known issue had a workaround to avoid the difficulty.

See also

Adding and editing snippets.