Merge remote-tracking branch 'origin/translation'

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

diff --git a/Documentation/contributor/doc-work.itexi b/Documentation/contributor/doc-work.itexi
index e8d993703a8f9db8b6a66351afb299c28ff0422b..f0bb52e8affd176264abb1003bea3364c2c41aee 100644 (file)
--- a/Documentation/contributor/doc-work.itexi
+++ b/Documentation/contributor/doc-work.itexi
@@ -14,6 +14,7 @@ Version Control System (VCS) called git, previously discussed in
 
 @menu
 * Introduction to documentation work::
 
 @menu
 * Introduction to documentation work::

+* version in documentation files::

 * Documentation suggestions::
 * Texinfo introduction and usage policy::
 * Documentation policy::
 * Documentation suggestions::
 * Texinfo introduction and usage policy::
 * Documentation policy::


@@ -66,6 +67,41 @@ Before undertaking any large documentation work, contributors are
 encouraged to contact the @ref{Meisters, Documentation Meister}.
 
 
 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
 
 @node Documentation suggestions
 @section Documentation suggestions
 


@@ -146,20 +182,42 @@ Please prepare a formal git patch.
 
 @end enumerate
 
 
 @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
 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:
 
 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.  Thanks for your interest!
+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!

 
 
 @node Texinfo introduction and usage policy
 
 
 @node Texinfo introduction and usage policy


@@ -221,27 +279,50 @@ how to modify the snippet files and SL, see @ref{LSR work}.
 @node Sectioning commands
 @subsection Sectioning commands
 
 @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
 
 @example
 @@node Foo

-@@subsubsection Foo
+@@unnumberedsubsubsec Foo

 @end example
 
 @end example
 

-@noindent
-level.  Sections are created with
+Level 3 subsections are created with

 
 @example
 @@node Foo
 @@subsection Foo
 @end example
 
 
 @example
 @@node Foo
 @@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:
+
+@example
+@@subsubsubheading Foo
+@end example
+

 Please leave two blank lines above a @code{@@node}; this makes it
 easier to find sections in texinfo.
 
 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.
 
 Do not use any @code{@@} commands for a @code{@@node}.  They may be
 used for any @code{@@sub...} sections or headings however.
 


@@ -255,28 +336,47 @@ but instead:
 @@subsection @@code@{Foo@} Bar
 @end example
 
 @@subsection @@code@{Foo@} Bar
 @end example
 

-@item
-With the exception of @code{@@} commands, the section name must
-match the node name exactly.
+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.

 
 

-@item
-No commas may be used in the node names.
+@example
+@@menu
+* Foo Bar::
+@@end menu

 
 

-@item
-If a heading is desired without creating a @code{@@node}, please use
-the following:
+@@node Foo Bar
+@@subsection Foo: Bar
+@end example
+
+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
 
 @example

-@@subheading Foo
+@@ref@{The set command,,The @@code@{@@bs@{@}set command@}

 @end example
 
 @end example
 

-@item
+With the exception of @code{@@} commands, @code{\} commands and
+punctuation, the section name should match the node name exactly.
+

 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}.
 
 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
 Nodes must be included inside a
 
 @example


@@ -287,8 +387,8 @@ Nodes must be included inside a
 @end example
 
 @noindent
 @end example
 
 @noindent

-construct.  These are easily constructed with automatic tools; see
-@ref{Scripts to ease doc work}.
+construct.  These can be constructed with scripts:
+see @ref{Stripping whitespace and generating menus}.

 
 
 @node LilyPond formatting
 
 
 @node LilyPond formatting


