Documentation/automated-engraving/input-format.itexi

   1 @c -*- coding: utf-8; mode: texinfo; -*-
   2 @ignore
   3     Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
   4
   5     When revising a translation, copy the HEAD committish of the
   6     version that you are working on.  See TRANSLATION for details.
   7 @end ignore
   8
   9
  10
  11 @node input-format
  12
  13 @unnumberedsec Input format
  14
  15 As discussed earlier, the ideal input format for a music engraving
  16 system is the content: the music itself. This poses a formidable
  17 problem: how can we define what music really @emph{is}? Our way out
  18 of this problem, is to reverse it.  Instead of defining what music is,
  19 our program serves as a definition: we write a program capable of
  20 producing sheet music, and adjust the format to be as lean as
  21 possible.  When the format can no longer be trimmed down, by
  22 definition we are left with content itself.
  23
  24 The syntax is also the user-interface for LilyPond, hence it is easily
  25 typable, e.g.,
  26
  27 @verbatim
  28
  29   c'4 d'8
  30
  31 @end verbatim
  32 Are a quarter note C1 and eighth note D1, as in this example:
  33
  34 @divClass{float-center}
  35 @sourceimage{simple-notation,,,.png}
  36 @divEnd
  37
  38 On a microscopic scale, such syntax is easy to use. On a larger scale,
  39 syntax also  needs structure.  How else can  you enter  complex pieces
  40 like symphonies and operas? The  structure is formed by the concept of
  41 music expressions:  by combining small fragments of  music into larger
  42 ones, more complex music can be expressed.  For example,
  43
  44 @multitable @columnfractions .5 .5
  45 @item
  46
  47 c4
  48
  49 @tab
  50
  51 @sourceimage{simultaneous-0,,,.png}
  52
  53
  54 @end multitable
  55
  56 Combine this simultaneously with two other notes by enclosing in <&lt
  57 and >>.
  58
  59 @multitable @columnfractions .5 .5
  60
  61 @item
  62
  63 @verbatim
  64
  65   <<c4 d4 e4>>
  66
  67 @end verbatim
  68
  69
  70 @tab
  71
  72 @sourceimage{simultaneous-1,,,.png}
  73
  74
  75
  76 @end multitable
  77
  78 This expression is put in sequence by enclosing it in braces, i.e.,
  79 @multitable @columnfractions .5 .5
  80 @item
  81
  82 @verbatim
  83
  84    { <<c4 d4 e4>> f4  }
  85 @end verbatim
  86
  87
  88 @tab
  89
  90 @sourceimage{simultaneous-2,,,.png}
  91
  92
  93
  94 @end multitable
  95
  96 The above is another expression, and therefore, it may be combined
  97 again with a simultaneous expression (in this case, a half note).
  98
  99 @multitable @columnfractions .5 .5
 100 @item
 101
 102 @verbatim
 103
 104 << { <<c4 d4 e4>> f4 } g2 >>
 105
 106 @end verbatim
 107
 108
 109 @tab
 110
 111 @sourceimage{simultaneous-3,,,.png}
 112
 113
 114
 115
 116 @end multitable
 117
 118 Such recursive structures can be specified neatly and formally in a
 119 @emph{context-free grammar}.  The parsing code is also generated
 120 from this grammar. In other words, the  syntax of LilyPond is clearly
 121 and unambiguously defined.
 122
 123 User-interfaces and syntax are what people see and deal with
 124 most. They are partly a matter of taste, and also subject of much
 125 discussion.  Although discussions on taste do have their merit, they
 126 are not very productive.  In the larger picture of LilyPond, the
 127 importance of input syntax is small: inventing neat syntax is easy,
 128 writing decent formatting code is much harder.  This is also
 129 illustrated by the line-counts for the respective components: parsing
 130 and representation take up less than 10% of the code.
 131
 132 @multitable @columnfractions .5 .5
 133 @item
 134 Parsing + representation
 135 @tab
 136 @item
 137 total
 138 @tab
 139 @item
 140 6000 lines C++
 141 @tab
 142 61500 lines C++
 143 @end multitable
 144
 145 @ignore
 146   TODO :
 147
 148   blurbs about lilypond today
 149
 150   future?
 151 @end ignore
 152
 153 @divClass{float-right}
 154 Next: @ref{conclusion,wrapping it up}, the conclusion.
 155 @divEnd