Documentation/user/README.txt

   1 Info for Documentation
   2 ----------------------
   3
   4 Current version of the manual: 2.9.13
   5 *** Please update this whenever you run convert-ly on the docs.
   6
   7 convert-ly --from=... --to=... --no-version *.itely
   8
   9 %%%%%
  10 DOC ORGANIZATION
  11
  12 There are three parts to the documentation: the Learning Manual,
  13 the Notation Reference, and the Technical Details.
  14
  15 * Long, wordy, chatty explanations go in the Learning Manual.
  16 This is aimed at users learning something for the first
  17 time -- not necessarily just learning lilypond notation, but
  18 also things like learning how to deal with projects, tweaking,
  19 preparing parts for orchestras, etc.  Less formal language
  20 may be used here.
  21
  22 * Notation Reference is a (hopefully complete) description of
  23 LilyPond input notation.  Some material from here may be
  24 duplicated in the Learning Manual (for teaching).  The
  25 material is presented in an approximate order of increasing
  26 difficulty, but the goal is _not_ to provide a step-by-step
  27 learning environment.  For example, all material under
  28 "Notes" should remain in that section, even though microtonal
  29 accidentals may seem more advanced than info about clefs or
  30 time signatures -- "Notes" should be a one-stop reference
  31 about, well, notes.  This section is written in formal
  32 technical writing style.
  33
  34 * Technical Details contains information about using
  35 the program lilypond with other programs (lilypond-book,
  36 operating systems, GUIs, convert-ly, etc).  This section
  37 is writtin in formal technical writing style.
  38
  39
  40 %%%%%
  41 GENERAL GUIDELINES
  42
  43 * Do not forget to create @cindex entries for new sections of text.
  44   Enter commands with @funindex, i.e.
  45   @funindex \relative
  46   do not bother with the @code{} (they are added automatically).  These
  47   items are added to both the command index and the unified index.
  48
  49 * The use of the word `illegal' is inappropriate in most cases.  Say
  50   `invalid' instead.
  51
  52 * Avoid long stretches of input code.  Noone is going to read them in
  53   print.  Instead refer to an example input file (@inputfileref), these
  54   are clickable in HTML.
  55
  56 * Abbrevs in caps, e.g., HTML, DVI, MIDI, etc.
  57
  58 * Colon usage
  59
  60   0. Do not use a colon to introduce examples, sentences just continue
  61
  62       in the display material.
  63
  64   1. To introduce lists
  65   2. When beginning a quote: "So, he said,..."
  66      This usage is rarer.  Americans often just use a comma.
  67   3. When adding a defining example at the end of a sentence.
  68
  69 * To produce good looking texinfo output (for both TTY and DVI) some
  70   additional formatting rules should be followed.
  71
  72   . Do not use tabs.  They expand to nothing in DVI output.
  73
  74   . Do not use spaces at the beginning of a line (except in @example
  75     or @verbatim environments), and do not use more than a single space
  76     between words.  `makeinfo' copies the input lines verbatim without
  77     removing those spaces.
  78
  79   . Use two spaces after a priod.
  80
  81   . Variables or numbers which consist of a single character (probably
  82     followed by a punctuation mark) should be tied properly, either to
  83     the previous or the next word.  Example:
  84
  85       The variable@tie{}@var{a} ...
  86
  87   . To get consistent indentation in the DVI output it is better to avoid
  88     the @verbatim environment.  Use the @example environment instead if
  89     possible, but without extraneous indentation.  For example, this
  90
  91       @example
  92         foo {
  93           bar
  94         }
  95       @end example
  96
  97     should be replaced with
  98
  99       @example
 100       foo {
 101         bar
 102       }
 103       @end example
 104
 105     where `@example' starts the line (without leading spaces).
 106
 107   . Use the `quote' option in @lilypond commands if possible.
 108
 109   . Do not compress the input vertically; this is, do not use
 110
 111       Beginning of logical unit
 112       @example
 113       ...
 114       @end example
 115       continuation of logical unit
 116
 117     but
 118
 119       Beginning of logical unit
 120
 121       @example
 122       ...
 123       @end example
 124
 125       @noindent
 126       continuation of logical unit
 127
 128     This makes it easier to not forget `@noindent'.
 129
 130   . Non-ASCII characters which are in utf-8 should be directly used;
 131     this is, don't say `Ba@ss{}tuba' but `Baßtuba'.  This ensures that
 132     all such characters appear in all output formats.
 133
 134 * Lines should be less than 80 characters long.
 135
 136
 137 %%%%%
 138 HINTS FOR TECHNICAL WRITING STYLE
 139
 140 * Do not refer to LilyPond in the text.  The reader knows what the
 141   manual is about.  If you do, capitalization is LilyPond.
 142
 143 * If you explicitly refer to `lilypond', the program (or any other
 144   command to be executed), say `@command{lilypond}'.
 145
 146 * Do not explicitly refer to the reader/user.  There is no one else
 147   besides the reader and the writer.
 148
 149 * Do not use abbreviations (don't, won't, etc.).  If you do, use a
 150   comma after it:
 151
 152     blabla blabla, i.e., blabla blabla
 153
 154 * Avoid fluff (``Notice that,'' ``as you can see,'' ``Currently,'').
 155