Documentation/user/README.txt

   1 Info for Documentation
   2 ----------------------
   3
   4 Current version of the manual: 2.8.0
   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
  45 * The use of the word `illegal' is inappropriate in most cases.  Say
  46   `invalid' instead.
  47
  48 * Avoid long stretches of input code.  Noone is going to read them in
  49   print.  Instead refer to an example input file (@inputfileref), these
  50   are clickable in HTML.
  51
  52 * Abbrevs in caps, e.g., HTML, DVI, MIDI, etc.
  53
  54 * Colon usage
  55
  56   0. Do not use a colon to introduce examples, sentences just continue
  57
  58       in the display material.
  59
  60   1. To introduce lists
  61   2. When beginning a quote: "So, he said,..."
  62      This usage is rarer.  Americans often just use a comma.
  63   3. When adding a defining example at the end of a sentence.
  64
  65 * To produce good looking texinfo output (for both TTY and DVI) some
  66   additional formatting rules should be followed.
  67
  68   . Do not use tabs.  They expand to nothing in DVI output.
  69
  70   . Do not use spaces at the beginning of a line (except in @example
  71     or @verbatim environments), and do not use more than a single space
  72     between words.  `makeinfo' copies the input lines verbatim without
  73     removing those spaces.
  74
  75   . Use two spaces after a priod.
  76
  77   . Variables or numbers which consist of a single character (probably
  78     followed by a punctuation mark) should be tied properly, either to
  79     the previous or the next word.  Example:
  80
  81       The variable@tie{}@var{a} ...
  82
  83   . To get consistent indentation in the DVI output it is better to avoid
  84     the @verbatim environment.  Use the @example environment instead if
  85     possible, but without extraneous indentation.  For example, this
  86
  87       @example
  88         foo {
  89           bar
  90         }
  91       @end example
  92
  93     should be replaced with
  94
  95       @example
  96       foo {
  97         bar
  98       }
  99       @end example
 100
 101     where `@example' starts the line (without leading spaces).
 102
 103   . Use the `quote' option in @lilypond commands if possible.
 104
 105   . Do not compress the input vertically; this is, do not use
 106
 107       Beginning of logical unit
 108       @example
 109       ...
 110       @end example
 111       continuation of logical unit
 112
 113     but
 114
 115       Beginning of logical unit
 116
 117       @example
 118       ...
 119       @end example
 120
 121       @noindent
 122       continuation of logical unit
 123
 124     This makes it easier to not forget `@noindent'.
 125
 126   . Non-ASCII characters which are in utf-8 should be directly used;
 127     this is, don't say `Ba@ss{}tuba' but `Baßtuba'.  This ensures that
 128     all such characters appear in all output formats.
 129
 130 * Lines should be less than 80 characters long.
 131
 132
 133 %%%%%
 134 HINTS FOR TECHNICAL WRITING STYLE
 135
 136 * Do not refer to LilyPond in the text.  The reader knows what the
 137   manual is about.  If you do, capitalization is LilyPond.
 138
 139 * If you explicitly refer to `lilypond', the program (or any other
 140   command to be executed), say `@command{lilypond}'.
 141
 142 * Do not explicitly refer to the reader/user.  There is no one else
 143   besides the reader and the writer.
 144
 145 * Do not use abbreviations (don't, won't, etc.).  If you do, use a
 146   comma after it:
 147
 148     blabla blabla, i.e., blabla blabla
 149
 150 * Avoid fluff (``Notice that,'' ``as you can see,'' ``Currently,'').
 151