Documentation/user/README.txt

   1 Info for Documentation
   2 ----------------------
   3
   4 %%%%% BOOKS
   5
   6 There are four parts to the documentation: the Learning Manual,
   7 the Notation Reference, the Program Reference, and the Music
   8 Glossary.
   9
  10 * Learning Manual: long, chatty, friendly explanations go here.
  11   This is aimed at users learning something for the first time --
  12   not necessarily just learning lilypond notation, but also things
  13   like learning how to deal with projects, tweaking, preparing parts
  14   for orchestras, etc.  Less formal language may be used here.
  15
  16 Users are encouraged to read the complete Learning Manual from
  17 start-to-finish.
  18
  19
  20 * Notation Reference: a (hopefully complete) description of
  21   LilyPond input notation.  Some material from here may be
  22   duplicated in the Learning Manual (for teaching).  The material is
  23   presented in an approximate order of increasing difficulty, but
  24   the goal is _not_ to provide a step-by-step learning environment.
  25   For example, all material under "Pitches" should remain in that
  26   section, even though microtonal accidentals may seem more advanced
  27   than info about clefs or time signatures -- "Pitches" should be a
  28   one-stop reference about the pitch portion of notes.  This section
  29   is written in formal technical writing style.
  30
  31 Users are not expected to read this manual from start to finish.
  32 However, they should be familiar with the material in the Learning
  33 Manual (particularly ``Fundamental Concepts''), so do not repeat
  34 that material in this book.  Also, you should assume that users
  35 know what the notation means; explaining musical concepts happens
  36 in the Music Glossary.
  37
  38
  39 * Program Usage: information about using the program lilypond with
  40   other programs (lilypond-book, operating systems, GUIs,
  41   convert-ly, etc).  This section is written in formal technical
  42   writing style.
  43
  44 Users are not expected to read this manual from start to finish.
  45
  46
  47 * Music Glossary: information about the music notation itself.
  48   Explainations and translations about notation terms go here.
  49
  50 Users are not expected to read this manual from start to finish.
  51
  52
  53 %%%%% SECTION ORGANIZATION
  54
  55 The order of headings inside documentation sections should be:
  56
  57 main docs
  58 @commonprop
  59 @seealso
  60 @refbugs
  61
  62 * You must include a @seealso with at least one link to @lsrdir{}.
  63
  64 * @commonprop and @refbugs are optional.
  65
  66
  67 %%%%% LILYPOND FORMATTING
  68
  69 * Use two spaces for indentation in lilypond examples.  (no tabs)
  70
  71 * If possible, only write one bar per line.  The notes on each
  72   line should be an independent line.
  73   Bad:
  74     \override textscript #'padding = #3 c1^"hi"
  75   Good:
  76     \override textscript #'padding = #3
  77     c1^"hi"
  78
  79 * LilyPond input should be produce via
  80     @lilypond[verbatim,quote,ragged-right]
  81   with `fragment' and `relative=2' optional.
  82
  83   Examples about page layout may alter the quote/ragged-right
  84   options.  Omitting `verbatim' is not allowed.
  85
  86 * Inspirational headwords are produced with
  87   @lilypondfile[ragged-right,line-width=16\cm,staffsize=16,quote]
  88   {pitches-headword.ly}
  89
  90 * Avoid long stretches of input code.  Noone is going to read them
  91   in print.  Instead refer to an example input file with @lsr{}.
  92
  93
  94 %%%%% TEXT FORMATTING
  95
  96 * Lines should be less than 72 characters long.  (I personally
  97   recommend writing with 66-char lines, but don't bother modifying
  98   existing material.)
  99
 100 * Do not use tabs.  They expand to nothing in DVI output.
 101
 102 * Do not use spaces at the beginning of a line (except in @example
 103   or @verbatim environments), and do not use more than a single
 104   space between words.  `makeinfo' copies the input lines verbatim
 105   without removing those spaces.
 106
 107 * Use two spaces after a period.
 108
 109 * Variables or numbers which consist of a single character
 110   (probably followed by a punctuation mark) should be tied
 111   properly, either to the previous or the next word.  Example:
 112
 113       The variable@tie{}@var{a} ...
 114
 115 * To get consistent indentation in the DVI output it is better to
 116   avoid the @verbatim environment.  Use the @example environment
 117   instead if possible, but without extraneous indentation.  For
 118   example, this
 119
 120     @example
 121       foo {
 122         bar
 123       }
 124     @end example
 125
 126   should be replaced with
 127
 128     @example
 129     foo {
 130       bar
 131     }
 132     @end example
 133
 134   where `@example' starts the line (without leading spaces).
 135
 136 * Do not compress the input vertically; this is, do not use
 137
 138     Beginning of logical unit
 139     @example
 140     ...
 141     @end example
 142     continuation of logical unit
 143
 144   but
 145
 146     Beginning of logical unit
 147
 148     @example
 149     ...
 150     @end example
 151
 152     @noindent
 153     continuation of logical unit
 154
 155   This makes it easier to avoid forgetting the `@noindent'.
 156
 157 * in @itemize use @item on a separate line like this:
 158   @itemize
 159   @item
 160   Foo
 161
 162   @item
 163   Bar
 164
 165   Do not use @itemize @bullet.
 166
 167 * Use @q instead of `...' and @qq instead of ``...''.  The latter macro
 168   should be used with care since we use `...' as the default quoting
 169   throughout the manual, except for things related to direct speech.
 170
 171   In most cases, you should use @code{} or @samp{} instead.
 172
 173
 174 %%%%% READABILITY
 175
 176 * Non-ASCII characters which are in utf-8 should be directly used;
 177   this is, don't say `Ba@ss{}tuba' but `Baßtuba'.  This ensures that
 178   all such characters appear in all output formats.
 179
 180 * Don't use a @ref{link to another section} in the middle of a
 181   sentence.  It looks ok in HTML, moderately bad in PDF, and
 182   utterly horrible in INFO.  Instead, reword the sentence so that
 183   users are encouraged to see @ref{link to another section}.
 184   (at the end of the sentence)
 185
 186 * Do not forget to create @cindex entries for new sections of text.
 187   Enter commands with @funindex, i.e.
 188     @cindex pitches, writing in different octaves
 189     @funindex \relative
 190   do not bother with the @code{} (they are added automatically).  These
 191   items are added to both the command index and the unified index.
 192
 193 * Abbrevs in caps, e.g., HTML, DVI, MIDI, etc.
 194
 195 * Colon usage
 196
 197   1. To introduce lists
 198   2. When beginning a quote: "So, he said,..."
 199      This usage is rarer.  Americans often just use a comma.
 200   3. When adding a defining example at the end of a sentence.
 201
 202
 203 %%%%% TECHNICAL WRITING STYLE
 204
 205 * Do not refer to LilyPond in the text.  The reader knows what the
 206   manual is about.  If you do, capitalization is LilyPond.
 207
 208 * If you explicitly refer to `lilypond' the program (or any other
 209   command to be executed), say `@command{lilypond}'.
 210
 211 * Do not explicitly refer to the reader/user.  There is no one
 212   else besides the reader and the writer.
 213
 214 * Do not use abbreviations (don't, won't, etc.).  If you do, use a
 215   comma after it:
 216
 217     blabla blabla, i.e., blabla blabla
 218
 219 * Avoid fluff (``Notice that,'' ``as you can see,''
 220   ``Currently,'').
 221
 222 * The use of the word `illegal' is inappropriate in most cases.
 223   Say `invalid' instead.
 224
 225
 226 %%%%% UPDATING DOCS
 227 convert-ly -e --from=... --to=... --no-version *.itely
 228
 229 % to find the current version number,
 230 grep "version \"" tutorial.itely
 231
 232 %  (nobody ever remembers to update this file, so I've stopped
 233 %  trying to record it here)
 234
 235
 236