X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fpolicy.txt;h=4dac1c28f5fdd89f1752dbda586cb458f205792d;hb=2455e5b0f8f0846a42952e32bbedecf1da1e7855;hp=67a94817ec60f5a6cdc2996732af171f7f893d03;hpb=23efbcbaa7dab9303faec9fc0aca4fec805e550c;p=lilypond.git diff --git a/Documentation/user/policy.txt b/Documentation/user/policy.txt index 67a94817ec..4dac1c28f5 100644 --- a/Documentation/user/policy.txt +++ b/Documentation/user/policy.txt @@ -8,11 +8,22 @@ There are four parts to the documentation: the Learning Manual, 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. @@ -20,21 +31,30 @@ 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 @@ -60,33 +80,54 @@ 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 +@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: + @lsrdir{section}, + @lsr{specific/example-name.ly}. - Installed files: @file{path/to/dir/blahz}. + Internals Reference: + @internalsref{fazzle}, + @internalsref{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. + * To create links, use @ref{} if the link is within the same manual. @@ -107,11 +148,20 @@ main docs 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. + * 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 %%%%% TECHNICAL WRITING STYLE