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 * Do not use tabs.  They expand to nothing in DVI output.
  75
  76 * Do not use spaces at the beginning of a line (except in @example
  77   or @verbatim environments), and do not use more than a single
  78   space between words.  `makeinfo' copies the input lines verbatim
  79   without removing those spaces.
  80
  81 * Use two spaces after a period.
  82
  83 * Don't use a @ref{link to another section} in the middle of a
  84   sentence.  It looks ok in HTML, moderately bad in PDF, and
  85   utterly horrible in INFO.  Instead, reword the sentence so that
  86   users are encouraged to see @ref{link to another section}.
  87   (at the end of the sentence)
  88
  89 * Variables or numbers which consist of a single character
  90   (probably followed by a punctuation mark) should be tied
  91   properly, either to the previous or the next word.  Example:
  92
  93       The variable@tie{}@var{a} ...
  94
  95 * To get consistent indentation in the DVI output it is better to
  96   avoid the @verbatim environment.  Use the @example environment
  97   instead if possible, but without extraneous indentation.  For
  98   example, this
  99
 100     @example
 101       foo {
 102         bar
 103       }
 104     @end example
 105
 106   should be replaced with
 107
 108     @example
 109     foo {
 110       bar
 111     }
 112     @end example
 113
 114   where `@example' starts the line (without leading spaces).
 115
 116 * Use the `quote' option in @lilypond commands if possible.
 117
 118   Do not compress the input vertically; this is, do not use
 119
 120     Beginning of logical unit
 121     @example
 122     ...
 123     @end example
 124     continuation of logical unit
 125
 126   but
 127
 128     Beginning of logical unit
 129
 130     @example
 131     ...
 132     @end example
 133
 134     @noindent
 135     continuation of logical unit
 136
 137   This makes it easier to avoid forgetting the `@noindent'.
 138
 139 * Non-ASCII characters which are in utf-8 should be directly used;
 140   this is, don't say `Ba@ss{}tuba' but `Baßtuba'.  This ensures that
 141   all such characters appear in all output formats.
 142
 143 * Lines should be less than 72 characters long.  (I personally
 144   recommend writing with 66-char lines, but don't bother modifying
 145   existing material.)
 146
 147 * Use @q instead of `...' and @qq instead of ``...''.  The latter macro
 148   should be used with care since we use `...' as the default quoting
 149   throughout the manual, except for things related to direct speech.
 150
 151   Warning: @q{} and @qq{} *MUST NOT* come at the end or beginning
 152   of a line (unless it begins the paragraph).  If these macros
 153   @qq{appear like this}, then they will being a new paragraph.
 154
 155   In most cases, you should use @code{} or @samp{} instead.
 156
 157
 158 %%%%% READABILITY
 159
 160 * LilyPond input should be produce via
 161     @lilypond[verbatim,quote,ragged-right]
 162   with `fragment' and `relative=2' optional.
 163
 164   Examples about page layout may alter the quote/ragged-right
 165   options.  Omitting `verbatim' is not recommended (other than the
 166   ``inspirational headword'' examples)
 167
 168 * Do not forget to create @cindex entries for new sections of text.
 169   Enter commands with @funindex, i.e.
 170     @cindex pitches, writing in different octaves
 171     @funindex \relative
 172   do not bother with the @code{} (they are added automatically).  These
 173   items are added to both the command index and the unified index.
 174
 175 * Avoid long stretches of input code.  Noone is going to read them in
 176   print.  Instead refer to an example input file (with @lsr{}); these
 177   are clickable in HTML.
 178
 179 * Abbrevs in caps, e.g., HTML, DVI, MIDI, etc.
 180
 181 * Colon usage
 182
 183   1. To introduce lists
 184   2. When beginning a quote: "So, he said,..."
 185      This usage is rarer.  Americans often just use a comma.
 186   3. When adding a defining example at the end of a sentence.
 187
 188
 189 %%%%% HINTS FOR TECHNICAL WRITING STYLE
 190
 191 * Do not refer to LilyPond in the text.  The reader knows what the
 192   manual is about.  If you do, capitalization is LilyPond.
 193
 194 * If you explicitly refer to `lilypond' the program (or any other
 195   command to be executed), say `@command{lilypond}'.
 196
 197 * Do not explicitly refer to the reader/user.  There is no one
 198   else besides the reader and the writer.
 199
 200 * Do not use abbreviations (don't, won't, etc.).  If you do, use a
 201   comma after it:
 202
 203     blabla blabla, i.e., blabla blabla
 204
 205 * Avoid fluff (``Notice that,'' ``as you can see,''
 206   ``Currently,'').
 207
 208 * The use of the word `illegal' is inappropriate in most cases.
 209   Say `invalid' instead.
 210
 211
 212