@menu
* Introduction to documentation work::
+* version in documentation files::
* Documentation suggestions::
* Texinfo introduction and usage policy::
* Documentation policy::
encouraged to contact the @ref{Meisters, Documentation Meister}.
+@node version in documentation files
+@section @code{\version} in documentation files
+
+Every documentation file which includes LilyPond code must begin
+with a @code{\version} statement, since the build procedure
+explicitly tests for its presence and will not continue otherwise.
+The @code{\version} statement should reference a version of LilyPond
+consistent with the syntax of the contained code.
+
+Since the @code{\version} statement is not valid Texinfo input it
+must be commented out like this:
+
+@example
+@@c \version "2.19.1"
+@end example
+
+So, if you are adding LilyPond code which is not consistent with the
+current version header, you should
+
+@enumerate
+
+@item
+run convert-ly on the file using the latest version of LilyPond
+(which should, if everybody has done proper maintenance, not change
+anything);
+
+@item
+add the new code;
+
+@item
+modify the version number to match the new code.
+
+@end enumerate
+
+
@node Documentation suggestions
@section Documentation suggestions
@emph{selected snippet} in the documentation. It will also appear
automatically in the Snippets lists. See @ref{Introduction to LSR}.
-Snippets that @emph{don't} have the @qq{docs} tage will still be
+Snippets that @emph{don't} have the @qq{docs} tag will still be
searchable and viewable within the LSR, but will be not be included in
the Snippets list or be able to be included as part of the main
documentation.
@@subsection Foo
@end example
-@itemize
-@item
Level 4 headings and menus must be preceded by level 3 headings and
menus, and so on for level 3 and level 2. If this is not what is
wanted, please use:
@@subsubsubheading Foo
@end example
-@item
Please leave two blank lines above a @code{@@node}; this makes it
easier to find sections in texinfo.
-@item
Do not use any @code{@@} commands for a @code{@@node}. They may be
used for any @code{@@sub...} sections or headings however.
@@subsection @@code@{Foo@} Bar
@end example
-@item
No punctuation may be used in the node names. If the heading text
uses punctuation (in particular, colons and commas) simply leave
this out of the node name and menu.
@@subsection Foo: Bar
@end example
-@item
-With the exception of @code{@@} commands and punctuation, the
-section name should match the node name exactly.
+Backslashes must not be used in node names or section headings.
+If the heading text should include a backslash simply leave this
+out of the node name and menu and replace it with @code{@@bs@{@}}
+in the heading text.
+
+@example
+@@menu
+* The set command
+@@end menu
+
+@@node The set command
+@@subsection The @@code@{@@bs@{@}set@} command
+@end example
+
+References to such a node may use the third argument of the
+@code{@@ref} command to display the texually correct heading.
+
+@example
+@@ref@{The set command,,The @@code@{@@bs@{@}set command@}
+@end example
+
+With the exception of @code{@@} commands, @code{\} commands and
+punctuation, the section name should match the node name exactly.
-@item
Sectioning commands (@code{@@node} and @code{@@section}) must not appear
inside an @code{@@ignore}. Separate those commands with a space, ie
@code{@@n}@tie{}@code{ode}.
-@end itemize
-
Nodes must be included inside a
@example
with:
@example
-@@lilypond[verbatim,quote,relative=1]
+@@lilypond[verbatim,quote]
@end example
-or
-
-@example
-@@lilypond[verbatim,quote,relative=2]
-@end example
-
-If using any combination of @code{\header@{@}}, @code{\score@{@}} or
-@code{\layout@{@}} in your example, then you must omit the
-@code{relative} variable and either use absolute entry mode or an
-explicit @code{\relative@{@}} construction.
-
-If using @code{\book@{@}} in your example then you must also omit the
-@code{relative} variable and either use absolute entry mode or an
-explicit @code{\relative@{@}} construction. However, you must also
+If using @code{\book@{@}} in your example then you must also
include the @code{papersize=X} variable, where @code{X} is a defined
paper size from within @file{scm/paper.scm}. This is to avoid the
default @code{a4} paper size being used and leaving too much unnecessary
@code{@@lilypond} parameters.
@example
-not: @@lilypond [verbatim, quote, relative=1]
-but instead: @@lilypond[verbatim,quote,relative=1]
+not: @@lilypond [verbatim, quote, fragment]
+but instead: @@lilypond[verbatim,quote,fragment]
@end example
@item
Staff.instrumentName = #"cello"}
@item
-Try to avoid using @code{#'} or @code{#`} within when describing
+Try to avoid using @code{#'} or @code{#`} when describing
context or layout properties outside of an @code{@@example} or @code{@@lilypond}, unless
the description explicitly requires it.
@item
Tweaks should, if possible, also occur on their own line.
@example
-not: \override TextScript #'padding = #3 c1^"hi"
-but instead: \override TextScript #'padding = #3
+not: \override TextScript.padding = #3 c1^"hi"
+but instead: \override TextScript.padding = #3
c1^"hi"
@end example
@node Special characters
@unnumberedsubsubsec Special characters
+@warning{In Texinfo, the backslash is an ordinary character, and
+is entered without escaping (e.g.
+@samp{The@tie{}@@code@{@bs{}foo@}@tie{}command}). However, within
+double-quoted Scheme and/or LilyPond strings, backslashes
+(including those ending up in Texinfo markup) need to be escaped
+by doubling them:
+@example
+(define (foo x)
+ "The @@code@{@bs{}@bs{}foo@} command..."
+ ...)
+@end example}
+
@itemize
@item
@code{--}, @code{---} --- Create an en dash (--) or an em dash
On the other side of this,
@example
-\override Score.Hairpin #'after-line-breaking = ##t
+\override Score.Hairpin.after-line-breaking = ##t
@end example
clearly belongs in LSR.
on bug-lilypond or add an issue in the tracker, then translate back the
reply from developers.
-@item @rweb{Help us}: this page should be translated very freely,
+@item @rcontrib{Help us}: this page should be translated very freely,
and possibly not at all: ask help for contributing to LilyPond for tasks
that LilyPond community in your language is able and going to handle.
@end itemize
projects / lilypond.git / blobdiff