5.5.2 Section organization

• The order of headings inside documentation sections should be:

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

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

    Music Glossary:
    @rglos{foo},
    @rglos{bar}.
    
    Learning Manual:
    @rlearning{baz},
    @rlearning{foozle}.
    
    Notation Reference:
    @rnotation{faazle},
    @rnotation{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.