@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::
* Documentation policy::
* Tips for writing docs::
* Updating docs with convert-ly::
+* 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
@example
\paper @{
- #(define dump-extents #t)
indent = 0\mm
line-width = 160\mm - 2.0 * 0.4\in
ragged-right = ##t
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
@@funindex - is for a \lilycommand.
@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
@@itemize @@item
A @@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
@@var - Use for variables.
+
@item
@@warning@{@} - produces a "Note: " box. Use for important messages.
@item
@@ref@{@} - normal references (type the exact node name inside the
@{@}).
+
@item
@@ruser@{@} - link to the NR.
+
@item
@@rlearning@{@} - link to the LM.
+
@item
@@rglos@{@} - link to the MG.
+
@item
@@rprogram@{@} - link to the AU.
+
@item
@@rlsr@{@} - link to a Snippet section.
+
@item
@@rinternals@{@} - link to the IR.
+
@item
@@uref@{@} - link to an external url.
the difficulty.
@seealso
-
@ref{Adding and editing snippets}.
+@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::
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:
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
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}.
useful until translations are stabilized after the end of GDP and GOP.
@seealso
-
@ref{Maintaining without updating translations},
@ref{Adding and editing snippets}.
projects / lilypond.git / blobdiff