Doc: how to update committishes of .texidoc files at once (issue 3485)

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

diff --git a/Documentation/contributor/doc-work.itexi b/Documentation/contributor/doc-work.itexi
index e8d993703a8f9db8b6a66351afb299c28ff0422b..bd7a4aa317e9b8082044abcbd00347b688bd498a 100644 (file)
--- a/Documentation/contributor/doc-work.itexi
+++ b/Documentation/contributor/doc-work.itexi
@@ -146,20 +146,42 @@ Please prepare a formal git patch.
 
 @end enumerate
 
+@subheading Contributions that contain examples using overrides
+
+Examples that use overrides, tweaks, customer Scheme functions etc. are
+(with very few exceptions) not included in the main text of the manuals;
+as there would be far too many, equally useful, candidates.
+
+The correct way is to submit your example, with appropriate explanatory
+text and tags, to the LilyPond Snippet Repository (LSR).  Snippets that
+have the @qq{docs} tag can then be easily added as a
+@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
+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.
+
+Generally, any new snippets that have the @qq{docs} tag are more
+carefully checked for syntax and formatting.
+
+@subheading Announcing your snippet
+
 Once you have followed these guidelines, please send a message to
 lilypond-devel with your documentation submissions.  Unfortunately
-there is a strict “no top-posting” check on the mailing list; to avoid
+there is a strict @q{no top-posting} check on the mailing list; to avoid
 this, add:
 
-> I'm not top posting.
+@code{> I'm not top posting}
+
+(you must include the > ) to the top of your documentation addition.
 
-(you must include the > ) to the top of your documentation
-addition.
+We may edit your suggestion for spelling, grammar, or style, and we may
+not place the material exactly where you suggested, but if you give us
+some material to work with, we can improve the manual much faster.
 
-We may edit your suggestion for spelling, grammar, or style, and
-we may not place the material exactly where you suggested, but if
-you give us some material to work with, we can improve the manual
-much faster.  Thanks for your interest!
+Thanks for your interest!
 
 
 @node Texinfo introduction and usage policy
@@ -221,15 +243,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 +303,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 +1843,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.
 
@@ -2041,6 +2075,17 @@ git rev-list HEAD |head -1
 @c contains a helper script which could be used to perform massive
 @c committish updates.
 
+Most of the changes in the LSR snippets included in the documentation concern
+the syntax, not the description inside @code{texidoc=""}.  This implies that
+quite often you will have to update only the committish of the matching
+.texidoc file.  This can be a tedious work if there are many snippets to be
+marked as up do date.  You can use the following command to update the
+committishes at once:
+
+@example
+cd Documentation/LANG/texidocs
+sed -i -r 's/[0-9a-z]@{40@}/NEW-COMMITTISH/' *.texidoc
+@end example
 
 @seealso
 @ref{LSR work}.