@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::
-* Translating the documentation::
+* Introduction to documentation work::
+* Documentation suggestions::
+* Texinfo introduction and usage policy::
+* Documentation policy::
+* Tips for writing docs::
+* Scripts to ease doc work::
+* Docstrings in scheme::
+* Translating the documentation::
@end menu
@section Texinfo introduction and usage policy
@menu
-* Texinfo introduction::
-* Documentation files::
-* Sectioning commands::
-* LilyPond formatting::
-* Text formatting::
-* Syntax survey::
-* Other text concerns::
+* Texinfo introduction::
+* Documentation files::
+* Sectioning commands::
+* LilyPond formatting::
+* Text formatting::
+* Syntax survey::
+* Other text concerns::
@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 example
@noindent
-construct. These are easily constructed with the emacs
-@code{M-x texinfo-all-menus-update} construct, or by 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})
+construct. These are easily constructed with automatic tools; see
+@ref{Scripts to ease doc work}.
@node 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 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
-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:
+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:
@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
-@@rinternals@{@} - link to the IR.
+@@ruser@{@} - link to Notation Reference.
+
+@item
+@@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
@section Documentation policy
@menu
-* Books::
-* Section organization::
-* Checking cross-references::
-* General writing::
-* Technical writing style::
+* Books::
+* Section organization::
+* Checking cross-references::
+* General writing::
+* Technical writing style::
@end menu
@node Books
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. Unless mentioned explicitly
+or except if a translations coordinator contacts you privately, you
+should send questions, remarks, patches to this list
+@code{translations@@lilynet.net}; especially note that the traffic is so
+high on English-speaking list @code{lilypond-user@@gnu.org} that it may
+take months before your request or contribution is handled if you send a
+email to these lists.
+
@menu
-* Getting started with documentation translation::
-* Documentation translation details::
-* Documentation translation maintenance::
-* Translations management policies::
-* Technical background::
+* Getting started with documentation translation::
+* Documentation translation details::
+* Documentation translation maintenance::
+* Translations management policies::
+* Technical background::
@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 of branch @code{lilypond/translation} from the
+Git repository, see @ref{Starting with Git}.
@menu
-* Translation requirements::
-* Which documentation can be translated::
-* Starting translation in a new language::
+* Translation requirements::
+* Which documentation can be translated::
+* Starting translation in a new language::
@end menu
@node 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
of the following documentation:
@itemize
-@item documentation index (HTML);
-@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 web site, 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
Finally, add a language definition for your language in
@file{python/langdefs.py}.
-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}.
-
@node Documentation translation details
@subsection Documentation translation details
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::
+* Files to be translated::
+* 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
-
-@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
-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
-
-@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
+@node Translating the Web site and other Texinfo documentation
+@unnumberedsubsubsec Translating the Web site and other Texinfo documentation
Every piece of text should be translated in the source file, except
Texinfo comments, text in @code{@@lilypond} blocks and a few cases
@@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.}
+
+Please think of the fact that it may not make sense translating
+everything in some Texinfo files, and you may take distance from the
+original text; for instance, in the translation of the web site section
+Community, you may take this into account depending on what you know the
+community in your language is willing to support, which is possible only
+if you personnally assume this support, or there exists a public forum
+or mailing list listed in Community for LilyPond in your language:
+
+@itemize
+@item @rweb{Bug reports}: this page should be translated only if you
+know that every bug report sent on your language's mailing list or forum
+will be handled by someone who will translate it to English and send it
+on bug-lilypond or add an issue in the tracker, then translate back the
+reply from developers.
+
+@item @rweb{Help us}: this page should be translated very freely,
+and possibly not at all: ask help for contributing to LilyPond for tasks
+that LilyPond community in your language is able and going to handle.
+@end itemize
+
@noindent
+In any case, please mark in your work the sections which do not result
+from the direct translation of a piece of English translation, using
+comments i.e. lines starting with @q{@code{@@c}}.
+
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.
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
names, file names and comments 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
easier. These helper scripts make use of the power of Git, the
version control system used for LilyPond development.
+You should use them whenever you would like to update the translation in
+your language, which you may do at the frequency that fits your and your
+cotranslators' respective available times. In the case your translation
+is up-do-date (which you can discover in the first subsection below), it
+is enough to check its state every one or two weeks. If you feel
+overwhelmed by the quantity of documentation to be updated, see
+@ref{Maintaining without updating translations}.
+
@menu
-* Check state of translation::
-* Updating documentation translation::
+* Check state of translation::
+* Updating documentation translation::
+* Updating translation committishes::
@end menu
+@macro seeCommittishesUpdate{}
+@warning{do not forget to update the committish in each file you have
+completely updated, see @ref{Updating translation committishes}.}
+@end macro
+
@node Check state of translation
@unnumberedsubsubsec Check state of translation
-First pull from Git, then cd into @file{Documentation/} (or at top of
-the source tree, replace @command{make} with @command{make -C
+First pull from Git -- see @ref{Pulling and rebasing}, but DO NOT rebase
+unless you are sure to master the translation state checking and
+updating system -- then cd into @file{Documentation/} (or at top of the
+source tree, replace @command{make} with @command{make -C
Documentation}) and run
@example
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
make ISOLANG=@var{MY_LANGUAGE} NO_COLOR=1 check-translation
@end example
+You can see the diffs generated by the commands above as changes that
+you should make in your language to the existing translation, in order
+to make your translation up to date.
+
+@seeCommittishesUpdate
+
+@warning{translation status generation is currently broken, so
+translation status pages have been removed; it will be regenerated again
+as soon as possible, in Texinfo format.}
+
Global state of the translation is recorded in
@file{Documentation/translations.html.in}, which is used to generate
Translations status page. To update that page, do from
counts of documentation files in this Guide.
@seealso
-
@ref{Maintaining without updating translations}.
diff cannot be generated or is bigger than the file in English itself,
the full file in English will be opened instead.
+@seeCommittishesUpdate
+
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
useful until translations are stabilized after the end of GDP and GOP.
@seealso
-
@ref{Maintaining without updating translations},
@ref{Adding and editing snippets}.
+@node Updating translation committishes
+@unnumberedsubsubsec Updating translation committishes
+
+At the beginning of each translated file except PO files, there is a
+committish which represents the revision of the sources which you have
+used to translate this file from the file in English.
+
+When you have pulled and updated a translation, it is very important to
+update this committish in the files you have completely updated (and
+only these); to do this, first commit possible changes to any
+documentation in English which you are sure to have done in your
+translation as well, then replace in the up-to-date translated files the
+old committish by the committish of latest commit, which can be obtained
+by doing
+
+@example
+git rev-list HEAD |head -1
+@end example
+
+
@node Translations management policies
@subsection Translations management policies
coordinators work efficiently.
@menu
-* Maintaining without updating translations::
-* Managing documentation translation with Git::
+* Maintaining without updating translations::
+* Managing documentation translation with Git::
@end menu
@node Maintaining without updating translations
projects / lilypond.git / blobdiff