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 write:
  49 DYNAMICS may be manually placed above or below the
  50 staff, see @ref{Controlling direction and placement}.
  51
  52 Most tweaks should be added to LSR and not placed directly in the
  53 .itely file.  In some cases, tweaks may be placed in the main
  54 text, but ask about this first.
  55
  56 Finally, you should assume that users know what the notation
  57 means; explaining musical concepts happens in the Music Glossary.
  58
  59
  60 * Application Usage: information about using the program lilypond
  61   with other programs (lilypond-book, operating systems, GUIs,
  62   convert-ly, etc).  This section is written in formal technical
  63   writing style.
  64
  65 Users are not expected to read this manual from start to finish.
  66
  67
  68 * Music Glossary: information about the music notation itself.
  69   Explanations and translations about notation terms go here.
  70
  71 Users are not expected to read this manual from start to finish.
  72
  73 * Internals Reference: not really a documentation book, since it
  74   is automagically generated from the source, but this is its
  75   name.
  76
  77
  78 %%%%% SECTION ORGANIZATION
  79
  80 The order of headings inside documentation sections should be:
  81
  82 main docs
  83 @predefined
  84 @endpredefined
  85 @snippets
  86 @seealso
  87 @knownissues
  88
  89 * You _must_ include a @seealso.  The order of items inside the
  90   @seealso section is
  91
  92     Music Glossary:
  93     @rglos{foo},
  94     @rglos{bar}.
  95
  96     Learning Manual:
  97     @rlearning{baz},
  98     @rlearning{foozle}.
  99
 100     Notation Reference:
 101     @ruser{faazle},
 102     @ruser{boo}.
 103
 104     Application Usage:
 105     @rprogram{blah}.
 106
 107     Installed Files:
 108     @file{path/to/dir/blahz}.
 109
 110     Snippets: @rlsr{section}.
 111
 112     Internals Reference:
 113     @rinternals{fazzle},
 114     @rinternals{booar}.
 115
 116       If there are multiple entries, separate them by commas
 117       but do not include an `and'.
 118
 119       Always end with a period.
 120
 121       Place each link on a new line as above; this makes it much
 122       easier to add or remove links.  In the output, they
 123       appear on a single line.
 124
 125   ("Snippets" is REQUIRED; the others are optional)
 126
 127   Any new concepts or links which require an explanation should go
 128   as a full sentence(s) in the main text.
 129
 130   Don't insert an empty line between @seealso and the first entry!
 131   Otherwise there is excessive vertical space in the PDF output.
 132
 133 * To create links, use @ref{} if the link is within the same
 134   manual.
 135
 136 * @predefined ... @endpredefined is for commands in ly/*-init.ly
 137   FIXME?
 138
 139 * Do not include any real info in second-level sections (ie 1.1
 140   Pitches).  A first-level section may have introductory material,
 141   but other than that all material goes into third-level sections
 142   (ie 1.1.1 Writing Pitches).
 143
 144
 145 %%%%% CHECKING CROSS-REFERENCES
 146
 147 Cross-references between different manuals are heavily used in the
 148 documentation, but they are not checked during compilation.  However,
 149 if you compile the documentation, a script called check_texi_refs can
 150 help you with checking and fixing these cross-references; for
 151 information on usage, cd into a source tree where documentation has
 152 been built, cd into Documentation and look for check-xrefs and
 153 fix-xrefs targets in 'make help' output.  Note that you have to find
 154 yourself the source files to fix cross-references in the generated
 155 documentation such as the Internals Reference; e.g. you can grep
 156 scm/ and lily/.
 157
 158
 159 %%%%% GENERAL WRITING
 160
 161 * Do not forget to create @cindex entries for new sections of text.
 162   Enter commands with @funindex, i.e.
 163     @cindex pitches, writing in different octaves
 164     @funindex \relative
 165   do not bother with the @code{} (they are added automatically).  These
 166   items are added to both the command index and the unified index.
 167
 168   Both index commands should go in front of the actual material.
 169
 170   @cindex entries should not be capitalized, ie
 171     @cindex time signature
 172   is preferred.  (instead of `Time signature')   Only use capital
 173   letters for musical terms which demand them, like D.S. al Fine.
 174
 175   For scheme functions, only include the final part, ie
 176     @funindex modern-voice-cautionary
 177   and NOT
 178     @funindex #(set-accidental-style modern-voice-cautionary)
 179
 180 * Preferred terms:
 181     - in general, use the American spellings.  The internal
 182       lilypond property names use this spelling.
 183     - list of specific terms:
 184 canceled
 185 simultaenous    NOT concurrent
 186 measure: the unit of music
 187 bar line: the symbol delimiting a measure   NOT barline
 188 note head   NOT notehead
 189 chord construct   NOT chord (when referring to <>)
 190
 191
 192 %%%%% TECHNICAL WRITING STYLE
 193
 194 * Do not refer to LilyPond in the text.  The reader knows what the
 195   manual is about.  If you do, capitalization is LilyPond.
 196
 197 * If you explicitly refer to `lilypond' the program (or any other
 198   command to be executed), say `@command{lilypond}'.
 199
 200 * Do not explicitly refer to the reader/user.  There is no one
 201   else besides the reader and the writer.
 202
 203 * Do not use abbreviations (don't, won't, etc.).  If you do, use a
 204   comma after it:
 205
 206     blabla blabla, i.e., blabla blabla
 207
 208 * Avoid fluff (``Notice that,'' ``as you can see,''
 209   ``Currently,'').
 210
 211 * The use of the word `illegal' is inappropriate in most cases.
 212   Say `invalid' instead.
 213
 214
 215