@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
they also stem from attempting to find the most effective use of
limited documentation help.
+Before undertaking any large documentation work, contributors are
+encouraged to contact the @ref{Meisters, Documentation Meister}.
+
@node Documentation suggestions
@section Documentation suggestions
@enumerate
@item
-Ask on the lilypond-devel maillist if such a rewrite is necessary;
+Ask on the lilypond-devel mailing list if such a rewrite is necessary;
somebody else might already be working on this issue!
@item
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 mailist; to avoid
+there is a strict “no top-posting” check on the mailing list; to avoid
this, add:
> I'm not top posting.
All manuals live in @file{Documentation/}.
In particular, there are four user manuals, their respective master
-source files are @file{learning.tely} (LM, Learning Manual),
-@file{notation.tely} (NR, Notation Reference),
-@file{music-glossary.tely} (MG, Music Glossary), and
-@file{lilypond-program} (AU). Each chapter is written in a separate
+source files are @file{learning@/.tely} (LM, Learning Manual),
+@file{notation@/.tely} (NR, Notation Reference),
+@file{music@/-glossary@/.tely} (MG, Music Glossary), and
+@file{lilypond@/-program} (AU). Each chapter is written in a separate
file, ending in @file{.itely} for files containing lilypond code, and
@file{.itexi} for files without lilypond code, located in a subdirectory
-associated to the manual (@file{learning/} for @file{learning.tely}, and
+associated to the manual (@file{learning/} for @file{learning@/.tely}, and
so on); list the subdirectory of each manual to determine the filename
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
@itemize
@item
-Please leave two blank lines above a @@node; this makes it
+Please leave two blank lines above a @code{@@node}; this makes it
easier to find sections in texinfo.
@item
-Sectioning commands (@@node and @@section) must not appear
-inside an @@ignore. Separate those commands with a space, ie @@n
-ode.
+Do not use any @code{@@} commands for a @code{@@node}. They may be
+used for any @code{@@sub...} sections or headings however.
+
+@example
+not:
+@@node @@code@{Foo@} Bar
+@@subsection @@code@{Foo@} Bar
+
+but instead:
+@@node Foo Bar
+@@subsection @@code@{Foo@} Bar
+@end example
+
+@item
+If a heading is desired without creating a @code{@@node}, please use
+the following:
+
+@example
+@@subheading Foo
+@end example
+
+@item
+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
+@@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
@itemize
@item
-Use two spaces for indentation in lilypond examples. (no
-tabs)
-
-@item
-All text strings should be prefaced with #. LilyPond does
-not strictly require this, but it is helpful to get users
-accustomed to this scheme construct. ie @code{\set
-Staff.instrumentName = #"cello"}
+Use two spaces for indentation in lilypond examples (no tabs).
@item
All engravers should have double-quotes around them:
\consists "Spans_arpeggio_engraver"
@end example
-Again, LilyPond does not strictly require this, but it is a useful
-standard to follow.
+LilyPond does not strictly require this, but it is a useful
+convention to follow.
@item
-Examples should end with a complete bar if possible.
+All context or layout object strings should be prefaced with @code{#}.
+Again, LilyPond does not strictly require this, but it is helpful
+to get users accustomed to this scheme construct, i.e. @code{\set
+Staff.instrumentName = #"cello"}
@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:
+Try to avoid using @code{#'} or @code{#`} within when describing
+context or layout properties outside of an @code{@@example} or @code{@@lilypond}, unless
+the description explicitly requires it.
-@example
-\override textscript #'padding = #3 c1^"hi"
-@end example
+ie @qq{...setting the @code{transparent} property leaves the object where it
+is, but makes it invisible.}
+
+@item
+If possible, only write one bar per line.
-Good:
+@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
+Tweaks should, if possible, also occur on their own line.
@example
-\override textscript #'padding = #3
-c1^"hi"
+not: \override TextScript #'padding = #3 c1^"hi"
+but instead: \override TextScript #'padding = #3
+ c1^"hi"
@end example
@item
@@lilypond[verbatim,quote,relative=1]
@end example
-If you want to use \layout@{@} or define variables, use
+If you want to use @code{\layout@{@}} or define variables, use
@example
@@lilypond[verbatim,quote]
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.
the line(s) to which they refer.
@item
-Add extra spaces around @{ @} marks; ie
+For clarity, always use @{ @} marks even if they are not technically
+required; ie
@example
-not: \chordmode @{c e g@}
+not:
+
+\context Voice \repeat unfold 2 \relative c' @{
+ c2 d
+@}
+
+but instead:
+
+\context Voice @{
+ \repeat unfold 2 @{
+ \relative c' @{
+ c2 d
+ @}
+ @}
+@}
+@end example
+
+@item
+Add a space around @{ @} marks; ie
+
+@example
+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.
+Use @{ @} marks for additional @code{\markup} format commands; ie
+
+@example
+not: c^\markup \tiny\sharp
+but instead: c^\markup @{ \tiny \sharp @}
+@end example
+
+@item
+Remove any space around @code{<} @code{>} marks; ie
+
+@example
+not: < c e g > 4
+but instead: <c e g>4
+@end example
+
+@item
+Beam, slur and tie marks should begin immediately after the first
+note with beam and phrase marks ending immediately after the last.
+
+@example
+a8(\ ais16[ b cis( d] b) cis4~ b' cis,\)
+@end example
@item
If you want to work on an example outside of the manual (for
@example
\paper @{
- #(define dump-extents #t)
indent = 0\mm
line-width = 160\mm - 2.0 * 0.4\in
ragged-right = ##t
@end example
You may not change any of these values. If you are making an
-example demonstrating special \paper@{@} values, contact the
+example demonstrating special @code{\paper@{@}} values, contact the
Documentation Editor.
@end itemize
@subsection Text formatting
@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). Also see the recommendations for fixed-width
+fonts in the @ref{Syntax survey}.
@item
Do not use tabs.
@item
Do not use spaces at the beginning of a line (except in
-@@example or @@verbatim environments), and do not use more than a
-single space between words. `makeinfo' copies the input lines
-verbatim without removing those spaces.
+@code{@@example} or @code{@@verbatim} environments), and do not
+use more than a single space between words. @q{makeinfo} copies
+the input lines verbatim without removing those spaces.
@item
Use two spaces after a period.
@item
-In examples of syntax, use @@var@{musicexpr@} for a music
-expression.
+In examples of syntax, use @code{@@var@{@var{musicexpr}@}} for a
+music expression.
+
+@item
+Don't use @code{@@rinternals@{@}} in the main text. If you're
+tempted to do so, you're probably getting too close to @qq{talking
+through the code}. If you really want to refer to a context, use
+@code{@@code@{@}} in the main text and @code{@@rinternals@{@}} in
+the @code{@@seealso}.
+@end itemize
+
+@node Syntax survey
+@subsection Syntax survey
+
+
+@menu
+* Comments::
+* Cross references::
+* External links::
+* Fixed-width font::
+* Indexing::
+* Lists::
+* Special characters::
+* Miscellany::
+@end menu
+
+
+@node Comments
+@unnumberedsubsubsec Comments
+
+@itemize
@item
-Don't use @@rinternals@{@} in the main text. If you're
-tempted to do so, you're probably getting too close to "talking
-through the code". If you really want to refer to a context, use
-@@code@{@} in the main text and @@rinternals@{@} in the @@seealso.
+@code{@@c @dots{}} --- single line comment. @samp{@@c NOTE:} is a
+comment which should remain in the final version. (gp only
+command ;)
@item
-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:
+@code{@@ignore} --- multi-line comment:
@example
-The variable@@tie@{@}@@var@{a@} ...
+@@ignore
+@dots{}
+@@end ignore
@end example
+@end itemize
+
+
+@node Cross references
+@unnumberedsubsubsec Cross references
+
+Enter the exact @code{@@node} name of the target reference between
+the brackets (eg.@tie{}@w{@samp{@@ref@{Syntax survey@}}}). Do not
+split a cross-reference across two lines -- this causes the
+cross-reference to be rendered incorrectly in html documents.
+
+@itemize
+@item
+@code{@@ref@{@dots{}@}} --- link within current manual.
+
+@item
+@code{@@rchanges@{@dots{}@}} --- link to Changes.
+
+@item
+@code{@@rcontrib@{@dots{}@}} --- link to Contributor's Guide.
+
+@item
+@code{@@ressay@{@dots{}@}} --- link to Engraving Essay.
+
+@item
+@code{@@rextend@{@dots{}@}} --- link to Extending LilyPond.
+
+@item
+@code{@@rglos@{@dots{}@}} --- link to the Music Glossary.
+
+@item
+@code{@@rinternals@{@dots{}@}} --- link to the Internals Reference.
+
+@item
+@code{@@rlearning@{@dots{}@}} --- link to Learning Manual.
@item
-To get consistent indentation in the DVI output it is better
-to avoid the @@verbatim environment. Use the @@example
-environment instead if possible, but without extraneous
-indentation. For example, this
+@code{@@rlsr@{@dots{}@}} --- link to a Snippet section.
+
+@item
+@code{@@rprogram@{@dots{}@}} --- link to Application Usage.
+
+@item
+@code{@@ruser@{@dots{}@}} --- link to Notation Reference.
+
+@item
+@code{@@rweb@{@dots{}@}} --- link to General Information.
+@end itemize
+
+
+@node External links
+@unnumberedsubsubsec External links
+
+@itemize
+@item
+@code{@@email@{@dots{}@}} --- create a @code{mailto:} E-mail link.
+
+@item
+@code{@@uref@{@var{URL}[, @var{link text}]@}} --- link to an
+external url. Use within an @code{@@example ... @@end example}.
@example
@@example
- foo @{
- bar
- @}
+@@uref@{URL [, link text ]@}
@@end example
@end example
+@end itemize
-@noindent
-should be replaced with
+
+@node Fixed-width font
+@unnumberedsubsubsec Fixed-width font
+
+@itemize
+@item
+@code{@@code@{@dots{}@}}, @code{@@samp@{@dots{}@}} ---
+
+Use the @code{@@code@{@dots{}@}} command for individual
+language-specific tokens (keywords, commands, engravers, scheme
+symbols, etc.). Ideally, a single @code{@@code@{@dots{}@}} block
+should fit within one line in the PDF output. Use the
+@code{@@samp@{@dots{}@}} command when you have a short example of
+user input, unless it constitutes an entire @code{@@item} by
+itself, in which case @code{@@code@{@dots{}@}} is preferable.
+Otherwise, both should only be used when part of a larger sentence
+within a paragraph or @code{@@item}. Never use a
+@code{@@code@{@dots{}@}} or @code{@@samp@{@dots{}@}} block as a
+free-standing paragraph; use @code{@@example} instead.
+
+A single unindented line in the PDF has space for about 79
+fixed-width characters (76 if indented). Within an @code{@@item}
+there is space for about 75 fixed-width characters. Each
+additional level of @code{@@itemize} or @code{@@enumerate}
+shortens the line by about 4 columns.
+
+However, even short blocks of @code{@@code@{@dots{}@}} and
+@code{@@samp@{@dots{}@}} can run into the margin if the Texinfo
+line-breaking algorithm gets confused. Additionally, blocks that
+are longer than this may in fact print nicely; it all depends
+where the line breaks end up. If you compile the docs yourself,
+check the PDF output to make sure the line breaks are
+satisfactory.
+
+The Texinfo setting @code{@@allowcodebreaks} is set to
+@code{false} in the manuals, so lines within
+@code{@@code@{@dots{}@}} or @code{@@samp@{@dots{}@}} blocks will
+only break at spaces, not at hyphens or underscores. If the block
+contains spaces, use @code{@@w@{@@code@{@dots{}@}@}} or
+@code{@@w@{@@samp@{@dots{}@}@}} to prevent unexpected line breaks.
+
+The Texinfo settings @code{txicodequoteundirected} and
+@code{txicodequotebacktick} are both set in the manuals, so
+backticks (@code{`}) and apostrophes (@code{'}) placed within
+blocks of @code{@@code}, @code{@@example}, or @code{@@verbatim}
+are not converted to left- and right-angled quotes
+(@code{@quoteleft{} @quoteright{}}) as they normally are within
+the text, so the apostrophes in
+@q{@w{@code{@@w@{@@code@{@bs{}relative c''@}@}}}} will display
+correctly. However, these settings do not affect the PDF output
+for anything within a @code{@@samp} block (even if it includes a
+nested @code{@@code} block), so entering
+@q{@code{@@w@{@@samp@{@bs{}relative c''@}@}}} wrongly produces
+@q{@w{@code{@bs{}relative c@quoteright{}@quoteright{}}}} in PDF.
+Consequently, if you want to use a @code{@@samp@{@dots{}@}} block
+which contains backticks or apostrophes, you should instead use
+@q{@code{@@q@{@@code@{@dots{}@}@}}} (or
+@q{@code{@@q@{@@w@{@@code@{@dots{}@}@}@}}} if the block also
+contains spaces). Note that backslashes within
+@code{@@q@{@dots{}@}} blocks must be entered as @samp{@@bs@{@}},
+so the example above would be coded as
+@q{@code{@@q@{@@w@{@@code@{@@bs@{@}relative c''@}@}@}}}.
+
+@item
+@code{@@command@{@dots{}@}} --- Use for command-line commands (eg.
+@samp{@@command@{lilypond-book@}}).
+
+@item
+@code{@@example} --- Use for examples of program code. Do not add
+extraneous indentation (ie. don't start every line with
+whitespace). Use the following layout (notice the use of blank
+lines). Omit the @code{@@noindent} if the text following the
+example starts a new paragraph:
@example
+@var{@dots{}text leading into the example@dots{}}
+
@@example
-foo @{
- bar
-@}
+@dots{}
@@end example
+
+@@noindent
+@var{continuation of the text@dots{}}
@end example
-@noindent
-where `@@example' starts the line (without leading spaces).
+Individual lines within an @code{@@example} block should not
+exceed 74 characters; otherwise they will run into the margin in
+the PDF output, and may get clipped. If an @code{@@example} block
+is part of an @code{@@item}, individual lines in the
+@code{@@example} block should not exceed 70 columns. Each
+additional level of @code{@@itemize} or @code{@@enumerate}
+shortens the line by about 4 columns.
+
+For long command line examples, if possible, use a trailing
+backslash to break up a single line, indenting the next line with
+2 spaces. If this isn't feasible, use @samp{@@smallexample
+@dots{} @@end@tie{}smallexample} instead, which uses a smaller
+fontsize. Use @code{@@example} whenever possible, but if needed,
+@code{@@smallexample} can fit up to 90 characters per line before
+running into the PDF margin. Each additional level of
+@code{@@itemize} or @code{@@enumerate} shortens a
+@code{@@smallexample} line by about 5 columns.
@item
-Do not compress the input vertically; this is, do not use
+@code{@@file@{@dots{}@}} --- Use for filenames and directories.
-@example
- Beginning of logical unit
- @@example
- ...
- @@end example
- continuation of logical unit
-@end example
+@item
+@code{@@option@{@dots{}@}} --- Use for options to command-line
+commands (eg. @samp{@@option@{--format@}}).
-@noindent
-but instead do
+@item
+@code{@@verbatim} --- Prints the block exactly as it appears in
+the source file (including whitespace, etc.). For program code
+examples, use @code{@@example} instead. @code{@@verbatim} uses
+the same format as @code{@@example}.
-@example
-Beginning of logical unit
+Individual lines within an @code{@@verbatim} block should not
+exceed 74 characters; otherwise they will run into the margin in
+the PDF output, and may get clipped. If an @code{@@verbatim}
+block is part of an @code{@@item}, individual lines in the
+@code{@@verbatim} block should not exceed 70 columns. Each
+additional level of @code{@@itemize} or @code{@@enumerate}
+shortens the line by about 4 columns.
+@end itemize
-@@example
-...
-@@end example
-@@noindent
-continuation of logical unit
-@end example
+@node Indexing
+@unnumberedsubsubsec Indexing
+
+@itemize
+@item
+@code{@@cindex @dots{}} --- General index. Please add as many as you can.
+Don't capitalize the first word.
+
+@item
+@code{@@funindex @dots{}} --- is for a \lilycommand.
+@end itemize
-This makes it easier to avoid forgetting the `@@noindent'. Only
-use @@noindent if the material is discussing the same material;
-new material should simply begin without anything special on the
-line above it.
+@node Lists
+@unnumberedsubsubsec Lists
+
+@itemize
@item
-in @@itemize use @@item
-on a separate line like this:
+@code{@@enumerate} --- Create an ordered list (with numbers).
+Always put @samp{@@item} on its own line, and separate consecutive
+items with a blank line:
@example
-@@itemize
+@@enumerate
@@item
Foo
@@item
Bar
+@@end enumerate
@end example
-Do not use @@itemize @@bullet.
-
@item
-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
-enclose it with
-
-@example
-@@w@{ ... @}
-
- e.g.
-
-@@w@{"@@version@{@}"@}
-@end example
-
+@code{@@itemize} --- Create an unordered list (with bullets). Use
+the same format as @code{@@enumerate}. Do not use
+@samp{@@itemize@tie{}@@bullet}.
@end itemize
-@node Syntax survey
-@subsection Syntax survey
+@node Special characters
+@unnumberedsubsubsec Special characters
@itemize
@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
+@code{--}, @code{---} --- Create an en dash (--) or an em dash
+(---) in the text. To print two or three literal hyphens in a
+row, wrap one of them in a @code{@@w@{@dots{}@}} (eg.
+@samp{-@@w@{-@}-}).
@item
-@@cindex - General index. Please add as many as you can. Don't
- capitalize the first word.
-@item
-@@funindex - is for a \lilycommand.
+@code{@@@@}, @code{@@@{}, @code{@@@}} --- Create an at-sign (@@),
+a left curly bracket (@{), or a right curly bracket (@}).
@item
-@@example ... @@end ignore - example text that should be set as a
- blockquote. Any @{@} must be escaped with @@@{ @}@@
-@item
-@@itemize @@item
-A @@item
-B ... @@end itemize - for bulleted lists.
- Do not compress vertically like this.
+@code{@@bs@{@}} --- Create a backslash within a
+@code{@@q@{@dots{}@}}, @code{@@qq@{@dots{}@}}, or
+@code{@@warning@{@dots{}@}} block. This is a custom LilyPond
+macro, not a builtin @@-command in Texinfo. Texinfo would also
+allow @samp{\\}, but this breaks the PDF output.
@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.
+@code{@@tie@{@}} --- Create a @emph{variable-width} non-breaking
+space in the text (use @w{@samp{@@w@{ @}}} for a single
+@emph{fixed-width} non-breaking space). 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: @samp{The letter@@tie@{@}@@q@{I@} is
+skipped}
+@end itemize
-@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
-@@var - Use for variables.
-@item
-@@warning@{@} - produces a "Note: " box. Use for important messages.
+@node Miscellany
+@unnumberedsubsubsec Miscellany
+@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).
+@code{@@notation@{@dots{}@}} --- refers to pieces of notation, e.g.
+@samp{@@notation@{clef@}}. Also use for specific lyrics
+(@samp{the @@notation@{A@tie{}-@tie{}men@} is centered}).
+Only use once per subsection per term.
@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.
+@code{@@q@{@dots{}@}} --- Single quotes. Used for
+@quoteleft{}vague@quoteright{} terms. To get a backslash
+(\), you must use @samp{@@bs@{@}}.
+
@item
-@@rprogram@{@} - link to the AU.
+@code{@@qq@{@dots{}@}} --- Double quotes. Used for actual quotes
+(@qq{he said}) or for introducing special input modes. To get a
+backslash (\), you must use @samp{@@bs@{@}}.
+
@item
-@@rlsr@{@} - link to a Snippet section.
+@code{@@var@{@dots{}@}} --- Use for variables.
+
@item
-@@rinternals@{@} - link to the IR.
+@code{@@version@{@}} --- Return the current LilyPond version
+string. Use @samp{@@w@{@@version@{@}@}} if it's at the end of a
+line (to prevent an ugly line break in PDF); use
+@samp{@@w@{"@@version@{@}"@}} if you need it in quotes.
+
@item
-@@uref@{@} - link to an external url.
+@code{@@w@{@dots{}@}} --- Do not allow any line breaks.
+@item
+@code{@@warning@{@dots{}@}} --- produces a @qq{Note:@tie{}} box.
+Use for important messages. To get a backslash (\), you must use
+@samp{@@bs@{@}}.
@end itemize
-
@node Other text concerns
@subsection Other text concerns
@itemize
-
@item
References must occur at the end of a sentence, for more
-information see @@ref@{the texinfo manual@}. Ideally this should
-also be the final sentence of a paragraph, but this is not
-required. Any link in a doc section must be duplicated in the
-@@seealso section at the bottom.
+information see the
+@uref{http://www.gnu.org/software/texinfo/manual/texinfo/,texinfo
+manual}. Ideally this should also be the final sentence of a
+paragraph, but this is not required. Any link in a doc section
+must be duplicated in the @code{@@seealso} section at the bottom.
@item
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/paragraph)
+: (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
Colon usage
@enumerate
-
@item
To introduce lists
@item
-When beginning a quote: "So, he said,...".
+When beginning a quote: @qq{So, he said,...}.
This usage is rarer. Americans often just use a comma.
@item
When adding a defining example at the end of a sentence.
-
@end enumerate
@item
Non-ASCII characters which are in utf-8 should be directly used;
-this is, don't say `Ba@@ss@{@}tuba' but `Baßtuba'. This ensures
-that all such characters appear in all output formats.
-
+this is, don't say @samp{Ba@@ss@{@}tuba} but @samp{Baßtuba}. This
+ensures that all such characters appear in all output formats.
@end itemize
-
-
@node Documentation policy
@section Documentation policy
Application Usage:
@@rprogram@{blah@}.
+Extending LilyPond:
+@@rextend@{frob@}.
+
Installed Files:
@@file@{path/to/dir/blahz@}.
manual.
@item
-@@predefined ... @@endpredefined is for commands in ly/*-init.ly
-FIXME?
+@@predefined ... @@endpredefined is for commands in
+@file{ly/@/*-init@/.ly}
@item
Do not include any real info in second-level sections (ie 1.1
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 languages.
+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::
@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::
translate the documentation. However, if you have enough time and
motivation and a suitable system, it can be very useful to build at
least the documentation so that you can check the output yourself and
-more quickly; if you are interested, see @ref{Compiling from source}.
+more quickly; if you are interested, see @ref{Compiling}.
+
+Before undertaking any large translation work, contributors are
+encouraged to contact the @ref{Meisters, Translation Meister}.
-@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
where @var{MY-LANGUAGE} is the ISO 639 language code.
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}.
+@file{python/@/langdefs@/.py}.
@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
-
-@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
+In addition, not listed above, Snippets' titles and descriptions
+should be translated; they are a part of the Notation Reference and
+therefore their priority is 5.
-@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
@@@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
+contains @code{@@untranslated}. 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
+@@translationof Foo bar
@@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 personally 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.
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
+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}.
+@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},
+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}
+@file{Documentation/@/@var{MY-LANGUAGE}/@/texidocs/@/@var{filename}@/.texidoc}.
+Additionally, you may translate the snippet's title in @code{doctitle}
header field, in case @code{doctitle} is a fragment option used in
@code{@@lilypondfile}; you can do this exactly the same way as
@code{texidoc}. For instance,
-@file{Documentation/@var{MY-LANGUAGE}/texidocs/@var{filename}.texidoc}
+@file{Documentation/@/@var{MY-LANGUAGE}/@/texidocs/@/@var{filename}@/.texidoc}
may contain
@example
@noindent
Then, you should get these translated strings into compiled snippets in
-@file{Documentation/snippets}, see @q{General guidelines} in @ref{Adding
+@file{Documentation/@/snippets}, see @q{General guidelines} in @ref{Adding
and editing snippets}.
-@code{@@example} blocs need not be verbatim copies, e.g. variable
+@code{@@example} blocks need not be verbatim copies, e.g. variable
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 Adding a Texinfo manual
+@unnumberedsubsubsec Adding a Texinfo manual
-@node Translating the Notation Reference and Application Usage
-@unnumberedsubsubsec Translating the Notation Reference and Application Usage
+In order to start translating a new manual whose basename is @var{FOO},
+do
-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.
+@example
+cd Documentation/@var{MY-LANGUAGE}
+cp ../@var{FOO}.tely .
+mkdir @var{FOO}
+cp web/GNUmakefile @var{FOO}
+@end example
+@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}:
-@node Translating the Documentation index index.html.in
-@unnumberedsubsubsec Translating the Documentation index @file{index.html.in}
+@example
+cd Documentation/
+make ISOLANG=@var{MY-LANGUAGE} TEXI_LANGUTIL_FLAGS=--head-only skeleton-update
+@end example
-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.
+@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::
+* 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
+
Global state of the translation is recorded in
-@file{Documentation/translations.html.in}, which is used to generate
+@file{Documentation/@/translations@/.itexi}, which is used to generate
Translations status page. To update that page, do from
@file{Documentation/}
make translation-status
@end example
-This will also leave @file{out/translations-status.txt}, which contains
+This will also leave @file{out/@/translations@/-status@/.txt}, which contains
up-to-dateness percentages for each translated file, and update word
counts of documentation files in this Guide.
@seealso
-
@ref{Maintaining without updating translations}.
-
@node Updating documentation translation
@unnumberedsubsubsec Updating documentation translation
make CHECKED_FILES=@var{MY_LANGUAGE/@var{manual}/foo.itely} update-translation
@end example
-For each file to be udpated, @code{update-translation} will open your
+For each file to be updated, @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.
+@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
@end example
-@file{.po} message catalogs in @file{Documentation/po/} may be updated
-by issuing from @file{Documentation/} or @file{Documentation/po/}
+@file{.po} message catalogs in @file{Documentation/@/po/} may be updated
+by issuing from @file{Documentation/} or @file{Documentation/@/po/}
@example
make po-update
@end example
This script overwrites music snippets in
-@file{@var{MY_LANGUAGE/foo/every.itely}} with music snippets from
-@file{@var{foo/every.itely}}. It ignores skeleton files, and keeps
+@file{@var{MY_LANGUAGE/@/foo/@/every@/.itely}} with music snippets from
+@file{@var{foo/@/every@/.itely}}. It ignores skeleton files, and keeps
intact music snippets preceded with a line starting with @code{@@c
KEEP LY}; it reports an error for each @file{.itely} that has not the
same music snippet count in both languages. Always use this script
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
+@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
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
+
+A special case is updating Snippet documentation strings in
+@file{Documentation/@/@var{MY-LANGUAGE}/@/texidocs}. For these to be
+correctly marked as up-to-date, first run @code{makelsr.py} as
+explained in @ref{Adding and editing snippets}, and commit the
+resulting compiled snippets left in @file{Documentation/@/snippets/}.
+Say the SHA1 ID code of this commit is <C>. Now edit again your
+translated files in @file{Documentation/@/@var{MY-LANGUAGE}/@/texidocs}
+adjusting the 40-digit committish that appears in the text to be <C>;
+finally, commit these updated files. Not doing so would result in
+changes made both to your updates and original snippets to
+persistently appear in the check-translation output as if they were
+out of sync.
+
+This two-phase mechanism avoids the (practically) unsolvable problem
+of guessing what committish will have our update, and pretending to
+put this very committish on the files in the same commit.
+
+@c http://lists.gnu.org/archive/html/lilypond-devel/2009-01/msg00245.html
+@c contains a helper script which could be used to perform massive
+@c committish updates.
+
+
+@seealso
+@ref{LSR work}.
+
@node Translations management policies
@subsection Translations management policies
no longer uses this macro.
@item Update @file{*.tely} files completely with
-@command{make check-translation} -- you may want to redirect ouptput
+@command{make check-translation} -- you may want to redirect output
to a file because of overwhelming output, or call check-translation.py
on individual files, see @ref{Check state of translation}.
@end example
@noindent
-This step requires a sucessful documentation build (with @command{make
+This step requires a successful documentation build (with @command{make
doc}). Some cross-references are broken because they point to a node
that exists in the documentation in English, which has not been added
to the translation; in this case, do not fix the cross-reference but
@item @code{lilypond/translation} Git branch may be merged into
master only if LilyPond (@command{make all}) and documentation
-(@command{make doc}) compile succesfully.
+(@command{make doc}) compile successfully.
@item @code{master} Git branch may be merged into
@code{lilypond/translation} whenever @command{make} and @command{make
-doc} are succesful (in order to ease documentation compilation by
+doc} are successful (in order to ease documentation compilation by
translators), or when significant changes had been made in
documentation in English in master branch.
A number of Python scripts handle a part of the documentation
translation process. All scripts used to maintain the translations
-are located in @file{scripts/auxiliar/}.
+are located in @file{scripts/@/auxiliar/}.
@itemize
@item @file{check_translation.py} -- show diff to update a translation,
"makeinfo --html" has been dropped.
@end itemize
-Other scripts are used in the build process, in @file{scripts/build/}:
+Other scripts are used in the build process, in @file{scripts/@/build/}:
@itemize
@item @file{mass-link.py} -- link or symlink files between English documentation
and documentation in other languages.
@end itemize
-Python modules used by scripts in @file{scripts/auxiliar/} or @file{scripts/build/} (but
-not by installed Python scripts) are located in @file{python/auxiliar/}:
+Python modules used by scripts in @file{scripts/@/auxiliar/} or @file{scripts/@/build/} (but
+not by installed Python scripts) are located in @file{python/@/auxiliar/}:
@itemize
@item @file{manuals_definitions.py} -- define manual names and name of
cross-reference Texinfo macros,
@item @file{buildlib.py} -- common functions (read piped output
of a shell command, use Git),
-@item @file{postprocess_html.py} (module imported by @file{www_post.py}) -- add footer and
+@item @file{postprocess_html.py} (module imported by @file{www_post@/.py}) -- add footer and
tweak links in HTML pages.
@end itemize
projects / lilypond.git / blobdiff