the Notation Reference, the Program Reference, and the Music
Glossary.
-* Learning Manual: long, chatty, friendly explanations go here.
- This is aimed at users learning something for the first time --
- not necessarily just learning lilypond notation, but also things
- like learning how to deal with projects, tweaking, preparing parts
- for orchestras, etc. Less formal language may be used here.
+* Learning Manual:
+ The LM is written in a tutorial style which introduces the most
+ important concepts, structure and syntax of the elements of a
+ LilyPond score in a carefully graded sequence of steps.
+ Explanations of all musical concepts used in the Manual can be
+ found in the Music Glossary, and readers are assumed to have no
+ prior knowledge of LilyPond. The objective is to take readers to
+ a level where the Notation Reference can be understood and
+ employed to both adapt the templates in the Appendix to their
+ needs and to begin to construct their own scores. Commonly used
+ tweaks are introduced and explained. Examples are provided
+ throughout which, while being focussed on the topic being
+ introduced, are long enough to seem real in order to retain the
+ readers' interest. Each example builds on the previous material,
+ and comments are used liberally. Every new aspect is thoroughly
+ explained before it is used.
Users are encouraged to read the complete Learning Manual from
start-to-finish.
* Notation Reference: a (hopefully complete) description of
LilyPond input notation. Some material from here may be
- duplicated in the Learning Manual (for teaching). The material is
- presented in an approximate order of increasing difficulty, but
- the goal is _not_ to provide a step-by-step learning environment.
- For example, all material under "Pitches" should remain in that
- section, even though microtonal accidentals may seem more advanced
- than info about clefs or time signatures -- "Pitches" should be a
- one-stop reference about the pitch portion of notes. This section
- is written in formal technical writing style.
-
-Users are not expected to read this manual from start to finish.
-However, they should be familiar with the material in the Learning
-Manual (particularly ``Fundamental Concepts''), so do not repeat
-that material in each section of this book. Also, you should
-assume that users know what the notation means; explaining musical
-concepts happens in the Music Glossary.
+ duplicated in the Learning Manual (for teaching), but consider
+ the NR to be the "definitive" description of each notation
+ element, with the LM being an "extra". The goal is _not_ to
+ provide a step-by-step learning environment -- do not avoid
+ using notation that has not be introduced previously in the
+ NR (for example, use \break if appropriate). This section is
+ written in formal technical writing style.
+
+Avoid duplication. Although users are not expected to read this
+manual from start to finish, they should be familiar with the
+material in the Learning Manual (particularly ``Fundamental
+Concepts''), so do not repeat that material in each section of
+this book. Also watch out for common constructs, like ^ - _ for
+directions -- those are explained in NR 3. In NR 1, you can
+write:
+DYNAMICS may be manually placed above or below the
+staff, see @ref{Controlling direction and placement}.
+
+Most tweaks should be added to LSR and not placed directly in the
+.itely file. In some cases, tweaks may be placed in the main
+text, but ask about this first.
+
+Finally, you should assume that users know what the notation
+means; explaining musical concepts happens in the Music Glossary.
* Application Usage: information about using the program lilypond
* 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.
The order of headings inside documentation sections should be:
main docs
-@refcommands
-@commonprop
+@predefined
+@endpredefined
+@snippets
@seealso
-@refbugs
+@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}.
+
+ Notation Reference:
+ @ruser{faazle},
+ @ruser{boo}.
- Learning Manual: @rlearning{baz}, @rlearning{foozle}
+ Application Usage:
+ @rprogram{blah}.
- Notation Reference: @ruser{faazle}, @ruser{boo}.
+ Installed Files:
+ @file{path/to/dir/blahz}.
- Application Usage: @rprogram{blah}.
+ Snippets: @rlsr{section}.
- Installed files: @file{path/to/dir/blahz}.
+ Internals Reference:
+ @rinternals{fazzle},
+ @rinternals{booar}.
- 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.)
+ If there are multiple entries, separate them by commas
+ but do not include an `and'.
- Internals Reference: @internalsref{fazzle}, @internalsref{booar}.
+ 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.
Both index commands should go in front of the actual material.
+ @cindex entries should not be capitalized, ie
+ @cindex time signature
+ 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.
- list of specific terms:
-canceled, bar
+canceled
+simultaenous NOT concurrent
+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
projects / lilypond.git / blobdiff