Documentation/user/README.txt

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