* Music Glossary: information about the music notation itself.
- Explainations and translations about notation terms go here.
+ Explanations and translations about notation terms go here.
Users are not expected to read this manual from start to finish.
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}.
+ Music Glossary:
+ @rglos{foo},
+ @rglos{bar}.
- Learning Manual: @rlearning{baz}, @rlearning{foozle}
+ Learning Manual:
+ @rlearning{baz},
+ @rlearning{foozle}.
- Notation Reference: @ruser{faazle}, @ruser{boo}.
+ Notation Reference:
+ @ruser{faazle},
+ @ruser{boo}.
- Application Usage: @rprogram{blah}.
+ Application Usage:
+ @rprogram{blah}.
- Installed Files: @file{path/to/dir/blahz}.
+ Installed Files:
+ @file{path/to/dir/blahz}.
- 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.)
+ Snippets: @rlsr{section}.
- Internals Reference: @internalsref{fazzle}, @internalsref{booar}.
+ 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.
+
* To create links, use @ref{} if the link is within the same
manual.
+* @predefined ... @endpredefined is for commands in ly/*-init.ly
+ FIXME?
+
* 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).
+%%%%% CHECKING CROSS-REFERENCES
+
+Cross-references between different manuals are heavily used in the
+documentation, but they are not checked during compilation. However,
+if you compile the documentation, a script called check_texi_refs can
+help you with checking and fixing these cross-references; for
+information on usage, cd into a source tree where documentation has
+been built, cd into Documentation and look for check-xrefs and
+fix-xrefs targets in 'make help' output. Note that you have to find
+yourself the source files to fix cross-references in the generated
+documentation such as the Internals Reference; e.g. you can grep
+scm/ and lily/.
+
+
%%%%% GENERAL WRITING
* Do not forget to create @cindex entries for new sections of text.
is preferred. (instead of `Time signature') Only use capital
letters for musical terms which demand them, like D.S. al Fine.
+ For scheme functions, only include the final part, ie
+ @funindex modern-voice-cautionary
+ and NOT
+ @funindex #(set-accidental-style modern-voice-cautionary)
+
* Preferred terms:
- in general, use the American spellings. The internal
lilypond property names use this spelling.
measure: the unit of music
bar line: the symbol delimiting a measure NOT barline
note head NOT notehead
+chord construct NOT chord (when referring to <>)
%%%%% TECHNICAL WRITING STYLE