in the Music Glossary.
-* Program Usage: information about using the program lilypond with
- other programs (lilypond-book, operating systems, GUIs,
+* 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.
+* Internals Reference: not really a documentation book, since it
+ is automagically generated from the source, but this is its
+ name.
+
%%%%% SECTION ORGANIZATION
The order of headings inside documentation sections should be:
main docs
+@refcommands
@commonprop
@seealso
@refbugs
Music glossary: @rglos{foo}, @rglos{bar}.
- User manual: @ref{baz}, @ref{foozle}.
+ Learning Manual: @rlearning{baz}, @rlearning{foozle}
+
+ Notation Reference: @ruser{faazle}, @ruser{boo}.
+
+ Application Usage: @rprogram{blah}.
+
+ Installed files: @file{blahz}.
- Snippets: @lsrdir{section}.
+ Snippets: @lsrdir{section}, @lsr{specific/example-name.ly}.
+ (if there is only one entry, omit a final period. If there
+ are multiple entries, separate them by commas, do not
+ include an `and', and end with a period.)
- Program reference: @internalsref{fazzle}, @internalsref{booar}.
+ Internals Reference: @internalsref{fazzle}, @internalsref{booar}.
("Snippets" is REQUIRED; the others are optional)
* To create links, use @ref{} if the link is within the same
- manual. If you are linking to another manual (say,
- learning->glossary or user->program usage), then use:
- @rlearning{}
- @ruser{}
- @rprogram{}
- @rglos{}
- @internalsref{}
+ manual.
* @commonprop and @refbugs are optional.
* Specially-marked text:
@code{}: actual lilypond code or property/context names.
- @samp{}: ditto, for single-letter code.
** Any `\' used inside the commands below must be **
@warning{}: produces a "Note: " box. Use for important
messages.
+* References must occur at the end of a sentence, for more
+ information see @ref{the texinfo manual}. Ideally this should
+ also be the final sentence of a paragraph, but this is not
+ required. Any link in a doc section must be duplicated in the
+ @seealso section at the bottom.
+
+* Introducing examples may be done with
+ . (ie finish the previous sentence/paragaph)
+ : (ie `in this example:')
+ , (ie `may add foo with the blah construct,')
+
%%%%% READABILITY
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.
+
* Abbrevs in caps, e.g., HTML, DVI, MIDI, etc.
* Colon usage