@node Documentation work
@chapter Documentation work
+There are currently 11 manuals for LilyPond, not including the
+translations. Each book is available in HTML, PDF, and info. The
+documentation is written in a language called @code{texinfo} --
+this allows us to generate different output formats from a single
+set of source files.
+
+To organize multiple authors working on the documentation, we use a
+Version Control System (VCS) called git, previously discussed in
+@ref{Starting with Git}.
+
@menu
* Introduction to documentation work::
* Documentation suggestions::
* Texinfo introduction and usage policy::
* Documentation policy::
* Tips for writing docs::
-* Updating docs with convert-ly::
+* Scripts to ease doc work::
+* Docstrings in scheme::
* Translating the documentation::
@end menu
of the specific chapter you wish to modify.
Developer manuals live in @file{Documentation/} too. Currently there is
-only one: the Contributors' Guide @file{contrib-guide.texi} you are
+only one: the Contributor's Guide @file{contrib-guide.texi} you are
reading.
Snippet files are part of documentation, and the Snippet List (SL) lives
@end itemize
+Nodes must be included inside a
+
+@example
+@@menu
+* foo::
+* bar::
+@@end menu
+@end example
+
+@noindent
+construct. These are easily constructed with automatic tools; see
+@ref{Scripts to ease doc work}.
+
@node LilyPond formatting
@subsection LilyPond formatting
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"
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.
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:
@example
\paper @{
- #(define dump-extents #t)
indent = 0\mm
line-width = 160\mm - 2.0 * 0.4\in
ragged-right = ##t
@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.
To get LilyPond version, use @@version@{@} (this does not work
inside LilyPond snippets). If you write "@@version@{@}" (enclosed
with quotes), or generally if @@version@{@} is not followed by a
-space, tere will be an ugly line break in PDF output unless you
+space, there will be an ugly line break in PDF output unless you
enclose it with
@example
@subsection Syntax survey
@itemize
+@item
+@@bs - Generates a backslash inside @@warning.
+ Any `\' used inside @@warning (and @@q or @@qq) must be written as `@@bs@{@}'
+ (texinfo would also allow \\, but this breaks with PDF output).
+
@item
@@c - single line comments
"@@c NOTE:" is a comment which should remain in the final
version. (gp only command ;)
-@item
-@@ignore ... @@end ignore - multi-line comment
@item
@@cindex - General index. Please add as many as you can. Don't
capitalize the first word.
+
@item
-@@funindex - is for a \lilycommand.
+@@code@{@} - typeset in a tt-font. Use for actual lilypond code or
+ property/context names. If the name contains a space, wrap
+ the entire thing inside @@w@{@@code@{ @}@}.
@item
-@@example ... @@end ignore - example text that should be set as a
+@@example ... @@end example - example text that should be set as a
blockquote. Any @{@} must be escaped with @@@{ @}@@
+
+@item
+@@funindex - is for a \lilycommand.
+
+@item
+@@ignore ... @@end ignore - multi-line comment
+
@item
@@itemize @@item
A @@item
Do not compress vertically like this.
@item
-@@code@{@} - typeset in a tt-font. Use for actual lilypond code or
- property/context names. If the name contains a space, wrap
- the entire thing inside @@w@{@@code@{ @}@}.
-@item
@@notation@{@} - refers to pieces of notation, e.g.
"@@notation@{cres.@}". Also use to specific lyrics ("the
@@notation@{A - men@} is centered"). Only use once per subsection
per term.
+
@item
@@q@{@} - Single quotes. Used for `vague' terms.
+
@item
@@qq@{@} - Double quotes. Used for actual quotes ("he said") or for
introducing special input modes.
@item
-@@tie@{@} - Variables or numbers which consist of a single character
- (probably followed by a punctuation mark) should be tied
- properly, either to the previous or the next word. Example:
- "The letter@@tie@{@}@@q@{I@} is skipped"
+@@rchanges@{@} - link to Changes.
@item
-@@var - Use for variables.
-@item
-@@warning@{@} - produces a "Note: " box. Use for important messages.
+@@rcontrib@{@} - link to Contributor's Guide.
@item
-@@bs - Generates a backslash inside @@warning.
- Any `\' used inside @@warning (and @@q or @@qq) must be written as `@@bs@{@}'
- (texinfo would also allow \\, but this breaks with PDF output).
+@@ref@{@} - link within current manual (type the exact node name inside the
+@{@}).
@item
-@@ref@{@} - normal references (type the exact node name inside the
-@{@}).
+@@ressay@{@} - link to Engraving Essay.
+
@item
-@@ruser@{@} - link to the NR.
+@@rextend@{@} - link to Extending LilyPond.
+
@item
-@@rlearning@{@} - link to the LM.
+@@rglos@{@} - link to the Music Glossary.
+
@item
-@@rglos@{@} - link to the MG.
+@@rinternals@{@} - link to the Internals Reference.
+
@item
-@@rprogram@{@} - link to the AU.
+@@rlearning@{@} - link to Learning Manual.
+
@item
@@rlsr@{@} - link to a Snippet section.
+
+@item
+@@rprogram@{@} - link to Application Usage.
+
+@item
+@@ruser@{@} - link to Notation Reference.
+
@item
-@@rinternals@{@} - link to the IR.
+@@rweb@{@} - link to General Informaion.
+
+@item
+@@tie@{@} - Variables or numbers which consist of a single character
+ (probably followed by a punctuation mark) should be tied
+ properly, either to the previous or the next word. Example:
+ "The letter@@tie@{@}@@q@{I@} is skipped"
+
@item
@@uref@{@} - link to an external url.
+@item
+@@var - Use for variables.
+
+@item
+@@version@{@} - Return the current LilyPond version string
+
+@item
+@@warning@{@} - produces a "Note: " box. Use for important messages.
+
@end itemize
Introducing examples must be done with
@example
- . (ie finish the previous sentence/paragaph)
- : (ie `in this example:')
- , (ie `may add foo with the blah construct,')
+. (ie finish the previous sentence/paragaph)
+: (ie `in this example:')
+, (ie `may add foo with the blah construct,')
@end example
-The old "sentence runs directly into the example" method is not
+The old @qq{sentence runs directly into the example} method is not
allowed any more.
@item
Application Usage:
@@rprogram@{blah@}.
+Extending LilyPond:
+@@rextend@{frob@}.
+
Installed Files:
@@file@{path/to/dir/blahz@}.
However, if you compile the documentation, a script called
check_texi_refs can help you with checking and fixing these
cross-references; for information on usage, cd into a source tree
-where documentation has been built, cd into Documentation and look
-for check-xrefs and fix-xrefs targets in 'make help' output. Note
-that you have to find yourself the source files to fix
+where documentation has been built, cd into Documentation and run:
+
+@example
+make check-xrefs
+make fix-xrefs
+@end example
+
+Note that you have to find yourself the source files to fix
cross-references in the generated documentation such as the
Internals Reference; e.g. you can grep scm/ and lily/.
+@c temporary? how long will kainhofer be used? -gp
+Also of interest may be the linkdoc checks on kainhofer.com. Be
+warned that these docs are not completely rebuilt every day, so it
+might not accurately reflect the current state of the docs.
+
+@example
+@uref{http://kainhofer.com/~lilypond/linkdoc/}
+@end example
+
@node General writing
@subsection General writing
the difficulty.
@seealso
-
@ref{Adding and editing snippets}.
-@node Updating docs with convert-ly
-@section Updating doc with @command{convert-ly}
+@node Scripts to ease doc work
+@section Scripts to ease doc work
+
+@subheading Stripping whitespace
+
+@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
+@end example
+
+
+@subheading Sectioning commands
+
+@warning{These commands add whitespace.}
+
+The emacs @code{M-x texinfo-all-menus-update} command will
+regenerate @@menu blocks. This can also be run with this
+command-line script:
+
+@example
+#!/bin/sh
+emacs $1 -batch -f texinfo-all-menus-update -f save-buffer
+@end example
+
+@noindent
+(save the above as something like @command{texinfo-menus.sh}, make
+it executable, then run @command{texinfo-menus.sh foo.itely})
+
+
+@subheading Updating doc with @command{convert-ly}
cd into @file{Documentation/} and run
+@node Docstrings in scheme
+@section Docstrings in scheme
+
+Material in the Internals reference is generated automatically
+from our source code. Any doc work on Internals therefore
+requires modifying files in @file{scm/*.scm}. Texinfo is allowed
+in these docstrings.
+
+Most documentation writers never touch these, though. If you want
+to work on them, please ask for help.
+
+
@node Translating the documentation
@section Translating the documentation
+The mailing list @code{translations@@lilynet.net} is dedicated to
+LilyPond web site and documentation translation; on this list, you will
+get support from the Translations Meister and experimented translators,
+and we regularly discuss translations issues common to all languagues.
+All people interested in LilyPond translations are invited to subscribe
+to this list regardless of the amount of their contribution, by sending
+an email to @code{translations-request@@lilynet.net} with subject
+@code{subscribe} and an empty message body.
+
@menu
* Getting started with documentation translation::
* Documentation translation details::
* Documentation translation maintenance::
* Translations management policies::
* Technical background::
-* Translation status::
@end menu
@node Getting started with documentation translation
@subsection Getting started with documentation translation
-First, get the sources from the Git repository, see @ref{Documentation
-translations source code}.
+First, get the sources from the Git repository, see
+@ref{Downloading remote branches}.
@menu
* Translation requirements::
least the documentation so that you can check the output yourself and
more quickly; if you are interested, see @ref{Compiling from source}.
-@menu
-@end menu
@node Which documentation can be translated
@unnumberedsubsubsec Which documentation can be translated
+FIXME: take into account the new web site integration in main sources.
+
The makefiles and scripts infrastructure currently supports translation
of the following documentation:
@itemize
@item documentation index (HTML);
-@item user manual and program usage -- Texinfo source, PDF and HTML
-output; Info output might be added if there is enough demand for it;
-@item the News document.
+@item the Learning Manual, the Notation Reference and Application Usage
+-- Texinfo source, PDF and HTML output; Info output might be added if
+there is enough demand for it;
+@item the Changes document.
@end itemize
-The following pieces of documentation should be added soon, by
-descending order of priority:
+Support for translating the following pieces of documentation should be
+added soon, by decreasing order of priority:
@itemize
@item automatically generated documentation: markup commands,
predefined music functions;
@item the Snippets List;
-@item the examples page;
@item the Internals Reference.
@end itemize
Before starting the real translation work, it is recommended to commit
changes you made so far to Git, so e.g. you are able to get back to
-this state of the sources easily if needed; see @ref{Sharing your
-changes}.
+this state of the sources easily if needed; see @ref{Making commits}.
@node Documentation translation details
@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
@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
-Any title which comes with one of the following commands must not be
-translated directly in the Texinfo source
+@iftex
+@vskip 12pt
+@end iftex
+@cartouche
+@b{Note:} node names and section titles are now translated directly in
+Texinfo source files. In case you have files in your working tree that
+have not been converted, please pull first, then run
@example
-@@node @@majorheading
-@@chapter @@unnumbered @@appendix @@chapheading
-@@section @@unnumberedsec @@appendixsec @@heading
-@@subsection @@unnumberedsubsec @@appendixsubsec @@subheading
-@@subsubsection @@unnumberedsubsubsec @@appendixsubsubsec @@subsubheading
-@@ref @@rglos @@ruser @@rlearning @@rprogram @@rlsr
+make -C Documentation/po doc
+export LYDOC_LOCALEDIR=Documentation/po/out-www
+export PYTHONPATH=python:python/auxiliar
+scripts/auxiliar/tely-gettext.py @var{manual.tely}
@end example
-The same applies to first argument of @code{@@r@var{manual}named}
-commands; however, the second argument @var{Bar baz} of
-@code{@@ref@{@var{Foo},@var{Bar baz},,@var{info-file}@}} and
-@code{@@r@var{manual}named@{@var{Foo},@var{Bar baz}@}} should be
-translated.
+@noindent
+This will also update files included in @file{@var{manual}.tely}, and of
+course this script can be used for individual @file{@var{foo}.itely}
+files too.
+@end cartouche
-@code{@@uref}'s names are to be translated.
+Every piece of text should be translated in the source file, except
+Texinfo comments, text in @code{@@lilypond} blocks and a few cases
+mentioned below.
-In any section which looks like
+Node names are translated, but the original node name in English should
+be kept as the argument of @code{@@translationof} put after the section
+title; that is, every piece in the original file like
@example
-@@menu
-* @var{node1}:: @var{thing1}
-* @var{node2}:: @var{thing2}
-...
-@@end menu
+@@node Foo bar
+@@@var{section_command} Bar baz
@end example
@noindent
-the node names @var{nodeN} are @emph{not} to be translated, whereas
-extra title information @var{thingN} is.
+should be translated as
-Every node name or section title must from now on be translated
-separately in a @file{.po} file (just as well as LilyPond output
-messages) in @file{Documentation/po}. The Gettext domain is named
-@code{lilypond-doc}, and unlike @code{lilypond} domain it is not
-managed through the Free Translation Project.
+@example
+@@node @var{translation of Foo bar}
+@@@var{section_command} @var{translation of Bar baz}
+@@translationof Foo bar
+@end example
+
+The argument of @code{@@rglos} commands and the first argument of
+@code{@@rglosnamed} commands must not be translated, as it is the node
+name of an entry in Music Glossary.
+
+Every time you translate a node name in a cross-reference, i.e. the
+argument of commands @code{@@ref, @@rprogram, @@rlearning, @@rlsr,
+@@ruser} or the first argument of their @code{@var{*}named} variants,
+you should make sure the target node is defined in the correct source
+file; if you do not intend to translate the target node right now, you
+should at least write the node definition (that is, the @code{@@node
+@@@var{section_commmand} @@translationof} trio mentioned above) in the
+expected source file and define all its parent nodes; for each node you
+have defined this way but have not translated, insert a line that
+contains @code{@@untranslated} and append @code{ @@c external} to the
+line that contains @code{@@translationof}. That is, you should end up
+for each untranslated node with something like
+
+@example
+@@node @var{translation of Foo bar}
+@@@var{section_command} @var{translation of Bar baz}
+@@translationof Foo bar @@c external
+
+@@untranslated
+@end example
+
+@warning{you do not have to translate the node name of a cross-reference
+to a node that you do not have translated. If you do, you must define
+an @qq{empty} node like explained just above; this will produce a
+cross-reference with the translated node name in output, although the
+target node will still be in English. On the opposite, if all
+cross-references that refer to an untranslated node use the node name in
+English, then you do not have to define such an @qq{empty} node, and the
+cross-reference text will appear in English in the output. The choice
+between these two strategies implies its particular maintenance
+requirements and is left to the translators, although the opinion of the
+Translation meister leans towards not translating these
+cross-references.}
+
+Finally, press in Emacs @key{C-c C-u C-a} to update or generate
+menus. This process should be made easier in the future, when the helper
+script @command{texi-langutils.py} and the makefile target are updated.
+
+Some pieces of text manipulated by build scripts that appear in the
+output are translated in a @file{.po} file -- just like LilyPond output
+messages -- in @file{Documentation/po}. The Gettext domain is named
+@code{lilypond-doc}, and unlike @code{lilypond} domain it is not managed
+through the Free Translation Project.
Take care of using typographic rules for your language, especially in
@file{macros.itexi}.
+If you wonder whether a word, phrase or larger piece of text should be
+translated, whether it is an argument of a Texinfo command or a small
+piece sandwiched between two Texinfo commands, try to track whether and
+where it appears in PDF and/or HTML output as visible text. This piece
+of advice is especially useful for translating @file{macros.itexi}.
Please keep verbatim copies of music snippets (in @code{@@lilypond}
blocs). However, some music snippets containing text that shows in
@end example
@noindent
-in the source, open @file{Documentation/snippets/@var{filename}.ly}, translate the
-@code{texidoc} header field it contains, enclose it with
+in the source, open @file{Documentation/snippets/@var{filename}.ly},
+translate the @code{texidoc} header field it contains, enclose it with
@code{texidoc@var{MY-LANGUAGE} = "} and @code{"}, and write it into
@file{Documentation/@var{MY-LANGUAGE}/texidocs/@var{filename}.texidoc}.
Additionnally, you may translate the snippet's title in @code{doctitle}
"
@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} blocs need not be verbatim copies, e.g. variable
names, file names and comments should be translated.
-Index entries (@code{@@cindex} and so on) should be translated.
-
Finally, please carefully apply every rule exposed in @ref{Texinfo
-introduction and usage policy}, and @ref{Documentation policy}. If
-one of these rules conflicts with a rule specific to your language,
-please ask the Translation meister and/or the Documentation Editors on
-@email{lilypond-devel@@gnu.org}.
+introduction and usage policy}, and @ref{Documentation policy}. If one
+of these rules conflicts with a rule specific to your language, please
+ask the Translation meister on @email{translations@@lilynet.net} list
+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
make CHECKED_FILES=@var{MY_LANGUAGE}/@var{manual}/@var{foo}.itely check-translation
@end example
+@noindent
+In case this file has been renamed since you last updated the
+translation, you should specify both old and new file names,
+e.g. @code{CHECKED_FILES=@var{MY_LANGUAGE}/@{@var{manual},user@}/@var{foo}.itely}.
+
To see only which files need to be updated, do
@example
counts of documentation files in this Guide.
@seealso
-
@ref{Maintaining without updating translations}.
make ISOLANG=@var{MY_LANGUAGE} update-translation
@end example
+@noindent
or to update a single file
@example
make CHECKED_FILES=@var{MY_LANGUAGE/@var{manual}/foo.itely} update-translation
@end example
-For each file to be udpated, update-translation will open your text
-editor with this file and a diff of the file in English; if the diff
-cannot be generated or is bigger than the file in English itself, the
-full file in English will be opened instead.
+For each file to be udpated, @code{update-translation} will open your
+text editor with this file and a diff of the file in English; if the
+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
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/}):
@end example
Use this command with caution, and keep in mind it will not be really
-useful until translations are stabilized after the end of GDP.
+useful until translations are stabilized after the end of GDP and GOP.
@seealso
-
-@ref{Maintaining without updating translations}.
+@ref{Maintaining without updating translations},
+@ref{Adding and editing snippets}.
@node Translations management policies
@node Maintaining without updating translations
@unnumberedsubsubsec Maintaining without updating translations
-Keeping translations up to date under heavy changes in the
-documentation in English may be almost impossible, especially as
-during the former Grand Documentation Project (GDP) or the Grand
-Organization Project (GOP) when a lot of contributors brings changes.
-In addition, transloators may be (and that) involved in these porjects too.
+Keeping translations up to date under heavy changes in the documentation
+in English may be almost impossible, especially as during the former
+Grand Documentation Project (GDP) or the Grand Organization Project
+(GOP) when a lot of contributors brings changes. In addition,
+translators may be --- and that is a very good thing --- involved in
+these projects too.
-it is possible -- and even recommended -- to
-perform some maintaining that keeps translated documentation usable
-and eases future translation updating. The rationale below the tasks
-list motivates this plan. The rationale below the tasks
-list motivates this plan.
+it is possible --- and even recommended --- to perform some maintenance
+that keeps translated documentation usable and eases future translation
+updating. The rationale below the tasks list motivates this plan.
The following tasks are listed in decreasing priority order.
English docs, which possibly involves moving nodes contents in block
between files, without updating contents itself. In other words, the
game is catching where has gone each section. In Learning manual, and
-in Notation Reference sections which have been revised in GDP, there
-may be completely new sections: in this case, copy @code{@@node} and
+in Notation Reference sections which have been revised in GDP, there may
+be completely new sections: in this case, copy @code{@@node} and
@code{@@section}-command from English docs, and add the marker for
untranslated status @code{@@untranslated} on a single line. Note that
it is not possible to exactly match subsections or subsubsections of
-documentation in English, when contents has been deeply revised; in
-this case, keep obsolete (sub)subsections in the translation, marking
-them with a line @code{@@c obsolete} just before the node.
+documentation in English, when contents has been deeply revised; in this
+case, keep obsolete (sub)subsections in the translation, marking them
+with a line @code{@@c obsolete} just before the node.
Emacs with Texinfo mode makes this step easier:
@itemize
@item without Emacs AucTeX installed, @key{C-c C-s} shows structure of current
-Texinfo file in a new buffer *Occur*; to show structure of two files
+Texinfo file in a new buffer @code{*Occur*}; to show structure of two files
simultaneously, first split Emacs window in 4 tiles (with @key{C-x 1}
and @key{C-x 2}), press @key{C-c C-s} to show structure of one file
-(e.g. the translated file), copy *Occur* contents into *Scratch*, then
-press @key{C-c C-s} for the other file.
+(e.g. the translated file), copy @code{*Occur*} contents into
+@code{*Scratch*}, then press @key{C-c C-s} for the other file.
If you happen to have installed AucTeX, you can either call the macro
by doing @key{M-x texinfo-show-structure} or create a key binding in your
@end example
@noindent
-and then obtain the structure in the *Occur* buffer with @key{C-c s}.
+and then obtain the structure in the @code{*Occur*} buffer with @key{C-c
+s}.
@item Do not bother updating @code{@@menu}s when all menu entries are in the same
-file, just do @key{C-c C-u C-a} ("update all menus") when you have
+file, just do @key{C-c C-u C-a} (@qq{update all menus}) when you have
updated all the rest of the file.
@item Moving to next or previous node using incremental search: press
Other scripts are used in the build process, in @file{scripts/build/}:
@itemize
-@item @file{html-gettext.py} -- translate node names, section titles and cross
-references in HTML files generated by @command{makeinfo},
-@item @file{texi-gettext.py} -- gettext node names, section titles and references
-before calling @command{texi2pdf},
@item @file{mass-link.py} -- link or symlink files between English documentation
and documentation in other languages.
@end itemize
@itemize
@item @file{python/langdefs.py} -- language definitions module
@end itemize
-
-
-@node Translation status
-@subsection Translation status
-
-
projects / lilypond.git / blobdiff