Merge remote-tracking branch 'origin/translation' into master

[lilypond.git] / Documentation / contributor / doc-work.itexi

diff --git a/Documentation/contributor/doc-work.itexi b/Documentation/contributor/doc-work.itexi
index cdf0e26f8d518de9487f8198bc53f7c3054ad0ff..ff6e0f07216048a90c71e31019fe01f0e79370a4 100644 (file)
--- a/Documentation/contributor/doc-work.itexi
+++ b/Documentation/contributor/doc-work.itexi
@@ -221,15 +221,33 @@ how to modify the snippet files and SL, see @ref{LSR work}.
 @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
@@ -263,11 +281,10 @@ match the node name exactly.
 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
@@ -1804,11 +1821,6 @@ Spanish translation blah
 "
 @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.
 
@@ -2003,11 +2015,6 @@ the changes it made with @command{git diff} before committing; if you
 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/}):
 
@@ -2042,23 +2049,6 @@ by doing
 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.