[ << Documentation work ] | [Top][Contents][Index][ ? ] | [ Website work >> ] | ||
[ < Introduction to documentation work ] | [ Up : Documentation work ] | [ > ] |
3.2 Texinfo crash course
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.
Note: Rule of thumb: follow the examples in the existing docs.
You can learn most of what you need to know from this; if you want
to do anything fancy, discuss it on |
[ << Documentation work ] | [Top][Contents][Index][ ? ] | [ Website work >> ] | ||
[ < Texinfo crash course ] | [ Up : Texinfo crash course ] | [ > ] |
3.2.1 Sectioning commands
Most of the manual operates at the
@node Foo @subsubsection Foo
level. Sections are created with
@node Foo @subsection Foo
- 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.
[ << Documentation work ] | [Top][Contents][Index][ ? ] | [ Website work >> ] | ||
[ < ] | [ Up : Texinfo crash course ] | [ > ] |
3.2.2 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.
[ << Documentation work ] | [Top][Contents][Index][ ? ] | [ Website work >> ] | ||
[ < ] | [ Up : Texinfo crash course ] | [ > ] |
3.2.3 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 instead do
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, tere will be an ugly line break in PDF output unless you
enclose it with
@w{ ... } e.g. @w{"@version{}"}
[ << Documentation work ] | [Top][Contents][Index][ ? ] | [ Website work >> ] | ||
[ < ] | [ Up : Texinfo crash course ] | [ > ] |
3.2.4 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).
[ << Documentation work ] | [Top][Contents][Index][ ? ] | [ Website work >> ] | ||
[ < ] | [ Up : Texinfo crash course ] | [ Documentation policy > ] |
3.2.5 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
- To introduce lists
-
When beginning a quote: "So, he said,...".
This usage is rarer. Americans often just use a comma.
- 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.
[ << Documentation work ] | [Top][Contents][Index][ ? ] | [ Website work >> ] | ||
[ < ] | [ Up : Texinfo crash course ] | [ Documentation policy > ] |