@@ -400,7 +500,7 @@ to get users accustomed to this scheme construct, i.e. @code{\set
 Staff.instrumentName = #"cello"}
 
 @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.
 
 context or layout properties outside of an @code{@@example} or @code{@@lilypond}, unless
 the description explicitly requires it.
 


@@ -418,8 +518,8 @@ checks.
 @item
 Tweaks should, if possible, also occur on their own line.
 @example
 @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
 
               c1^"hi"
 @end example
 


@@ -1381,7 +1481,7 @@ good example of this.
 On the other side of this,
 
 @example
 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.
 @end example
 
 clearly belongs in LSR.


@@ -1410,7 +1510,20 @@ the difficulty.
 @node Scripts to ease doc work
 @section Scripts to ease doc work
 
 @node Scripts to ease doc work
 @section Scripts to ease doc work
 

-@subheading Building only one section of the documentation
+@menu
+* Scripts to test the documentation::
+* Scripts to create documentation::
+@end menu
+
+@node Scripts to test the documentation
+@subsection Scripts to test the documentation
+
+@menu
+* Building only one section of the documentation::
+@end menu
+
+@node Building only one section of the documentation
+@unnumberedsubsubsec Building only one section of the documentation

 
 In order to save build time, a script is available to build only
 one section of the documentation in English with a default html
 
 In order to save build time, a script is available to build only
 one section of the documentation in English with a default html


@@ -1471,10 +1584,21 @@ scripts/auxiliar/cg-section.sh doc-work
 @code{cg-section.sh} uses the same environment variables and
 corresponding default values as @code{doc-section.sh}.
 
 @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 Scripts to create documentation
+@subsection Scripts to create documentation
+
+@menu
+* Stripping whitespace and generating menus::
+* Stripping whitespace only::
+* Updating doc with convert-ly::
+@end menu
+
+@node Stripping whitespace and generating menus
+@unnumberedsubsubsec Stripping whitespace and generating menus

 
 @warning{This script assumes that the file conforms to our doc
 
 @warning{This script assumes that the file conforms to our doc

-policy; a few files still need work in this regard.}
+policy, in particular with regard to @ref{Sectioning commands};
+a few files still need work in this regard.}

 
 To automatically regenerate @code{@@menu} portions and strip
 whitespace, use:
 
 To automatically regenerate @code{@@menu} portions and strip
 whitespace, use:


@@ -1483,19 +1607,28 @@ whitespace, use:
 scripts/auxiliar/node-menuify.py @var{FILENAME}
 @end example
 
 scripts/auxiliar/node-menuify.py @var{FILENAME}
 @end example
 

+If you are adding documentation that requires new menus,
+you will need to add a blank @code{@@menu} section:

 
 

-@subheading Stripping whitespace only
+@example
+@@menu
+@@end menu
+@end example
+
+@node Stripping whitespace only
+@unnumberedsubsubsec Stripping whitespace only

 
 @c TODO: should this be documented elsewhere?  It's useful for
 @c more than just docs.
 To remove extra whitespace from the ends of lines, run
 
 @example
 
 @c TODO: should this be documented elsewhere?  It's useful for
 @c more than just docs.
 To remove extra whitespace from the ends of lines, run
 
 @example

-scripts/auxiliar/strip-whitespace.py Documentation/FILENAME
+scripts/auxiliar/strip-whitespace.py @var{FILENAME}

 @end example
 
 
 @end example
 
 

-@subheading Updating doc with @command{convert-ly}
+@node Updating doc with convert-ly
+@unnumberedsubsubsec Updating doc with @command{convert-ly}

 
 Don't.  This should be done by programmers when they add new
 features.  If you notice that it hasn't been done, complain to
 
 Don't.  This should be done by programmers when they add new
 features.  If you notice that it hasn't been done, complain to


@@ -1804,11 +1937,6 @@ Spanish translation blah
 "
 @end example
 
 "
 @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.
 
 @code{@@example} blocks need not be verbatim copies, e.g. variable
 names, file names and comments should be translated.
 


@@ -2041,6 +2169,17 @@ git rev-list HEAD |head -1
 @c contains a helper script which could be used to perform massive
 @c committish updates.
 
 @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}.
 
 @seealso
 @ref{LSR work}.