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