-DOCUMENTATION FORMATTING
-------------------------
-
-The language is called texinfo; you can see its manual here:
-http://www.gnu.org/software/texinfo/manual/texinfo/
-
-However, you don't need to read those docs. The most important
-thing to notice is that text is text. If you see a mistake in the
-text, you can fix it. If you want to change the order of
-something, you can cut-and-paste that stuff into a new location.
-
-
-%%%%% SECTIONING COMMANDS
-
-Most of the manual operates at the
- @node Foo
- @subsubsection Foo
-level. Sections are created with
- @node Foo
- @subsection Foo
-commands.
-
-* Please leave two blank lines above a @node; this makes it easier
- to find sections in texinfo.
-
-* sectioning commands (@node and @section) must not appear inside
- an @ignore. Separate those commands with a space, ie @n ode.
-
-
-
-%%%%% LILYPOND FORMATTING
-
-* Use two spaces for indentation in lilypond examples. (no tabs)
-
-* All text strings should be prefaced with #. LilyPond does not
- strictly require this, but it is helpful to get users accustomed
- to this scheme construct. ie
- \set Staff.instrumentName = #"cello"
-
-* All engravers should have double-quotes around them:
- \consists "Spans_arpeggio_engraver"
- Again, LilyPond does not strictly require this, but it is a
- useful standard to follow.
-
-* Examples should end with a complete bar if possible.
-
-* If possible, only write one bar per line. The notes on each
- line should be an independent line -- tweaks should occur on
- their own line if possible.
- Bad:
- \override textscript #'padding = #3 c1^"hi"
- Good:
- \override textscript #'padding = #3
- c1^"hi"
-
-* Most LilyPond input should be produced with:
- @lilypond[verbatim,quote,relative=2]
- or
- @lilypond[verbatim,quote,relative=1]
-
- If you want to use \layout{} or define variables, use
- @lilypond[verbatim,quote]
-
- In rare cases, other options may be used (or omitted), but ask first.
-
-* Inspirational headwords are produced with
- @lilypondfile[quote,ragged-right,line-width=16\cm,staffsize=16]
- {pitches-headword.ly}
-
-* LSR snippets are linked with
- @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
- {filename.ly}
- excepted in Templates, where `doctitle' may be omitted.
-
-* Avoid long stretches of input code. Noone is going to read them
- in print. Please create a smaller example. (the smaller
- example does not need to be minimal, however)
-
-* Specify durations for at least the first note of every bar.
-
-* If possible, end with a complete bar.
-
-* Comments should go on their own line, and be placed before the
- line(s) to which they refer.
-
-* Add extra spaces around { } marks; ie
- not: \chordmode {c e g}
- but instead: \chordmode { c e g }
-
-* If you only have one bar per line, omit bar checks. If you
- put more than one bar per line (not recommended), then include
- bar checks.
-
-* If you want to work on an example outside of the manual (for
- easier/faster processing), use this header:
-
-\paper {
- #(define dump-extents #t)
- indent = 0\mm
- line-width = 160\mm - 2.0 * 0.4\in
- ragged-right = ##t
- force-assignment = #""
- line-width = #(- line-width (* mm 3.000000))
-}
-
-\layout {
-}
-
- You may not change any of these values. If you are making an
- example demonstrating special \paper{} values, contact the
- Documentation Editor.
-
-
-%%%%% TEXT FORMATTING
-
-* Lines should be less than 72 characters long. (I personally
- recommend writing with 66-char lines, but don't bother modifying
- existing material.)
-
-* Do not use tabs.
-
-* Do not use spaces at the beginning of a line (except in @example
- or @verbatim environments), and do not use more than a single
- space between words. `makeinfo' copies the input lines verbatim
- without removing those spaces.
-
-* Use two spaces after a period.
-
-* In examples of syntax, use @var{musicexpr} for a music
- expression.
-
-* Don't use @rinternals{} in the main text. If you're tempted to
- do so, you're probably getting too close to "talking through the
- code". If you really want to refer to a context, use @code{} in
- the main text and @rinternals{} in the @seealso.
-
-* Variables or numbers which consist of a single character
- (probably followed by a punctuation mark) should be tied
- properly, either to the previous or the next word. Example:
-
- The variable@tie{}@var{a} ...
-
-* To get consistent indentation in the DVI output it is better to
- avoid the @verbatim environment. Use the @example environment
- instead if possible, but without extraneous indentation. For
- example, this
-
- @example
- foo {
- bar
- }
- @end example
-
- should be replaced with
-
- @example
- foo {
- bar
- }
- @end example
-
- where `@example' starts the line (without leading spaces).
-
-* Do not compress the input vertically; this is, do not use
-
- Beginning of logical unit
- @example
- ...
- @end example
- continuation of logical unit
-
- but
-
- Beginning of logical unit
-
- @example
- ...
- @end example
-
- @noindent
- continuation of logical unit
-
- This makes it easier to avoid forgetting the `@noindent'. Only
- use @noindent if the material is discussing the same material;
- new material should simply begin without anything special on the
- line above it.
-
-* in @itemize use @item on a separate line like this:
- @itemize
- @item
- Foo
-
- @item
- Bar
-
- Do not use @itemize @bullet.
-
-* To get LilyPond version, use @version{} (this does not work inside
- LilyPond snippets). If you write "@version{}" (enclosed with
- quotes), or generally if @version{} is not followed by a space,
- enclose it with
-
- @w{ ... }
-
- e.g.
-
- @w{"@version{}"}
-
- to prevent an ugly line break in PDF output.
-
-
-%%%%% SYNTAX SURVEY
-
-@c - single line comments
- "@c NOTE:" is a comment which should remain in the final
- version. (gp only command ;)
-@ignore ... @end ignore - multi-line comment
-
-@cindex - General index. Please add as many as you can. Don't
- capitalize the first word.
-@funindex - is for a \lilycommand.
-
-@example ... @end ignore - example text that should be set as a
- blockquote. Any {} must be escaped with @{ }@
-@itemize @item A @item B ... @end itemize - for bulleted lists.
- Do not compress vertically like this.
-
-@code{} - typeset in a tt-font. Use for actual lilypond code or
- property/context names. If the name contains a space, wrap
- the entire thing inside @w{@code{ }}.
-@notation{} - refers to pieces of notation, e.g.
- "@notation{cres.}". Also use to specific lyrics ("the
- @notation{A - men} is centered"). Only use once per subsection
- per term.
-@q{} - Single quotes. Used for `vague' terms.
-@qq{} - Double quotes. Used for actual quotes ("he said") or for
- introducing special input modes.
-
-@tie{} - Variables or numbers which consist of a single character
- (probably followed by a punctuation mark) should be tied
- properly, either to the previous or the next word. Example:
- "The letter@tie{}@q{I} is skipped"
-
-@var - Use for variables.
-@warning{} - produces a "Note: " box. Use for important messages.
-
-@bs - Generates a backslash inside @warning.
- Any `\' used inside @warning (and @q or @qq) must be written as `@bs{}'
- (texinfo would also allow \\, but this breaks with PDF output).
-
-
-
-%%%%% OTHER TEXT CONCERNS
-
-* References must occur at the end of a sentence, for more
- information see @ref{the texinfo manual}. Ideally this should
- also be the final sentence of a paragraph, but this is not
- required. Any link in a doc section must be duplicated in the
- @seealso section at the bottom.
-
-* Introducing examples must be done with
- . (ie finish the previous sentence/paragaph)
- : (ie `in this example:')
- , (ie `may add foo with the blah construct,')
- The old "sentence runs directly into the example" method is not
- allowed any more.
-
-* Abbrevs in caps, e.g., HTML, DVI, MIDI, etc.
-
-* Colon usage
-
- 1. To introduce lists
- 2. When beginning a quote: "So, he said,..."
- This usage is rarer. Americans often just use a comma.
- 3. When adding a defining example at the end of a sentence.
-
-* Non-ASCII characters which are in utf-8 should be directly used;
- this is, don't say `Ba@ss{}tuba' but `Baßtuba'. This ensures that
- all such characters appear in all output formats.
-