This section deals with general lilypond input syntax issues,
rather than specific notation.
+FIXME: don't complain about anything in this chapter. It's still
+under heavy development.
+
+FIXME: add comments
+@verbatim
+% %{
+@end verbatim
+to 3.1.
+
@menu
* Input files::
* Common syntax issues TODO name?::
@section Input files
The main format of input for LilyPond are text files. By convention,
-these files end with @samp{.ly}.
+these files end with @code{.ly}.
@menu
* File structure::
@seealso
-Examples: @lsr{non-notation,clip-systems.ly}
+Examples: @c @lsr{non-notation,clip-systems.ly}
@node Including LilyPond files
search path.
The @code{\include} statement can use full path information, but with the Unix
-convention @samp{/} rather than the DOS/Windows @samp{\}. For example,
+convention @code{/} rather than the DOS/Windows @code{\}. For example,
if @file{stuff.ly} is located one directory higher than the current working
directory, use
@seealso
-@lsr{text,utf-8.ly}
+@c @lsr{text,utf-8.ly}
@node Different editions from one source
@seealso
-Examples: @lsr{parts,tag@/-filter@/.ly}
+Examples: @c @lsr{parts,tag@/-filter@/.ly}
-@refbugs
+@knownissues
Multiple rests are not merged if you create the score with both tagged
sections.
@section Common syntax issues TODO name?
@menu
-* Up and down::
+* Controlling direction and placement::
* Distances and measurements MAYBE MOVE::
+* When to add a -::
@end menu
-@node Up and down
-@subsection Up and down
+@node Controlling direction and placement
+@subsection Controlling direction and placement
TODO: everything
^ _
@end verbatim
+Also cover
+#UP
+#DOWN
+#LEFT
+#RIGHT.
+
+Maybe rename section to "directions".
+
+Also mention \override Foo #'direction = #'DOWN.
+
+also mention the typical \fooDown, \fooNeutral predefined commands.
+
+also mention that some directions are (without other tweaking)
+always up or always down (like dynamics or fermata), while other
+things can alternate between up or down based on the stem direction
+(like slurs or accents).
+
@node Distances and measurements MAYBE MOVE
@subsection Distances and measurements MAYBE MOVE
TODO: staff spaces, #UP #DOWN #LEFT #RIGHT. Maybe move into tweaks?
+@node When to add a -
+@subsection When to add a -
+
+One of these works, the other doesn't.
+@verbatim
+\version "2.11.38"
+{ c'\mp\fermata\accent-\markup { "forcefully"} }
+% { c'\mp\fermata\accent\markup { "forcefully"} }
+@end verbatim
@node Other stuffs TODO move?
@menu
* Displaying LilyPond notation::
* Skipping corrected music::
+* context list FIXME::
+* another thing FIXME::
+* Input modes FIXME::
@end menu
@node Displaying LilyPond notation
voices and staves, saving even more time.
+@node context list FIXME
+@subsection context list FIXME
+
+>> > > - list of contexts: my *danger unmaintainable*
+>> > > alarm just went off. I'm
+
+I knew it would... And leaving out some of them is perfectly fine
+with me.
+I do think that a list like this, with the main contexts and a
+brief
+description of what they do (perhaps also with a note about what
+default
+behaviour is associated with each of them, but this may be
+unmanageable),
+should be there, and then we could simply list the remaining ones
+without
+further explanation and with links to the IR.
+
+
+The Master Of All Contexts
+==========================
+
+ * Score
+ This is the top level notation context. No other context
+can
+ contain a Score context. This context handles the
+ administration of time signatures. It also makes sure that
+ items such as clefs, time signatures, and key-signatures
+are
+ aligned across staves.
+ You cannot explicitly instantiate a Score context (since
+it is
+ not contained in any other context). It is instantiated
+ automatically when an output definition (a \score or
+\layout
+ block) is processed.
+ (it should also be made clear somewhere what the
+difference is between
+ \score and \Score).
+
+Top-level contexts: Staff containers
+====================================
+ * StaffGroup
+ Groups staves while adding a bracket on the left side,
+ grouping the staves together. The bar lines of the
+contained
+ staves are connected vertically. StaffGroup only consists
+of a
+ collection of staves, with a bracket in front and spanning
+bar
+ lines.
+ * ChoirStaff
+ Identical to StaffGroup except that the contained staves
+are
+ not connected vertically.
+ * GrandStaff
+ A group of staves, with a brace on the left side, grouping
+the
+ staves together. The bar lines of the contained staves are
+ connected vertically.
+ * PianoStaff
+ Just like GrandStaff but with a forced distance between
+the
+ staves, so cross staff beaming and slurring can be used.
+ * DrumStaff
+ Handles typesetting for percussion. Can contain DrumVoice
+ * InnerStaffGroup
+ * InnerChoirStaff
+
+Staff-level contexts
+====================
+ * Staff
+ Handles clefs, bar lines, keys, accidentals. It can
+contain
+ Voice contexts.
+ * RhythmicStaff
+ Like Staff but for printing rhythms. Pitches are
+ ignored; the notes are printed on one line.
+ * TabStaff
+ Context for generating tablature. By default lays the
+music
+ expression out as a guitar tablature, printed on six
+lines.
+ * VaticanaStaff
+ Same as Staff, except that it is accommodated for
+ typesetting a piece in gregorian style.
+ * MensuralStaff
+ Same as Staff, except that it is accommodated for
+ typesetting a piece in mensural style.
+
+Voice-level (bottom) contexts
+=============================
+What is generated by default here? The voice-level contexts
+initiate
+certain properties and start engravers.
+
+ * Voice
+ Corresponds to a voice on a staff. This context handles
+the
+ conversion of dynamic signs, stems, beams, super- and
+ subscripts, slurs, ties, and rests.
+ You have to instantiate this explicitly if you want to
+have
+ multiple voices on the same staff.
+ Bottom context.
+ * VaticanaVoice
+ Same as Voice, except that it is accommodated for
+ typesetting a piece in gregorian style.
+ * MensuralVoice
+ Same as Voice, except that it is accommodated for
+ typesetting a piece in mensural style.
+ * Lyrics
+ Corresponds to a voice with lyrics. Handles the printing
+of a
+ single line of lyrics.
+ Bottom context.
+ * DrumVoice
+ A voice on a percussion staff.
+ * FiguredBass
+
+ * ChordNames
+ Typesets chord names. This context is a `bottom' context;
+it
+ cannot contain other contexts.
+
+------------------------------
+Then the following, which I don't know what to do with:
+
+ * TabVoice
+ * GregorianTranscriptionVoice
+ * GregorianTranscriptionStaff
+
+ * FretBoards
+ Engraves fretboards from chords. Not easy... Not
+documented.
+ * NoteNames
+
+ * CueVoice Not documented
+ * Global
+ Hard coded entry point for LilyPond. Cannot be tuned.
+ * Devnull
+ Silently discards all musical information given to this
+context.
+
+
+@node another thing FIXME
+@subsection another thing FIXME
+
+Another thing that is needed, is an overview of the various naming
+conventions:
+
+ scheme functions: lowercase-with-hyphens (incl. one-word
+names)
+ scheme functions: ly:plus-scheme-style
+ music events, music classes and music properties:
+as-scheme-functions
+ Grob interfaces: scheme-style
+ backend properties: scheme-style (but X and Y!)
+ contexts (and MusicExpressions and grobs): Capitalized or
+CamelCase
+ context properties: lowercaseFollowedByCamelCase
+ engravers:
+Capitalized_followed_by_lowercase_and_with_underscores
+
+Which of these are conventions and which are rules?
+Which are rules of the underlying language, and which are
+LP-specific?
+
+
+@node Input modes FIXME
+@subsection Input modes FIXME
+
+\notemode
+
+\notemode turns the front end of LilyPond into note mode
+(which is the default parsing mode).
+It's certainly useful in certain situations, for example if you
+are in \lyricmode or \chordmode or ... and want to insert
+something that only can be done with \notemode syntax.
+
+See for example
+http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00418.html
+http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00218.html
+http://lists.gnu.org/archive/html/lilypond-user/2006-12/msg00236.html
+http://lists.gnu.org/archive/html/lilypond-user/2006-11/msg00061.html
+
+
+\chords
+\drums
+\fretmode ?
+
+
+