5.5.2 Section organization

• The order of headings inside documentation sections should be:

  documentation text
  
  @predefined
  @endpredefined
  
  @snippets
  
  @morerefs
  @endmorerefs
  
  @knownissues
  

• You must include a @morerefs … @endmorerefs block.
  • − The order of items inside the @morerefs block 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 only and do not use the word ‘and’. If there are no references to a specific manual, omit it.
  • − 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.
  • − Any new concepts or links which require an explanation should appear 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.
• Use @ref{...} instead of the abovementioned reference commands if the link is within the same manual.
• @predefined … @endpredefined is for commands defined in files ly/*-init.ly.
• Do not include any real information in second-level sections (for example, ‘1.1 Pitches’). A first-level section may have introductory material, but other than that all material goes into third-level sections (for example, ‘1.1.1 Writing Pitches’).
• The @knownissues part should usually not describe any issues that are in LilyPond’s bug tracker. The goal is rather 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 of them that it would be a huge task to keep @knownissues current and accurate all the time.