Most of the manual operates at the
@node Foo
- @unnumberedsubsubsec 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.
* 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.
+ 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.
+* 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]
- Examples about page layout may alter the quote/ragged-right
- options. Omitting `verbatim' is not allowed except for special
- circumstances.
+ 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]
+ @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:
* 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:
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
Do not compress vertically like this.
@code{} - typeset in a tt-font. Use for actual lilypond code or
- property/context names.
+ 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")
+ @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").
-
-@warning{}: produces a "Note: " box. Use for important
- messages.
+@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
"The letter@tie{}@q{I} is skipped"
@var - Use for variables.
-@warning{} - produces a "Note: " box.
- Any `\' used inside this must be written as `\\'.
+@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).
required. Any link in a doc section must be duplicated in the
@seealso section at the bottom.
-* Introducing examples may be done with
+* 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.
this is, don't say `Ba@ss{}tuba' but `Baßtuba'. This ensures that
all such characters appear in all output formats.
-* Don't use a @ref{link to another section} in the middle of a
- sentence. It looks ok in HTML, moderately bad in PDF, and
- utterly horrible in INFO. Instead, reword the sentence so that
- users are encouraged to see @ref{link to another section}.
- (at the end of the sentence)
-
-