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