Documentation/user/README.txt

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