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.

* 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"

* LilyPond input should be produced via
    @lilypond[verbatim,quote,ragged-right]
  with `fragment' and `relative=2' optional.

  Examples about page layout may alter the quote/ragged-right
  options.  Omitting `verbatim' is not allowed except for special
  circumstances.

* 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]
  {filename.ly}

* 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.

* 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.

* 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.
@notation{} - refers to pieces of notation, e.g.
  "@notation{cres.}".  Also use to specific lyrics ("the
  @notation{A - men} is centered")
@q{} - Single quotes. Used for `vague' terms.
@qq{} - Double quotes.  Used for actual quotes ("he said").

@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.