[ << Documentation work ] | [Top][Contents][Index][ ? ] | [ Website work >> ] | ||
[ < Books ] | [ Up : Documentation policy ] | [ Checking cross-references > ] |
4.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}. 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 @seealso and the first entry! Otherwise there is excessive vertical space in the PDF output.
-
The order of items inside the @seealso section is
- 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 (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).
[ << Documentation work ] | [Top][Contents][Index][ ? ] | [ Website work >> ] | ||
[ < Books ] | [ Up : Documentation policy ] | [ Checking cross-references > ] |