Documentation/user/README.txt

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