@@subsection @@code@{Foo@} Bar
@end example
+@item
+With the exception of @code{@@} commands, the section name must
+match the node name exactly.
+
+@item
+No commas may be used in the node names.
+
@item
If a heading is desired without creating a @code{@@node}, please use
the following:
@itemize
+@item
+Most LilyPond examples throughout the documentation can be produced
+with:
+
+@example
+@@lilypond[verbatim,quote,relative=1]
+@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
+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
+whitespace and potentially awkward page breaks in the PDFs.
+
+The preferred @code{papersize}s are @code{a5}, @code{a6} or
+@code{a8landscape}.
+
+@code{a8landscape} works best for a single measure with a single title
+and/or single @code{tagline}:
+
+@example
+@@lilypond[papersize=a8landscape,verbatim]
+\book @{
+ \header @{
+ title = "A scale in LilyPond"
+ @}
+ \relative @{
+ c d e f
+ @}
+@}
+@@end lilypond
+@end example
+
+and can also be used to easily show features that require page breaks
+(i.e. page numbers) without taking large amounts of space within the
+documentation. Do not use the @code{quote} option with this paper size.
+
+@code{a5} or @code{a6} paper sizes are best used for examples that have
+more than two measures of music or require multiple staves (i.e. to
+illustrate cross-staff features, RH and LH parts etc.) and where
+@code{\book@{@}} constructions are required or where @code{a8landscape}
+produces an example that is too cramped. Depending on the example the
+@code{quote} option may need to be omitted.
+
+In rare cases, other options may be used (or omitted), but ask first.
+
+@item
+Please avoid using extra spacing either after or within the
+@code{@@lilypond} parameters.
+
+@example
+not: @@lilypond [verbatim, quote, relative=1]
+but instead: @@lilypond[verbatim,quote,relative=1]
+@end example
+
+@item
+Inspirational headwords are produced with:
+
+@example
+@@lilypondfile[quote,ragged-right,line-width=16\cm,staffsize=16]
+@{pitches-headword.ly@}
+@end example
+
+@item
+LSR snippets are linked with:
+
+@example
+@@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
+@{filename.ly@}
+@end example
+
@item
Use two spaces for indentation in lilypond examples (no tabs).
c1^"hi"
@end example
-@item
-Most LilyPond input should be produced with:
-
-@example
-@@lilypond[verbatim,quote,relative=2]
-@end example
-
-@noindent
-or
-
-@example
-@@lilypond[verbatim,quote,relative=1]
-@end example
-
-Please avoid using extra spacing either after or within the
-@code{@@lilypond} parameters.
-
-@example
-not: @@lilypond [verbatim, quote, relative=1]
-but instead: @@lilypond[verbatim,quote,relative=1]
-@end example
-
-If you want to use @code{\layout@{@}} or define variables, use
-
-@example
-@@lilypond[verbatim,quote]
-@end example
-
-In rare cases, other options may be used (or omitted), but ask first.
-
-@item
-Inspirational headwords are produced with
-
-@example
-@@lilypondfile[quote,ragged-right,line-width=16\cm,staffsize=16]
-@{pitches-headword.ly@}
-@end example
-
-@item
-LSR snippets are linked with
-
-@example
-@@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
-@{filename.ly@}
-@end example
-
@noindent
excepted in Templates, where `doctitle' may be omitted.
\paper @{
indent = 0\mm
line-width = 160\mm - 2.0 * 0.4\in
- ragged-right = ##t
- force-assignment = #""
line-width = #(- line-width (* mm 3.000000))
@}
one section of the documentation in English with a default html
appearance.
-The script is available as:
-
-@example
-scripts/auxiliar/doc-section.sh
-@end example
-
-This script will require customization for your site if your
-LilyPond git repository is anyplace but @code{$HOME/lilypond}.
-
-Assuming that no customization is required, you can setup the
-single section build with:
-
-@example
-mkdir $HOME/lilypond/tempdocs
-cp $HOME/lilypond/Documentation/out/version.itexi $HOME/lilypond/tempdocs
-@end example
-
-You can then build a section of the documentation with:
+You can build a section of the documentation with:
@example
scripts/auxiliar/doc-section.sh MANUAL SECTION
scripts/auxiliar/doc-section.sh notation pitches
@end example
+You can then see the generated document for the section at
+
+@example
+tempdocs/pitches/out/pitches.html
+@end example
+
+According to
+@uref{http://code.google.com/p/lilypond/issues/detail?id=1236,Lilypond issue 1236},
+the location of the lilypond git tree is taken from @code{$LILYPOND_GIT}
+if specified, otherwise it is auto-detected.
+
+It is assumed that compilation takes place in the @file{build/}
+subdirectory, but this can be overridden by setting the environment
+variable @code{LILYPOND_BUILD_DIR}.
+
+Similarly, output defaults to @file{build/tempdocs/} but this can be
+overridden by setting the environment variable
+@code{LILYPOND_TEMPDOCS}.
+
This script will not work for building sections of the
Contributors' guide. For building sections of the Contributors'
Guide, use:
scripts/auxiliar/cg-section.sh doc-work
@end example
-Like @code{doc-section.sh}, @code{cg-section.sh} may need to be customized
-for your installation.
+@code{cg-section.sh} uses the same environment variables and
+corresponding default values as @code{doc-section.sh}.
@subheading Stripping whitespace and generating menus
@node Getting started with documentation translation
@subsection Getting started with documentation translation
-First, get the sources of branch @code{lilypond/translation} from the
+First, get the sources of branch @code{translation} from the
Git repository, see @ref{Starting with Git}.
@menu
@item Update sections finished in the English documentation; check
sections status at
+@smallexample
@uref{http://lilypondwiki.tuxfamily.org/index.php?title=Documentation_coordination}.
+@end smallexample
@item Update documentation PO. It is recommended not to update
strings which come from documentation that is currently deeply revised
@itemize
@item Translation changes matching master branch are preferably made on
-@code{lilypond/translation} branch; they may be pushed directly to
+@code{translation} branch; they may be pushed directly to
@code{master} only if they do not break compilation of LilyPond and
its documentation, and in this case they should be pushed to
-@code{lilypond/translation} too. Similarly, changes matching
+@code{translation} too. Similarly, changes matching
@code{stable/X.Y} are preferably made on
@code{lilypond/X.Ytranslation}.
-@item @code{lilypond/translation} Git branch may be merged into
+@item @code{translation} Git branch may be merged into
master only if LilyPond (@command{make all}) and documentation
(@command{make doc}) compile successfully.
@item @code{master} Git branch may be merged into
-@code{lilypond/translation} whenever @command{make} and @command{make
+@code{translation} whenever @command{make} and @command{make
doc} are successful (in order to ease documentation compilation by
translators), or when significant changes had been made in
documentation in English in master branch.
projects / lilypond.git / blobdiff