Most of the manual operates at the
@node Foo
- @unnumberedsubsubsec Foo
+ @subsubsection Foo
level. Sections are created with
@node Foo
@subsection Foo
* 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 produce via
+* LilyPond input should be produced via
@lilypond[verbatim,quote,ragged-right]
with `fragment' and `relative=2' optional.
circumstances.
* Inspirational headwords are produced with
- @lilypondfile[ragged-right,line-width=16\cm,staffsize=16,quote]
+ @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.
+
+* Comments should go on their own line, and be placed before the
+ line(s) to which they refer.
+
+* 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.
+
* 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")
@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.
-
@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.
- 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)
-
-