@node Sectioning commands
@subsection Sectioning commands
-Most of the manual operates at the
+The Notation Reference uses section headings at four, occasionally
+five, levels.
+
+@itemize
+
+@item Level 1: @@chapter
+@item Level 2: @@section
+@item Level 3: @@subsection
+@item Level 4: @@unnumberedsubsubsec
+@item Level 5: @@subsubsubheading
+@end itemize
+
+The first three levels are numbered in html, the last two are not.
+Numbered sections correspond to a single html page in the split html
+documents.
+
+The first four levels always have accompanying nodes so they can be
+referenced and are also included in the ToC in html.
+
+Most of the manual is written at level 4 under headings created with
@example
@@node Foo
-@@subsubsection Foo
+@@unnumberedsubsubsec Foo
@end example
-@noindent
-level. Sections are created with
+Level 3 subsections are created with
@example
@@node Foo
No commas may be used in the node names.
@item
-If a heading is desired without creating a @code{@@node}, please use
-the following:
+If a heading is desired without creating a @code{@@node}, please use:
@example
-@@subheading Foo
+@@subsubsubheading Foo
@end example
@item
LSR snippets are linked with:
@example
-@@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+@@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
@{filename.ly@}
@end example
\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
"
@end example
-@noindent
-Then, you should get these translated strings into compiled snippets in
-@file{Documentation/snippets}, see @q{General guidelines} in @ref{Adding
-and editing snippets}.
-
@code{@@example} blocks need not be verbatim copies, e.g. variable
names, file names and comments should be translated.
don't do so, some @code{@@lilypond} snippets might be broken or make
no sense in their context.
-When you have updated texidocs in
-@file{Documentation/@var{MY-LANGUAGE}/texidocs}, you can get these
-changes into compiled snippets in @file{Documentation/snippets}, see
-@q{General guidelines} in @ref{Adding and editing snippets}.
-
Finally, a command runs the three update processes above for all
enabled languages (from @file{Documentation/}):
git rev-list HEAD |head -1
@end example
-A special case is updating Snippet documentation strings in
-@file{Documentation/@var{MY-LANGUAGE}/texidocs}. For these to be
-correctly marked as up-to-date, first run @code{makelsr.py} as
-explained in @ref{Adding and editing snippets}, and commit the
-resulting compiled snippets left in @file{Documentation/snippets/}.
-Say the SHA1 ID code of this commit is <C>. Now edit again your
-translated files in @file{Documentation/@var{MY-LANGUAGE}/texidocs}
-adjusting the 40-digit committish that appears in the text to be <C>;
-finally, commit these updated files. Not doing so would result in
-changes made both to your updates and original snippets to
-persistently appear in the check-translation output as if they were
-out of sync.
-
-This two-phase mechanism avoids the (practically) unsolvable problem
-of guessing what committish will have our update, and pretending to
-put this very committish on the files in the same commit.
-
@c http://lists.gnu.org/archive/html/lilypond-devel/2009-01/msg00245.html
@c contains a helper script which could be used to perform massive
@c committish updates.
translations to Git.
@itemize
-@item Translation changes matching master branch are preferably made on
-@code{lilypond/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
+@item Translation work is made on
+@code{translation} branch. This branch is merged on
+@code{staging} once a week, approximately. Then,
+@code{master} branch is merged on
+@code{translation}, where the check-translation script (see
+@ref{Check state of translation}) shows changes in English docs which
+should be translated, and the cycle starts again.
+
+@item Translations may be pushed directly to
+@code{staging} only if they do not break compilation of LilyPond and
+its documentation. Those changes could be pushed to
+@code{translation} too, or alternatively translators could wait until
+they come from
+@code{master} the next time it is merged on
+@code{translation}. Similarly, changes matching
@code{stable/X.Y} are preferably made on
-@code{lilypond/X.Ytranslation}.
+@code{X.Ytranslation}.
-@item @code{lilypond/translation} Git branch may be merged into
-master only if LilyPond (@command{make all}) and documentation
-(@command{make doc}) compile successfully.
+@item @code{translation} Git branch may be merged into
+@code{staging} branch 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
-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.
+@item @command{make} and @command{make doc} are usually successful in
+@code{master} Git branch because those tests should have already
+succeeded in
+@code{staging} branch before merging.
+@code{master} branch may be merged into
+@code{translation} when significant changes had been made in
+documentation in English in
+@code{master} branch.
@item General maintenance may be done by anybody who knows what he does
in documentation in all languages, without informing translators
first. General maintenance include simple text substitutions
(e.g. automated by sed), compilation fixes, updating Texinfo or
lilypond-book commands, updating macros, updating ly code, fixing
-cross-references, and operations described in @ref{Maintaining
-without updating translations}.
+cross-references, and operations described in
+@ref{Maintaining without updating translations}.
@end itemize