]> git.donarmstrong.com Git - lilypond.git/blob - Documentation/user/policy.txt
Merge branch 'master' of git+ssh://git.sv.gnu.org/srv/git/lilypond
[lilypond.git] / Documentation / user / policy.txt
1 DOCUMENTATION POLICY
2 --------------------
3
4
5 %%%%% BOOKS
6
7 There are four parts to the documentation: the Learning Manual,
8 the Notation Reference, the Program Reference, and the Music
9 Glossary.
10
11 * Learning Manual:
12   The LM is written in a tutorial style which introduces the most
13   important concepts, structure and syntax of the elements of a
14   LilyPond score in a carefully graded sequence of steps.
15   Explanations of all musical concepts used in the Manual can be
16   found in the Music Glossary, and readers are assumed to have no
17   prior knowledge of LilyPond.  The objective is to take readers to
18   a level where the Notation Reference can be understood and
19   employed to both adapt the templates in the Appendix to their
20   needs and to begin to construct their own scores.  Commonly used
21   tweaks are introduced and explained.  Examples are provided
22   throughout which, while being focussed on the topic being
23   introduced, are long enough to seem real in order to retain the
24   readers' interest.  Each example builds on the previous material,
25   and comments are used liberally.  Every new aspect is thoroughly
26   explained before it is used.
27
28 Users are encouraged to read the complete Learning Manual from
29 start-to-finish.
30
31
32 * Notation Reference: a (hopefully complete) description of
33   LilyPond input notation.  Some material from here may be
34   duplicated in the Learning Manual (for teaching), but consider
35   the NR to be the "definitive" description of each notation
36   element, with the LM being an "extra".  The goal is _not_ to
37   provide a step-by-step learning environment -- do not avoid
38   using notation that has not be introduced previously in the
39   NR  (for example, use \break if appropriate).  This section is
40   written in formal technical writing style.
41
42 Avoid duplication.  Although users are not expected to read this
43 manual from start to finish, they should be familiar with the
44 material in the Learning Manual (particularly ``Fundamental
45 Concepts''), so do not repeat that material in each section of
46 this book.  Also watch out for common constructs, like ^ - _ for
47 directions -- those are explained in NR 3.  In NR 1, you can
48 mention that "dynamics (or whatever) may be placed above or below
49 the staff, for details see @ref{Up and down}".
50
51 Most tweaks should be added to LSR and not placed directly in the
52 .itely file.  In some cases, tweaks may be placed in the main
53 text, but ask about this first.
54
55 Finally, you should assume that users know what the notation
56 means; explaining musical concepts happens in the Music Glossary.
57
58
59 * Application Usage: information about using the program lilypond
60   with other programs (lilypond-book, operating systems, GUIs,
61   convert-ly, etc).  This section is written in formal technical
62   writing style.
63
64 Users are not expected to read this manual from start to finish.
65
66
67 * Music Glossary: information about the music notation itself.
68   Explainations and translations about notation terms go here.
69
70 Users are not expected to read this manual from start to finish.
71
72 * Internals Reference: not really a documentation book, since it
73   is automagically generated from the source, but this is its
74   name.
75
76
77 %%%%% SECTION ORGANIZATION
78
79 The order of headings inside documentation sections should be:
80
81 main docs
82 @refcommands
83 @commonprop
84 @seealso
85 @refbugs
86
87 * You _must_ include a @seealso.  The order of items inside the
88   @seealso section is
89
90     Music Glossary: @rglos{foo}, @rglos{bar}.
91
92     Learning Manual: @rlearning{baz}, @rlearning{foozle}
93
94     Notation Reference: @ruser{faazle}, @ruser{boo}.
95
96     Application Usage: @rprogram{blah}.
97
98     Installed Files: @file{path/to/dir/blahz}.
99
100     Snippets: @lsrdir{section}, @lsr{specific/example-name.ly}.
101       (if there is only one entry, omit a final period.  If there
102        are multiple entries, separate them by commas, do not
103        include an `and', and end with a period.)
104
105     Internals Reference: @internalsref{fazzle}, @internalsref{booar}.
106
107   ("Snippets" is REQUIRED; the others are optional)
108
109   Any new concepts or links which require an explanation should go
110   as a full sentence(s) in the main text.
111
112 * To create links, use @ref{} if the link is within the same
113   manual.
114
115 * Do not include any real info in second-level sections (ie 1.1
116   Pitches).  A first-level section may have introductory material,
117   but other than that all material goes into third-level sections
118   (ie 1.1.1 Writing Pitches).
119
120
121 %%%%% GENERAL WRITING
122
123 * Do not forget to create @cindex entries for new sections of text.
124   Enter commands with @funindex, i.e.
125     @cindex pitches, writing in different octaves
126     @funindex \relative
127   do not bother with the @code{} (they are added automatically).  These
128   items are added to both the command index and the unified index.
129
130   Both index commands should go in front of the actual material.
131
132   @cindex entries should not be capitalized, ie
133     @cindex time signature
134   is preferred.  (instead of `Time signature')   Only use capital
135   letters for musical terms which demand them, like D.S. al Fine.
136
137 * Preferred terms:
138     - in general, use the American spellings.  The internal
139       lilypond property names use this spelling.
140     - list of specific terms:
141 canceled
142 simultaenous    NOT concurrent
143 measure: the unit of music
144 bar line: the symbol delimiting a measure   NOT barline
145 note head   NOT notehead
146
147
148 %%%%% TECHNICAL WRITING STYLE
149
150 * Do not refer to LilyPond in the text.  The reader knows what the
151   manual is about.  If you do, capitalization is LilyPond.
152
153 * If you explicitly refer to `lilypond' the program (or any other
154   command to be executed), say `@command{lilypond}'.
155
156 * Do not explicitly refer to the reader/user.  There is no one
157   else besides the reader and the writer.
158
159 * Do not use abbreviations (don't, won't, etc.).  If you do, use a
160   comma after it:
161
162     blabla blabla, i.e., blabla blabla
163
164 * Avoid fluff (``Notice that,'' ``as you can see,''
165   ``Currently,'').
166
167 * The use of the word `illegal' is inappropriate in most cases.
168   Say `invalid' instead.
169
170
171