Docs: update translations script and instructions in the CG

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

diff --git a/Documentation/contributor/doc-work.itexi b/Documentation/contributor/doc-work.itexi
index 24ff967f4fa9f5e09a97509040ca8ced9e8bd081..67f23b573249554d1c9c1d4b15a447697e6fca64 100644 (file)
--- a/Documentation/contributor/doc-work.itexi
+++ b/Documentation/contributor/doc-work.itexi
@@ -279,12 +279,16 @@ Again, LilyPond does not strictly require this, but it is a useful
 standard to follow.
 
 @item
-Examples should end with a complete bar if possible.
+If possible, only write one bar per line.
 
 @item
-If possible, only write one bar per line.  The notes on each
-line should be an independent line -- tweaks should occur on their
-own line if possible.  Bad:
+If you only have one bar per line, omit bar checks.  If you
+must put more than one bar per line (not recommended), then include bar
+checks.
+
+@item
+Tweaks should, if possible, also occur on their own line.
+Bad:
 
 @example
 \override textscript #'padding = #3 c1^"hi"
@@ -339,9 +343,9 @@ LSR snippets are linked with
 excepted in Templates, where `doctitle' may be omitted.
 
 @item
-Avoid long stretches of input code.  Noone is going to read
-them in print.  Please create a smaller example.  (the smaller
-example does not need to be minimal, however)
+Avoid long stretches of input code.  Nobody is going to read
+them in print.  Create small examples. However, this does not mean
+it has be minimal.
 
 @item
 Specify durations for at least the first note of every bar.
@@ -361,11 +365,6 @@ not:          \chordmode @{c e g@}
 but instead:  \chordmode @{ c e g @}
 @end example
 
-@item
-If you only have one bar per line, omit bar checks.  If you
-put more than one bar per line (not recommended), then include bar
-checks.
-
 @item
 If you want to work on an example outside of the manual (for
 easier/faster processing), use this header:
@@ -396,9 +395,9 @@ Documentation Editor.
 @itemize
 
 @item
-Lines should be less than 72 characters long.  (I personally
-recommend writing with 66-char lines, but don't bother modifying
-existing material.)
+Lines should be less than 72 characters long.  (We personally
+recommend writing with 66-char lines, but do not bother modifying
+existing material).
 
 @item
 Do not use tabs.
@@ -1281,9 +1280,8 @@ All files should be encoded in UTF-8.
 
 @menu
 * Files to be translated::
-* Translating the Learning Manual and other Texinfo documentation::
-* Translating the Notation Reference and Application Usage::
-* Translating the Documentation index index.html.in::
+* Translating the Web site and other Texinfo documentation::
+* Adding a Texinfo manual::
 @end menu
 
 @node Files to be translated
@@ -1291,8 +1289,8 @@ All files should be encoded in UTF-8.
 
 @include contributor/doc-translation-list.itexi
 
-@node Translating the Learning Manual and other Texinfo documentation
-@unnumberedsubsubsec Translating the Learning Manual and other Texinfo documentation
+@node Translating the Web site and other Texinfo documentation
+@unnumberedsubsubsec Translating the Web site and other Texinfo documentation
 
 @iftex
 @vskip 12pt
@@ -1453,22 +1451,32 @@ and/or the Documentation Editors on @email{lilypond-devel@@gnu.org}
 list.
 
 
-@node Translating the Notation Reference and Application Usage
-@unnumberedsubsubsec Translating the Notation Reference and Application Usage
+@node Adding a Texinfo manual
+@unnumberedsubsubsec Adding a Texinfo manual
 
-Copy @file{notation.tely} (or @file{application.tely},
-respectively) into @file{@var{MY-LANGUAGE}}, then translate this
-file and run @code{skeleton-update} -- see @ref{Updating documentation
-translation}.  Your are now ready to translate the Notation Reference
-(Application Usage, respectively) exactly like the Learning Manual.
+In order to start translating a new manual whose basename is @var{FOO},
+do
 
+@example
+cd Documentation/@var{MY-LANGUAGE}
+cp ../@var{FOO}.tely .
+mkdir @var{FOO}
+cp web/GNUmakefile @var{FOO}
+@end example
 
-@node Translating the Documentation index index.html.in
-@unnumberedsubsubsec Translating the Documentation index @file{index.html.in}
+@noindent
+then append @var{FOO} to variable @code{SUBDIRS} in
+Documentation/@var{MY-LANGUAGE}/GNUmakefile, then translate file
+@var{MY-LANGUAGE}/@var{FOO}.tely and run @code{skeleton-update}:
 
-Unlike almost all HTML pages in this documentation, links in this page
-are not tweaked by @file{postprocess_html.py}, so links should be
-manually edited to link to existing translations.
+@example
+cd Documentation/
+make ISOLANG=@var{MY-LANGUAGE} TEXI_LANGUTIL_FLAGS=--head-only skeleton-update
+@end example
+
+@noindent
+Your are now ready to translate the new manual exactly like the web site
+or the Learning Manual.
 
 
 @node Documentation translation maintenance
@@ -1563,9 +1571,9 @@ diff cannot be generated or is bigger than the file in English itself,
 the full file in English will be opened instead.
 
 Texinfo skeleton files, i.e. @file{.itely} files not yet translated,
-containing only the Texinfo structure can be updated automatically:
-whenever @command{make check-translation} shows that such files should
-be updated, run from @file{Documentation/}
+containing only the first node of the original file in English can be
+updated automatically: whenever @command{make check-translation} shows
+that such files should be updated, run from @file{Documentation/}
 
 @example
 make ISOLANG=@var{MY_LANGUAGE} skeleton-update