1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @node Documentation work
3 @chapter Documentation work
5 There are currently 11 manuals for LilyPond, not including the
6 translations. Each book is available in HTML, PDF, and info. The
7 documentation is written in a language called @code{texinfo} --
8 this allows us to generate different output formats from a single
11 To organize multiple authors working on the documentation, we use a
12 Version Control System (VCS) called git, previously discussed in
13 @ref{Starting with Git}.
16 * Introduction to documentation work::
17 * Documentation suggestions::
18 * Texinfo introduction and usage policy::
19 * Documentation policy::
20 * Tips for writing docs::
21 * Scripts to ease doc work::
22 * Docstrings in scheme::
23 * Translating the documentation::
27 @node Introduction to documentation work
28 @section Introduction to documentation work
30 Our documentation tries to adhere to our @ref{Documentation
31 policy}. This policy contains a few items which may seem odd.
32 One policy in particular is often questioned by potential
33 contributors: we do not repeat material in the Notation Reference,
34 and instead provide links to the @qq{definitive} presentation of
35 that information. Some people point out, with good reason, that
36 this makes the documentation harder to read. If we repeated
37 certain information in relevant places, readers would be less
38 likely to miss that information.
40 That reasoning is sound, but we have two counter-arguments.
41 First, the Notation Reference -- one of @emph{five} manuals for
42 users to read -- is already over 500 pages long. If we repeated
43 material, we could easily exceed 1000 pages! Second, and much
44 more importantly, LilyPond is an evolving project. New features
45 are added, bugs are fixed, and bugs are discovered and documented.
46 If features are discussed in multiple places, the documentation
47 team must find every instance. Since the manual is so large, it
48 is impossible for one person to have the location of every piece
49 of information memorized, so any attempt to update the
50 documentation will invariably omit a few places. This second
51 concern is not at all theoretical; the documentation used to be
52 plagued with inconsistent information.
54 If the documentation were targeted for a specific version -- say,
55 LilyPond 2.10.5 -- and we had unlimited resources to spend on
56 documentation, then we could avoid this second problem. But since
57 LilyPond evolves (and that is a very good thing!), and since we
58 have quite limited resources, this policy remains in place.
60 A few other policies (such as not permitting the use of tweaks in
61 the main portion of NR 1+2) may also seem counter-intuitive, but
62 they also stem from attempting to find the most effective use of
63 limited documentation help.
66 @node Documentation suggestions
67 @section Documentation suggestions
69 @subheading Small additions
71 For additions to the documentation,
76 Tell us where the addition should be placed. Please include both
77 the section number and title (i.e. "LM 2.13 Printing lyrics").
80 Please write exact changes to the text.
83 A formal patch to the source code is @emph{not} required; we can
84 take care of the technical details. Here is an example of a
85 perfect documentation report:
88 To: lilypond-devel@gnu.org
89 From: helpful-user@example.net
92 In LM 2.13 (printing lyrics), above the last line ("More options,
93 like..."), please add:
96 To add lyrics to a divided part, use blah blah blah. For example,
99 \notes {blah <<blah>> }
100 \lyrics {blah <<blah>> }
105 In addition, the second sentence of the first paragraph is
106 confusing. Please delete that sentence (it begins "Users
107 often...") and replace it with this:
109 To align lyrics with something, do this thing.
119 @subheading Larger contributions
121 To replace large sections of the documentation, the guidelines are
122 stricter. We cannot remove parts of the current documentation
123 unless we are certain that the new version is an improvement.
128 Ask on the lilypond-devel maillist if such a rewrite is necessary;
129 somebody else might already be working on this issue!
132 Split your work into small sections; this makes it much easier to
133 compare the new and old documentation.
136 Please prepare a formal git patch.
140 Once you have followed these guidelines, please send a message to
141 lilypond-devel with your documentation submissions. Unfortunately
142 there is a strict “no top-posting” check on the mailist; to avoid
145 > I'm not top posting.
147 (you must include the > ) to the top of your documentation
150 We may edit your suggestion for spelling, grammar, or style, and
151 we may not place the material exactly where you suggested, but if
152 you give us some material to work with, we can improve the manual
153 much faster. Thanks for your interest!
156 @node Texinfo introduction and usage policy
157 @section Texinfo introduction and usage policy
160 * Texinfo introduction::
161 * Documentation files::
162 * Sectioning commands::
163 * LilyPond formatting::
166 * Other text concerns::
170 @node Texinfo introduction
171 @subsection Texinfo introduction
173 The language is called Texinfo; you can see its manual here:
175 @uref{http://www.gnu.org/software/texinfo/manual/texinfo/}
177 However, you don't need to read those docs. The most important
178 thing to notice is that text is text. If you see a mistake in the
179 text, you can fix it. If you want to change the order of
180 something, you can cut-and-paste that stuff into a new location.
182 @warning{Rule of thumb: follow the examples in the existing docs.
183 You can learn most of what you need to know from this; if you want
184 to do anything fancy, discuss it on @code{lilypond-devel} first.}
187 @node Documentation files
188 @subsection Documentation files
190 All manuals live in @file{Documentation/}.
192 In particular, there are four user manuals, their respective master
193 source files are @file{learning.tely} (LM, Learning Manual),
194 @file{notation.tely} (NR, Notation Reference),
195 @file{music-glossary.tely} (MG, Music Glossary), and
196 @file{lilypond-program} (AU). Each chapter is written in a separate
197 file, ending in @file{.itely} for files containing lilypond code, and
198 @file{.itexi} for files without lilypond code, located in a subdirectory
199 associated to the manual (@file{learning/} for @file{learning.tely}, and
200 so on); list the subdirectory of each manual to determine the filename
201 of the specific chapter you wish to modify.
203 Developer manuals live in @file{Documentation/} too. Currently there is
204 only one: the Contributor's Guide @file{contrib-guide.texi} you are
207 Snippet files are part of documentation, and the Snippet List (SL) lives
208 in @file{Documentation/} just like the manuals. For information about
209 how to modify the snippet files and SL, see @ref{LSR work}.
212 @node Sectioning commands
213 @subsection Sectioning commands
215 Most of the manual operates at the
223 level. Sections are created with
232 Please leave two blank lines above a @@node; this makes it
233 easier to find sections in texinfo.
236 If a heading is desired without creating a node, please use
244 Sectioning commands (@@node and @@section) must not appear
245 inside an @@ignore. Separate those commands with a space, ie
250 Nodes must be included inside a
260 construct. These are easily constructed with automatic tools; see
261 @ref{Scripts to ease doc work}.
264 @node LilyPond formatting
265 @subsection LilyPond formatting
270 Use two spaces for indentation in lilypond examples. (no
274 All text strings should be prefaced with #. LilyPond does
275 not strictly require this, but it is helpful to get users
276 accustomed to this scheme construct. ie @code{\set
277 Staff.instrumentName = #"cello"}
280 All engravers should have double-quotes around them:
283 \consists "Spans_arpeggio_engraver"
286 Again, LilyPond does not strictly require this, but it is a useful
290 If possible, only write one bar per line.
293 If you only have one bar per line, omit bar checks. If you
294 must put more than one bar per line (not recommended), then include bar
298 Tweaks should, if possible, also occur on their own line.
300 not: \override TextScript #'padding = #3 c1^"hi"
301 but instead: \override TextScript #'padding = #3
306 Most LilyPond input should be produced with:
309 @@lilypond[verbatim,quote,relative=2]
316 @@lilypond[verbatim,quote,relative=1]
319 If you want to use @code{\layout@{@}} or define variables, use
322 @@lilypond[verbatim,quote]
325 In rare cases, other options may be used (or omitted), but ask first.
328 Inspirational headwords are produced with
331 @@lilypondfile[quote,ragged-right,line-width=16\cm,staffsize=16]
332 @{pitches-headword.ly@}
336 LSR snippets are linked with
339 @@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
344 excepted in Templates, where `doctitle' may be omitted.
347 Avoid long stretches of input code. Nobody is going to read
348 them in print. Create small examples. However, this does not mean
352 Specify durations for at least the first note of every bar.
355 If possible, end with a complete bar.
358 Comments should go on their own line, and be placed before
359 the line(s) to which they refer.
362 For clarity, always use @{ @} marks even if they are not technically
368 \context Voice \repeat unfold 2 \relative c' @{
384 Add a space around @{ @} marks; ie
387 not: \chordmode@{c e g@}
388 but instead: \chordmode @{ c e g @}
392 Use @{ @} marks for additional @code{\markup} format comands; ie
395 not: c^\markup \tiny\sharp
396 but instead: c^\markup @{ \tiny \sharp @}
400 Remove any space around @code{<} @code{>} marks; ie
404 but instead: <c e g>4
408 Beam, slur and tie marks should begin immediately after the first
409 note with beam and phrase marks ending immediately after the last.
412 a8(\ ais16[ b cis( d] b) cis4~ b' cis,\)
416 If you want to work on an example outside of the manual (for
417 easier/faster processing), use this header:
422 line-width = 160\mm - 2.0 * 0.4\in
424 force-assignment = #""
425 line-width = #(- line-width (* mm 3.000000))
432 You may not change any of these values. If you are making an
433 example demonstrating special @code{\paper@{@}} values, contact the
434 Documentation Editor.
439 @node Text formatting
440 @subsection Text formatting
444 Lines should be less than 72 characters long. (We personally
445 recommend writing with 66-char lines, but do not bother modifying
446 existing material). Also see the recommendations for fixed-width
447 fonts in the @ref{Syntax survey}.
453 Do not use spaces at the beginning of a line (except in
454 @code{@@example} or @code{@@verbatim} environments), and do not
455 use more than a single space between words. @q{makeinfo} copies
456 the input lines verbatim without removing those spaces.
459 Use two spaces after a period.
462 In examples of syntax, use @code{@@var@{@var{musicexpr}@}} for a
466 Don't use @code{@@rinternals@{@}} in the main text. If you're
467 tempted to do so, you're probably getting too close to @qq{talking
468 through the code}. If you really want to refer to a context, use
469 @code{@@code@{@}} in the main text and @code{@@rinternals@{@}} in
470 the @code{@@seealso}.
475 @subsection Syntax survey
485 * Special characters::
491 @unnumberedsubsubsec Comments
495 @code{@@c @dots{}} --- single line comment. @samp{@@c NOTE:} is a
496 comment which should remain in the final version. (gp only
500 @code{@@ignore} --- multi-line comment:
510 @node Cross references
511 @unnumberedsubsubsec Cross references
513 Enter the exact @code{@@node} name of the target reference between
514 the brackets (eg.@tie{}@w{@samp{@@ref@{Syntax survey@}}}).
518 @code{@@ref@{@dots{}@}} --- link within current manual.
521 @code{@@rchanges@{@dots{}@}} --- link to Changes.
524 @code{@@rcontrib@{@dots{}@}} --- link to Contributor's Guide.
527 @code{@@ressay@{@dots{}@}} --- link to Engraving Essay.
530 @code{@@rextend@{@dots{}@}} --- link to Extending LilyPond.
533 @code{@@rglos@{@dots{}@}} --- link to the Music Glossary.
536 @code{@@rinternals@{@dots{}@}} --- link to the Internals Reference.
539 @code{@@rlearning@{@dots{}@}} --- link to Learning Manual.
542 @code{@@rlsr@{@dots{}@}} --- link to a Snippet section.
545 @code{@@rprogram@{@dots{}@}} --- link to Application Usage.
548 @code{@@ruser@{@dots{}@}} --- link to Notation Reference.
551 @code{@@rweb@{@dots{}@}} --- link to General Informaion.
556 @unnumberedsubsubsec External links
560 @code{@@email@{@dots{}@}} --- create a @code{mailto:} E-mail link.
563 @code{@@uref@{@var{URL}[, @var{link text}]@}} --- link to an
564 external url. Use within an @code{@@example ... @@end example}.
568 @@uref@{URL [, link text ]@}
574 @node Fixed-width font
575 @unnumberedsubsubsec Fixed-width font
579 @code{@@code@{@dots{}@}}, @code{@@samp@{@dots{}@}} ---
581 Use the @code{@@code@{@dots{}@}} command for individual
582 language-specific tokens (keywords, commands, engravers, scheme
583 symbols, etc.). Ideally, a single @code{@@code@{@dots{}@}} block
584 should fit within one line in the PDF output. Use the
585 @code{@@samp@{@dots{}@}} command when you have a short example of
586 user input, unless it constitutes an entire @code{@@item} by
587 itself, in which case @code{@@code@{@dots{}@}} is preferable.
588 Otherwise, both should only be used when part of a larger sentence
589 within a paragraph or @code{@@item}. Never use a
590 @code{@@code@{@dots{}@}} or @code{@@samp@{@dots{}@}} block as a
591 free-standing paragraph; use @code{@@example} instead.
593 A single unindented line in the PDF has space for about 79
594 fixed-width characters (76 if indented). Within an @code{@@item}
595 there is space for about 75 fixed-width characters. Each
596 additional level of @code{@@itemize} or @code{@@enumerate}
597 shortens the line by about 4 columns.
599 However, even short blocks of @code{@@code@{@dots{}@}} and
600 @code{@@samp@{@dots{}@}} can run into the margin if the Texinfo
601 line-breaking algorithm gets confused. Additionally, blocks that
602 are longer than this may in fact print nicely; it all depends
603 where the line breaks end up. If you compile the docs yourself,
604 check the PDF output to make sure the line breaks are
607 The Texinfo setting @code{@@allowcodebreaks} is set to
608 @code{false} in the manuals, so lines within
609 @code{@@code@{@dots{}@}} or @code{@@samp@{@dots{}@}} blocks will
610 only break at spaces, not at hyphens or underscores. If the block
611 contains spaces, use @code{@@w@{@@code@{@dots{}@}@}} or
612 @code{@@w@{@@samp@{@dots{}@}@}} to prevent unexpected line breaks.
614 The Texinfo settings @code{txicodequoteundirected} and
615 @code{txicodequotebacktick} are both set in the manuals, so
616 backticks (@code{`}) and apostrophes (@code{'}) placed within
617 blocks of @code{@@code}, @code{@@example}, or @code{@@verbatim}
618 are not converted to left- and right-angled quotes
619 (@code{@quoteleft{} @quoteright{}}) as they normally are within
620 the text, so the apostrophes in
621 @q{@w{@code{@@w@{@@code@{@bs{}relative c''@}@}}}} will display
622 correctly. However, these settings do not affect the PDF output
623 for anything within a @code{@@samp} block (even if it includes a
624 nested @code{@@code} block), so entering
625 @q{@code{@@w@{@@samp@{@bs{}relative c''@}@}}} wrongly produces
626 @q{@w{@code{@bs{}relative c@quoteright{}@quoteright{}}}} in PDF.
627 Consequently, if you want to use a @code{@@samp@{@dots{}@}} block
628 which contains backticks or apostrophes, you should instead use
629 @q{@code{@@q@{@@code@{@dots{}@}@}}} (or
630 @q{@code{@@q@{@@w@{@@code@{@dots{}@}@}@}}} if the block also
631 contains spaces). Note that backslashes within
632 @code{@@q@{@dots{}@}} blocks must be entered as @samp{@@bs@{@}},
633 so the example above would be coded as
634 @q{@code{@@q@{@@w@{@@code@{@@bs@{@}relative c''@}@}@}}}.
637 @code{@@command@{@dots{}@}} --- Use for command-line commands (eg.
638 @samp{@@command@{lilypond-book@}}).
641 @code{@@example} --- Use for examples of program code. Do not add
642 extraneous indentation (ie. don't start every line with
643 whitespace). Use the following layout (notice the use of blank
644 lines). Omit the @code{@@noindent} if the text following the
645 example starts a new paragraph:
648 @var{@dots{}text leading into the example@dots{}}
655 @var{continuation of the text@dots{}}
658 Individual lines within an @code{@@example} block should not
659 exceed 74 characters; otherwise they will run into the margin in
660 the PDF output, and may get clipped. If an @code{@@example} block
661 is part of an @code{@@item}, individual lines in the
662 @code{@@example} block should not exceed 70 columns. Each
663 additional level of @code{@@itemize} or @code{@@enumerate}
664 shortens the line by about 4 columns.
666 For long command line examples, if possible, use a trailing
667 backslash to break up a single line, indenting the next line with
668 2 spaces. If this isn't feasible, use @samp{@@smallexample
669 @dots{} @@end@tie{}smallexample} instead, which uses a smaller
670 fontsize. Use @code{@@example} whenever possible, but if needed,
671 @code{@@smallexample} can fit up to 90 characters per line before
672 running into the PDF margin. Each additional level of
673 @code{@@itemize} or @code{@@enumerate} shortens a
674 @code{@@smallexample} line by about 5 columns.
677 @code{@@file@{@dots{}@}} --- Use for filenames and directories.
680 @code{@@option@{@dots{}@}} --- Use for options to command-line
681 commands (eg. @samp{@@option@{--format@}}).
684 @code{@@verbatim} --- Prints the block exactly as it appears in
685 the source file (including whitespace, etc.). For program code
686 examples, use @code{@@example} instead. @code{@@verbatim} uses
687 the same format as @code{@@example}.
689 Individual lines within an @code{@@verbatim} block should not
690 exceed 74 characters; otherwise they will run into the margin in
691 the PDF output, and may get clipped. If an @code{@@verbatim}
692 block is part of an @code{@@item}, individual lines in the
693 @code{@@verbatim} block should not exceed 70 columns. Each
694 additional level of @code{@@itemize} or @code{@@enumerate}
695 shortens the line by about 4 columns.
700 @unnumberedsubsubsec Indexing
704 @code{@@cindex @dots{}} --- General index. Please add as many as you can.
705 Don't capitalize the first word.
708 @code{@@funindex @dots{}} --- is for a \lilycommand.
713 @unnumberedsubsubsec Lists
717 @code{@@enumerate} --- Create an ordered list (with numbers).
718 Always put @samp{@@item} on its own line, and separate consecutive
719 items with a blank line:
732 @code{@@itemize} --- Create an unordered list (with bullets). Use
733 the same format as @code{@@enumerate}. Do not use
734 @samp{@@itemize@tie{}@@bullet}.
738 @node Special characters
739 @unnumberedsubsubsec Special characters
743 @code{--}, @code{---} --- Create an en dash (--) or an em dash
744 (---) in the text. To print two or three literal hyphens in a
745 row, wrap one of them in a @code{@@w@{@dots{}@}} (eg.
749 @code{@@@@}, @code{@@@{}, @code{@@@}} --- Create an at-sign (@@),
750 a left curly bracket (@{), or a right curly bracket (@}).
753 @code{@@bs@{@}} --- Create a backslash within a
754 @code{@@q@{@dots{}@}}, @code{@@qq@{@dots{}@}}, or
755 @code{@@warning@{@dots{}@}} block. This is a custom LilyPond
756 macro, not a builtin @@-command in Texinfo. Texinfo would also
757 allow @samp{\\}, but this breaks the PDF output.
760 @code{@@tie@{@}} --- Create a @emph{variable-width} non-breaking
761 space in the text (use @w{@samp{@@w@{ @}}} for a single
762 @emph{fixed-width} non-breaking space). Variables or numbers
763 which consist of a single character (probably followed by a
764 punctuation mark) should be tied properly, either to the previous
765 or the next word. Example: @samp{The letter@@tie@{@}@@q@{I@} is
771 @unnumberedsubsubsec Miscellany
775 @code{@@notation@{@dots{}@}} --- refers to pieces of notation, e.g.
776 @samp{@@notation@{clef@}}. Also use for specific lyrics
777 (@samp{the @@notation@{A@tie{}-@tie{}men@} is centered}).
778 Only use once per subsection per term.
781 @code{@@q@{@dots{}@}} --- Single quotes. Used for
782 @quoteleft{}vague@quoteright{} terms. To get a backslash
783 (\), you must use @samp{@@bs@{@}}.
786 @code{@@qq@{@dots{}@}} --- Double quotes. Used for actual quotes
787 (@qq{he said}) or for introducing special input modes. To get a
788 backslash (\), you must use @samp{@@bs@{@}}.
791 @code{@@var@{@dots{}@}} --- Use for variables.
794 @code{@@version@{@}} --- Return the current LilyPond version
795 string. Use @samp{@@w@{@@version@{@}@}} if it's at the end of a
796 line (to prevent an ugly line break in PDF); use
797 @samp{@@w@{"@@version@{@}"@}} if you need it in quotes.
800 @code{@@w@{@dots{}@}} --- Do not allow any line breaks.
803 @code{@@warning@{@dots{}@}} --- produces a @qq{Note:@tie{}} box.
804 Use for important messages. To get a backslash (\), you must use
809 @node Other text concerns
810 @subsection Other text concerns
814 References must occur at the end of a sentence, for more
816 @uref{http://www.gnu.org/software/texinfo/manual/texinfo/,texinfo
817 manual}. Ideally this should also be the final sentence of a
818 paragraph, but this is not required. Any link in a doc section
819 must be duplicated in the @code{@@seealso} section at the bottom.
822 Introducing examples must be done with
825 . (ie finish the previous sentence/paragaph)
826 : (ie `in this example:')
827 , (ie `may add foo with the blah construct,')
830 The old @qq{sentence runs directly into the example} method is not
834 Abbrevs in caps, e.g., HTML, DVI, MIDI, etc.
844 When beginning a quote: @qq{So, he said,...}.
846 This usage is rarer. Americans often just use a comma.
849 When adding a defining example at the end of a sentence.
853 Non-ASCII characters which are in utf-8 should be directly used;
854 this is, don't say @samp{Ba@@ss@{@}tuba} but @samp{Baßtuba}. This
855 ensures that all such characters appear in all output formats.
859 @node Documentation policy
860 @section Documentation policy
864 * Section organization::
865 * Checking cross-references::
867 * Technical writing style::
873 There are four parts to the documentation: the Learning Manual,
874 the Notation Reference, the Program Reference, and the Music
882 The LM is written in a tutorial style which introduces the most
883 important concepts, structure and syntax of the elements of a
884 LilyPond score in a carefully graded sequence of steps.
885 Explanations of all musical concepts used in the Manual can be
886 found in the Music Glossary, and readers are assumed to have no
887 prior knowledge of LilyPond. The objective is to take readers to
888 a level where the Notation Reference can be understood and
889 employed to both adapt the templates in the Appendix to their
890 needs and to begin to construct their own scores. Commonly used
891 tweaks are introduced and explained. Examples are provided
892 throughout which, while being focussed on the topic being
893 introduced, are long enough to seem real in order to retain the
894 readers' interest. Each example builds on the previous material,
895 and comments are used liberally. Every new aspect is thoroughly
896 explained before it is used.
898 Users are encouraged to read the complete Learning Manual from
903 Notation Reference: a (hopefully complete) description of LilyPond
904 input notation. Some material from here may be duplicated in the
905 Learning Manual (for teaching), but consider the NR to be the
906 "definitive" description of each notation element, with the LM
907 being an "extra". The goal is _not_ to provide a step-by-step
908 learning environment -- do not avoid using notation that has not
909 be introduced previously in the NR (for example, use \break if
910 appropriate). This section is written in formal technical writing
913 Avoid duplication. Although users are not expected to read this
914 manual from start to finish, they should be familiar with the
915 material in the Learning Manual (particularly ``Fundamental
916 Concepts''), so do not repeat that material in each section of
917 this book. Also watch out for common constructs, like ^ - _ for
918 directions -- those are explained in NR 3. In NR 1, you can
919 write: DYNAMICS may be manually placed above or below the staff,
920 see @@ref@{Controlling direction and placement@}.
922 Most tweaks should be added to LSR and not placed directly in the
923 .itely file. In some cases, tweaks may be placed in the main
924 text, but ask about this first.
926 Finally, you should assume that users know what the notation
927 means; explaining musical concepts happens in the Music Glossary.
931 Application Usage: information about using the program lilypond
932 with other programs (lilypond-book, operating systems, GUIs,
933 convert-ly, etc). This section is written in formal technical
936 Users are not expected to read this manual from start to finish.
940 Music Glossary: information about the music notation itself.
941 Explanations and translations about notation terms go here.
943 Users are not expected to read this manual from start to finish.
946 Internals Reference: not really a documentation book, since it is
947 automagically generated from the source, but this is its name.
952 @node Section organization
953 @subsection Section organization
958 The order of headings inside documentation sections should
971 You @emph{must} include a @@seealso.
975 The order of items inside the @@seealso section is
984 @@rlearning@{foozle@}.
997 @@file@{path/to/dir/blahz@}.
999 Snippets: @@rlsr@{section@}.
1001 Internals Reference:
1002 @@rinternals@{fazzle@},
1003 @@rinternals@{booar@}.
1007 If there are multiple entries, separate them by commas but do not
1011 Always end with a period.
1014 Place each link on a new line as above; this makes it much easier
1015 to add or remove links. In the output, they appear on a single
1018 ("Snippets" is REQUIRED; the others are optional)
1021 Any new concepts or links which require an explanation should go
1022 as a full sentence(s) in the main text.
1025 Don't insert an empty line between @@seealso and the first entry!
1026 Otherwise there is excessive vertical space in the PDF output.
1031 To create links, use @@ref@{@} if the link is within the same
1035 @@predefined ... @@endpredefined is for commands in
1039 Do not include any real info in second-level sections (ie 1.1
1040 Pitches). A first-level section may have introductory material,
1041 but other than that all material goes into third-level sections
1042 (ie 1.1.1 Writing Pitches).
1047 @node Checking cross-references
1048 @subsection Checking cross-references
1050 Cross-references between different manuals are heavily used in the
1051 documentation, but they are not checked during compilation.
1052 However, if you compile the documentation, a script called
1053 check_texi_refs can help you with checking and fixing these
1054 cross-references; for information on usage, cd into a source tree
1055 where documentation has been built, cd into Documentation and run:
1062 Note that you have to find yourself the source files to fix
1063 cross-references in the generated documentation such as the
1064 Internals Reference; e.g. you can grep scm/ and lily/.
1066 @c temporary? how long will kainhofer be used? -gp
1067 Also of interest may be the linkdoc checks on kainhofer.com. Be
1068 warned that these docs are not completely rebuilt every day, so it
1069 might not accurately reflect the current state of the docs.
1072 @uref{http://kainhofer.com/~lilypond/linkdoc/}
1076 @node General writing
1077 @subsection General writing
1082 Do not forget to create @@cindex entries for new sections of text.
1083 Enter commands with @@funindex, i.e.
1086 @@cindex pitches, writing in different octaves
1087 @@funindex \relative
1091 do not bother with the @@code@{@} (they are added automatically).
1092 These items are added to both the command index and the unified
1095 Both index commands should go in front of the actual material.
1097 @@cindex entries should not be capitalized, ie
1100 @@cindex time signature
1104 is preferred instead of @qq{Time signature}, Only use capital
1105 letters for musical terms which demand them, like D.S. al Fine.
1107 For scheme functions, only include the final part, i.e.,
1110 @@funindex modern-voice-cautionary
1112 @@funindex #(set-accidental-style modern-voice-cautionary)
1121 In general, use the American spellings. The internal lilypond
1122 property names use this spelling.
1125 List of specific terms:
1129 simultaneous NOT concurrent
1130 measure: the unit of music
1131 bar line: the symbol delimiting a measure NOT barline
1132 note head NOT notehead
1133 chord construct NOT chord (when referring to <>)
1141 @node Technical writing style
1142 @subsection Technical writing style
1144 These refer to the NR. The LM uses a more gentle, colloquial
1150 Do not refer to LilyPond in the text. The reader knows what the
1151 manual is about. If you do, capitalization is LilyPond.
1154 If you explicitly refer to @q{lilypond} the program (or any other
1155 command to be executed), write @code{@@command@{lilypond@}}.
1158 Do not explicitly refer to the reader/user. There is no one else
1159 besides the reader and the writer.
1162 Avoid contractions (don't, won't, etc.). Spell the words out completely.
1165 Avoid abbreviations, except for commonly used abbreviations of foreign
1166 language terms such as etc. and i.e.
1169 Avoid fluff (@qq{Notice that,} @qq{as you can see,}
1173 The use of the word @q{illegal} is inappropriate in most cases.
1174 Say @q{invalid} instead.
1179 @node Tips for writing docs
1180 @section Tips for writing docs
1182 In the NR, I highly recommend focusing on one subsection at a
1183 time. For each subsection,
1188 check the mundane formatting. Are the headings (@@predefined,
1189 @@seealso, etc.) in the right order?
1192 add any appropriate index entries.
1195 check the links in the @@seealso section -- links to music
1196 glossary, internal references, and other NR sections are the main
1197 concern. Check for potential additions.
1200 move LSR-worthy material into LSR. Add the snippet, delete the
1201 material from the .itely file, and add a @@lilypondfile command.
1204 check the examples and descriptions. Do they still work?
1205 @strong{Do not} assume that the existing text is
1206 accurate/complete; some of the manual is highly out of date.
1209 is the material in the @@knownissues still accurate?
1212 can the examples be improved (made more explanatory), or is there
1213 any missing info? (feel free to ask specific questions on -user;
1214 a couple of people claimed to be interesting in being
1215 @qq{consultants} who would help with such questions)
1219 In general, I favor short text explanations with good examples --
1220 @qq{an example is worth a thousand words}. When I worked on the
1221 docs, I spent about half my time just working on those tiny
1222 lilypond examples. Making easily-understandable examples is much
1223 harder than it looks.
1226 @subsubheading Tweaks
1228 In general, any \set or \override commands should go in the
1229 @qq{select snippets} section, which means that they should go in
1230 LSR and not the .itely file. For some cases, the command
1231 obviously belongs in the @qq{main text} (i.e. not inside
1232 @@predefined or @@seealso or whatever) -- instrument names are a
1233 good example of this.
1236 \set Staff.instrumentName = #"foo"
1239 On the other side of this,
1242 \override Score.Hairpin #'after-line-breaking = ##t
1245 clearly belongs in LSR.
1247 I'm quite willing to discuss specific cases if you think that a
1248 tweaks needs to be in the main text. But items that can go into
1249 LSR are easier to maintain, so I'd like to move as much as
1250 possible into there.
1253 It would be @qq{nice} if you spent a lot of time crafting nice
1254 tweaks for users@dots{} but my recommendation is @strong{not} to do
1255 this. There's a lot of doc work to do without adding examples of
1256 tweaks. Tweak examples can easily be added by normal users by adding
1259 One place where a documentation writer can profitably spend time writing
1260 or upgrading tweaks is creating tweaks to deal with known issues. It
1261 would be ideal if every significant known issue had a workaround to avoid
1265 @ref{Adding and editing snippets}.
1268 @node Scripts to ease doc work
1269 @section Scripts to ease doc work
1271 @subheading Stripping whitespace
1273 @c TODO: should this be documented elsewhere? It's useful for
1274 @c more than just docs.
1275 To remove extra whitespace from the ends of lines, run
1278 scripts/auxiliar/strip-whitespace.py Documentation/FILENAME
1282 @subheading Sectioning commands
1284 @warning{These commands add whitespace.}
1286 The emacs @code{M-x texinfo-all-menus-update} command will
1287 regenerate @@menu blocks. This can also be run with this
1288 command-line script:
1292 emacs $1 -batch -f texinfo-all-menus-update -f save-buffer
1296 (save the above as something like @command{texinfo-menus.sh}, make
1297 it executable, then run @command{texinfo-menus.sh foo.itely})
1300 @subheading Updating doc with @command{convert-ly}
1302 cd into @file{Documentation/} and run
1305 find . -name '*.itely' | xargs convert-ly -e
1309 This also updates translated documentation.
1313 @node Docstrings in scheme
1314 @section Docstrings in scheme
1316 Material in the Internals reference is generated automatically
1317 from our source code. Any doc work on Internals therefore
1318 requires modifying files in @file{scm/*.scm}. Texinfo is allowed
1319 in these docstrings.
1321 Most documentation writers never touch these, though. If you want
1322 to work on them, please ask for help.
1325 @node Translating the documentation
1326 @section Translating the documentation
1328 The mailing list @code{translations@@lilynet.net} is dedicated to
1329 LilyPond web site and documentation translation; on this list, you will
1330 get support from the Translations Meister and experimented translators,
1331 and we regularly discuss translations issues common to all languagues.
1332 All people interested in LilyPond translations are invited to subscribe
1333 to this list regardless of the amount of their contribution, by sending
1334 an email to @code{translations-request@@lilynet.net} with subject
1335 @code{subscribe} and an empty message body. Unless mentioned explicitly
1336 or except if a translations coordinator contacts you privately, you
1337 should send questions, remarks, patches to this list
1338 @code{translations@@lilynet.net}; especially note that the traffic is so
1339 high on English-speaking list @code{lilypond-user@@gnu.org} that it may
1340 take months before your request or contribution is handled if you send a
1341 email to these lists.
1344 * Getting started with documentation translation::
1345 * Documentation translation details::
1346 * Documentation translation maintenance::
1347 * Translations management policies::
1348 * Technical background::
1351 @node Getting started with documentation translation
1352 @subsection Getting started with documentation translation
1354 First, get the sources of branch @code{lilypond/translation} from the
1355 Git repository, see @ref{Starting with Git}.
1358 * Translation requirements::
1359 * Which documentation can be translated::
1360 * Starting translation in a new language::
1363 @node Translation requirements
1364 @unnumberedsubsubsec Translation requirements
1366 Working on LilyPond documentation translations requires the following
1367 pieces of software, in order to make use of dedicated helper tools:
1370 @item Python 2.4 or higher,
1376 It is not required to build LilyPond and the documentation to
1377 translate the documentation. However, if you have enough time and
1378 motivation and a suitable system, it can be very useful to build at
1379 least the documentation so that you can check the output yourself and
1380 more quickly; if you are interested, see @ref{Compiling}.
1383 @node Which documentation can be translated
1384 @unnumberedsubsubsec Which documentation can be translated
1386 The makefiles and scripts infrastructure currently supports translation
1387 of the following documentation:
1390 @item the web site, the Learning Manual, the Notation Reference and
1391 Application Usage -- Texinfo source, PDF and HTML output; Info output
1392 might be added if there is enough demand for it;
1393 @item the Changes document.
1396 Support for translating the following pieces of documentation should be
1397 added soon, by decreasing order of priority:
1400 @item automatically generated documentation: markup commands,
1401 predefined music functions;
1402 @item the Snippets List;
1403 @item the Internals Reference.
1407 @node Starting translation in a new language
1408 @unnumberedsubsubsec Starting translation in a new language
1410 At top of the source directory, do
1417 or (if you want to install your self-compiled LilyPond locally)
1420 ./autogen.sh --prefix=$HOME
1424 If you want to compile LilyPond -- which is almost required to build
1425 the documentation, but is not required to do translation only -- fix
1426 all dependencies and rerun @command{./configure} (with the same
1427 options as for @command{autogen.sh}).
1429 Then @command{cd} into @file{Documentation/} and run
1432 make ISOLANG=@var{MY-LANGUAGE} new-lang
1436 where @var{MY-LANGUAGE} is the ISO 639 language code.
1438 Finally, add a language definition for your language in
1439 @file{python/langdefs.py}.
1442 @node Documentation translation details
1443 @subsection Documentation translation details
1445 Please follow all the instructions with care to ensure quality work.
1447 All files should be encoded in UTF-8.
1450 * Files to be translated::
1451 * Translating the Web site and other Texinfo documentation::
1452 * Adding a Texinfo manual::
1455 @node Files to be translated
1456 @unnumberedsubsubsec Files to be translated
1458 @include contributor/doc-translation-list.itexi
1460 In addition, not listed above, Snippets' titles and descriptions
1461 should be translated; they are a part of the Notation Reference and
1462 therefore their priority is 5.
1464 @node Translating the Web site and other Texinfo documentation
1465 @unnumberedsubsubsec Translating the Web site and other Texinfo documentation
1467 Every piece of text should be translated in the source file, except
1468 Texinfo comments, text in @code{@@lilypond} blocks and a few cases
1471 Node names are translated, but the original node name in English should
1472 be kept as the argument of @code{@@translationof} put after the section
1473 title; that is, every piece in the original file like
1477 @@@var{section_command} Bar baz
1481 should be translated as
1484 @@node @var{translation of Foo bar}
1485 @@@var{section_command} @var{translation of Bar baz}
1486 @@translationof Foo bar
1489 The argument of @code{@@rglos} commands and the first argument of
1490 @code{@@rglosnamed} commands must not be translated, as it is the node
1491 name of an entry in Music Glossary.
1493 Every time you translate a node name in a cross-reference, i.e. the
1494 argument of commands @code{@@ref, @@rprogram, @@rlearning, @@rlsr,
1495 @@ruser} or the first argument of their @code{@var{*}named} variants,
1496 you should make sure the target node is defined in the correct source
1497 file; if you do not intend to translate the target node right now, you
1498 should at least write the node definition (that is, the @code{@@node
1499 @@@var{section_commmand} @@translationof} trio mentioned above) in the
1500 expected source file and define all its parent nodes; for each node you
1501 have defined this way but have not translated, insert a line that
1502 contains @code{@@untranslated}. That is, you should end up
1503 for each untranslated node with something like
1506 @@node @var{translation of Foo bar}
1507 @@@var{section_command} @var{translation of Bar baz}
1508 @@translationof Foo bar
1513 @warning{you do not have to translate the node name of a cross-reference
1514 to a node that you do not have translated. If you do, you must define
1515 an @qq{empty} node like explained just above; this will produce a
1516 cross-reference with the translated node name in output, although the
1517 target node will still be in English. On the opposite, if all
1518 cross-references that refer to an untranslated node use the node name in
1519 English, then you do not have to define such an @qq{empty} node, and the
1520 cross-reference text will appear in English in the output. The choice
1521 between these two strategies implies its particular maintenance
1522 requirements and is left to the translators, although the opinion of the
1523 Translation meister leans towards not translating these
1526 Please think of the fact that it may not make sense translating
1527 everything in some Texinfo files, and you may take distance from the
1528 original text; for instance, in the translation of the web site section
1529 Community, you may take this into account depending on what you know the
1530 community in your language is willing to support, which is possible only
1531 if you personnally assume this support, or there exists a public forum
1532 or mailing list listed in Community for LilyPond in your language:
1535 @item @rweb{Bug reports}: this page should be translated only if you
1536 know that every bug report sent on your language's mailing list or forum
1537 will be handled by someone who will translate it to English and send it
1538 on bug-lilypond or add an issue in the tracker, then translate back the
1539 reply from developers.
1541 @item @rweb{Help us}: this page should be translated very freely,
1542 and possibly not at all: ask help for contributing to LilyPond for tasks
1543 that LilyPond community in your language is able and going to handle.
1547 In any case, please mark in your work the sections which do not result
1548 from the direct translation of a piece of English translation, using
1549 comments i.e. lines starting with @q{@code{@@c}}.
1551 Finally, press in Emacs @key{C-c C-u C-a} to update or generate
1552 menus. This process should be made easier in the future, when the helper
1553 script @command{texi-langutils.py} and the makefile target are updated.
1555 Some pieces of text manipulated by build scripts that appear in the
1556 output are translated in a @file{.po} file -- just like LilyPond output
1557 messages -- in @file{Documentation/po}. The Gettext domain is named
1558 @code{lilypond-doc}, and unlike @code{lilypond} domain it is not managed
1559 through the Free Translation Project.
1562 Take care of using typographic rules for your language, especially in
1563 @file{macros.itexi}.
1565 If you wonder whether a word, phrase or larger piece of text should be
1566 translated, whether it is an argument of a Texinfo command or a small
1567 piece sandwiched between two Texinfo commands, try to track whether and
1568 where it appears in PDF and/or HTML output as visible text. This piece
1569 of advice is especially useful for translating @file{macros.itexi}.
1571 Please keep verbatim copies of music snippets (in @code{@@lilypond}
1572 blocs). However, some music snippets containing text that shows in
1573 the rendered music, and sometimes translating this text really helps
1574 the user to understand the documentation; in this case, and only in
1575 this case, you may as an exception translate text in the music
1576 snippet, and then you must add a line immediately before the
1577 @code{@@lilypond} block, starting with
1584 Otherwise the music snippet would be reset to the same content as the
1585 English version at next @command{make snippet-update} run -- see
1586 @ref{Updating documentation translation}.
1591 @@lilypondfile[<number of fragment options>,texidoc]@{@var{filename.ly}@}
1595 in the source, open @file{Documentation/snippets/@var{filename}.ly},
1596 translate the @code{texidoc} header field it contains, enclose it with
1597 @code{texidoc@var{MY-LANGUAGE} = "} and @code{"}, and write it into
1598 @file{Documentation/@var{MY-LANGUAGE}/texidocs/@var{filename}.texidoc}.
1599 Additionnally, you may translate the snippet's title in @code{doctitle}
1600 header field, in case @code{doctitle} is a fragment option used in
1601 @code{@@lilypondfile}; you can do this exactly the same way as
1602 @code{texidoc}. For instance,
1603 @file{Documentation/@var{MY-LANGUAGE}/texidocs/@var{filename}.texidoc}
1607 doctitlees = "Spanish title baz"
1609 Spanish translation blah
1614 Then, you should get these translated strings into compiled snippets in
1615 @file{Documentation/snippets}, see @q{General guidelines} in @ref{Adding
1616 and editing snippets}.
1618 @code{@@example} blocks need not be verbatim copies, e.g. variable
1619 names, file names and comments should be translated.
1621 Finally, please carefully apply every rule exposed in @ref{Texinfo
1622 introduction and usage policy}, and @ref{Documentation policy}. If one
1623 of these rules conflicts with a rule specific to your language, please
1624 ask the Translation meister on @email{translations@@lilynet.net} list
1625 and/or the Documentation Editors on @email{lilypond-devel@@gnu.org}
1629 @node Adding a Texinfo manual
1630 @unnumberedsubsubsec Adding a Texinfo manual
1632 In order to start translating a new manual whose basename is @var{FOO},
1636 cd Documentation/@var{MY-LANGUAGE}
1637 cp ../@var{FOO}.tely .
1639 cp web/GNUmakefile @var{FOO}
1643 then append @var{FOO} to variable @code{SUBDIRS} in
1644 Documentation/@var{MY-LANGUAGE}/GNUmakefile, then translate file
1645 @var{MY-LANGUAGE}/@var{FOO}.tely and run @code{skeleton-update}:
1649 make ISOLANG=@var{MY-LANGUAGE} TEXI_LANGUTIL_FLAGS=--head-only skeleton-update
1653 Your are now ready to translate the new manual exactly like the web site
1654 or the Learning Manual.
1657 @node Documentation translation maintenance
1658 @subsection Documentation translation maintenance
1660 Several tools have been developed to make translations maintenance
1661 easier. These helper scripts make use of the power of Git, the
1662 version control system used for LilyPond development.
1664 You should use them whenever you would like to update the translation in
1665 your language, which you may do at the frequency that fits your and your
1666 cotranslators' respective available times. In the case your translation
1667 is up-do-date (which you can discover in the first subsection below), it
1668 is enough to check its state every one or two weeks. If you feel
1669 overwhelmed by the quantity of documentation to be updated, see
1670 @ref{Maintaining without updating translations}.
1673 * Check state of translation::
1674 * Updating documentation translation::
1675 * Updating translation committishes::
1678 @macro seeCommittishesUpdate{}
1679 @warning{do not forget to update the committish in each file you have
1680 completely updated, see @ref{Updating translation committishes}.}
1683 @node Check state of translation
1684 @unnumberedsubsubsec Check state of translation
1686 First pull from Git -- see @ref{Pulling and rebasing}, but DO NOT rebase
1687 unless you are sure to master the translation state checking and
1688 updating system -- then cd into @file{Documentation/} (or at top of the
1689 source tree, replace @command{make} with @command{make -C
1690 Documentation}) and run
1693 make ISOLANG=@var{MY_LANGUAGE} check-translation
1697 This presents a diff of the original files since the most recent
1698 revision of the translation. To check a single file, cd into
1699 @file{Documentation/} and run
1702 make CHECKED_FILES=@var{MY_LANGUAGE}/@var{manual}/@var{foo}.itely check-translation
1706 In case this file has been renamed since you last updated the
1707 translation, you should specify both old and new file names, e.g.
1708 @code{CHECKED_FILES=@var{MY_LANGUAGE}/@{@var{manual},user@}/@var{foo}.itely}.
1710 To see only which files need to be updated, do
1713 make ISOLANG=@var{MY_LANGUAGE} check-translation | grep 'diff --git'
1716 To avoid printing terminal colors control characters, which is often
1717 desirable when you redirect output to a file, run
1720 make ISOLANG=@var{MY_LANGUAGE} NO_COLOR=1 check-translation
1723 You can see the diffs generated by the commands above as changes that
1724 you should make in your language to the existing translation, in order
1725 to make your translation up to date.
1727 @seeCommittishesUpdate
1729 Global state of the translation is recorded in
1730 @file{Documentation/translations.itexi}, which is used to generate
1731 Translations status page. To update that page, do from
1732 @file{Documentation/}
1735 make translation-status
1738 This will also leave @file{out/translations-status.txt}, which contains
1739 up-to-dateness percentages for each translated file, and update word
1740 counts of documentation files in this Guide.
1743 @ref{Maintaining without updating translations}.
1745 @node Updating documentation translation
1746 @unnumberedsubsubsec Updating documentation translation
1748 Instead of running @code{check-translation}, you may want to run
1749 @code{update-translation}, which will run your favorite text editor to
1750 update files. First, make sure environment variable @code{EDITOR} is
1751 set to a text editor command, then run from @file{Documentation/}
1754 make ISOLANG=@var{MY_LANGUAGE} update-translation
1758 or to update a single file
1761 make CHECKED_FILES=@var{MY_LANGUAGE/@var{manual}/foo.itely} update-translation
1764 For each file to be udpated, @code{update-translation} will open your
1765 text editor with this file and a diff of the file in English; if the
1766 diff cannot be generated or is bigger than the file in English itself,
1767 the full file in English will be opened instead.
1769 @seeCommittishesUpdate
1771 Texinfo skeleton files, i.e. @file{.itely} files not yet translated,
1772 containing only the first node of the original file in English can be
1773 updated automatically: whenever @command{make check-translation} shows
1774 that such files should be updated, run from @file{Documentation/}
1777 make ISOLANG=@var{MY_LANGUAGE} skeleton-update
1780 @file{.po} message catalogs in @file{Documentation/po/} may be updated
1781 by issuing from @file{Documentation/} or @file{Documentation/po/}
1787 @warning{if you run po-update and somebody else does the same and
1788 pushes before you push or send a patch to be applied, there will be a
1789 conflict when you pull. Therefore, it is better that only the
1790 Translation meister runs this command.}
1792 Updating music snippets can quickly become cumbersome, as most
1793 snippets should be identical in all languages. Fortunately, there is
1794 a script that can do this odd job for you (run from
1795 @file{Documentation/}):
1798 make ISOLANG=@var{MY_LANGUAGE} snippet-update
1801 This script overwrites music snippets in
1802 @file{@var{MY_LANGUAGE/foo/every.itely}} with music snippets from
1803 @file{@var{foo/every.itely}}. It ignores skeleton files, and keeps
1804 intact music snippets preceded with a line starting with @code{@@c
1805 KEEP LY}; it reports an error for each @file{.itely} that has not the
1806 same music snippet count in both languages. Always use this script
1807 with a lot of care, i.e. run it on a clean Git working tree, and check
1808 the changes it made with @command{git diff} before committing; if you
1809 don't do so, some @code{@@lilypond} snippets might be broken or make
1810 no sense in their context.
1812 When you have updated texidocs in
1813 @file{Documentation/@var{MY-LANGUAGE}/texidocs}, you can get these
1814 changes into compiled snippets in @file{Documentation/snippets}, see
1815 @q{General guidelines} in @ref{Adding and editing snippets}.
1817 Finally, a command runs the three update processes above for all
1818 enabled languages (from @file{Documentation/}):
1821 make all-translations-update
1824 Use this command with caution, and keep in mind it will not be really
1825 useful until translations are stabilized after the end of GDP and GOP.
1828 @ref{Maintaining without updating translations},
1829 @ref{Adding and editing snippets}.
1832 @node Updating translation committishes
1833 @unnumberedsubsubsec Updating translation committishes
1835 At the beginning of each translated file except PO files, there is a
1836 committish which represents the revision of the sources which you have
1837 used to translate this file from the file in English.
1839 When you have pulled and updated a translation, it is very important to
1840 update this committish in the files you have completely updated (and
1841 only these); to do this, first commit possible changes to any
1842 documentation in English which you are sure to have done in your
1843 translation as well, then replace in the up-to-date translated files the
1844 old committish by the committish of latest commit, which can be obtained
1848 git rev-list HEAD |head -1
1851 A special case is updating Snippet documentation strings in
1852 @file{Documentation/@var{MY-LANGUAGE}/texidocs}. For these to be
1853 correctly marked as up-to-date, first run @code{makelsr.py} as
1854 explained in @ref{Adding and editing snippets}, and commit the
1855 resulting compiled snippets left in @file{Documentation/snippets/}.
1856 Say the SHA1 ID code of this commit is <C>. Now edit again your
1857 translated files in @file{Documentation/@var{MY-LANGUAGE}/texidocs}
1858 adjusting the 40-digit committish that appears in the text to be <C>;
1859 finally, commit these updated files. Not doing so would result in
1860 changes made both to your updates and original snippets to
1861 persistently appear in the check-translation output as if they were
1864 This two-phase mechanism avoids the (practically) unsolvable problem
1865 of guessing what committish will have our update, and pretending to
1866 put this very committish on the files in the same commit.
1868 @c http://lists.gnu.org/archive/html/lilypond-devel/2009-01/msg00245.html
1869 @c contains a helper script which could be used to perform massive
1870 @c committish updates.
1876 @node Translations management policies
1877 @subsection Translations management policies
1879 These policies show the general intent of how the translations should
1880 be managed, they aim at helping translators, developers and
1881 coordinators work efficiently.
1884 * Maintaining without updating translations::
1885 * Managing documentation translation with Git::
1888 @node Maintaining without updating translations
1889 @unnumberedsubsubsec Maintaining without updating translations
1891 Keeping translations up to date under heavy changes in the documentation
1892 in English may be almost impossible, especially as during the former
1893 Grand Documentation Project (GDP) or the Grand Organization Project
1894 (GOP) when a lot of contributors brings changes. In addition,
1895 translators may be --- and that is a very good thing --- involved in
1898 it is possible --- and even recommended --- to perform some maintenance
1899 that keeps translated documentation usable and eases future translation
1900 updating. The rationale below the tasks list motivates this plan.
1902 The following tasks are listed in decreasing priority order.
1905 @item Update macros.itexi.
1906 For each obsolete macro definition, if it is possible to update macro
1907 usage in documentation with an automatic text or regexp substitution,
1908 do it and delete the macro definition from macros.itexi; otherwise,
1909 mark this macro definition as obsolete with a comment, and keep it in
1910 macros.itexi until the documentation translation has been updated and
1911 no longer uses this macro.
1913 @item Update @file{*.tely} files completely with
1914 @command{make check-translation} -- you may want to redirect ouptput
1915 to a file because of overwhelming output, or call check-translation.py
1916 on individual files, see @ref{Check state of translation}.
1918 @item In @file{.itelys}, match sections and .itely file names with those from
1919 English docs, which possibly involves moving nodes contents in block
1920 between files, without updating contents itself. In other words, the
1921 game is catching where has gone each section. In Learning manual, and
1922 in Notation Reference sections which have been revised in GDP, there may
1923 be completely new sections: in this case, copy @code{@@node} and
1924 @code{@@section}-command from English docs, and add the marker for
1925 untranslated status @code{@@untranslated} on a single line. Note that
1926 it is not possible to exactly match subsections or subsubsections of
1927 documentation in English, when contents has been deeply revised; in this
1928 case, keep obsolete (sub)subsections in the translation, marking them
1929 with a line @code{@@c obsolete} just before the node.
1931 Emacs with Texinfo mode makes this step easier:
1934 @item without Emacs AucTeX installed, @key{C-c C-s} shows structure of current
1935 Texinfo file in a new buffer @code{*Occur*}; to show structure of two files
1936 simultaneously, first split Emacs window in 4 tiles (with @key{C-x 1}
1937 and @key{C-x 2}), press @key{C-c C-s} to show structure of one file
1938 (e.g. the translated file), copy @code{*Occur*} contents into
1939 @code{*Scratch*}, then press @key{C-c C-s} for the other file.
1941 If you happen to have installed AucTeX, you can either call the macro
1942 by doing @key{M-x texinfo-show-structure} or create a key binding in your
1943 @file{~/.emacs}, by adding the four following lines:
1946 (add-hook 'Texinfo-mode-hook
1948 (define-key Texinfo-mode-map "\C-cs"
1949 'texinfo-show-structure)))
1953 and then obtain the structure in the @code{*Occur*} buffer with @key{C-c
1956 @item Do not bother updating @code{@@menu}s when all menu entries are in the same
1957 file, just do @key{C-c C-u C-a} (@qq{update all menus}) when you have
1958 updated all the rest of the file.
1960 @item Moving to next or previous node using incremental search: press
1961 @key{C-s} and type @code{node} (or @key{C-s @@node} if the text
1962 contains the word @q{node}) then press @key{C-s} to move to next node
1963 or @key{C-r} to move to previous node. Similar operation can be used
1964 to move to the next/previous section. Note that every cursor move
1965 exits incremental search, and hitting @key{C-s} twice starts
1966 incremental search with the text entered in previous incremental
1969 @item Moving a whole node (or even a sequence of nodes): jump to beginning
1970 of the node (quit incremental search by pressing an arrow), press
1971 @key{C-SPACE}, press @key{C-s node} and repeat @key{C-s} until you
1972 have selected enough text, cut it with @key{C-w} or @key{C-x}, jump to
1973 the right place (moving between nodes with the previous hint is often
1974 useful) and paste with @key{C-y} or @key{C-v}.
1977 @item Update sections finished in the English documentation; check
1979 @uref{http://lilypondwiki.tuxfamily.org/index.php?title=Documentation_coordination}.
1981 @item Update documentation PO. It is recommended not to update
1982 strings which come from documentation that is currently deeply revised
1983 in English, to avoid doing the work more than once.
1985 @item Fix broken cross-references by running (from @file{Documentation/})
1988 make ISOLANG=@var{YOUR-LANGUAGE} fix-xrefs
1992 This step requires a sucessful documentation build (with @command{make
1993 doc}). Some cross-references are broken because they point to a node
1994 that exists in the documentation in English, which has not been added
1995 to the translation; in this case, do not fix the cross-reference but
1996 keep it "broken", so that the resulting HTML link will point to an
1997 existing page of documentation in English.
2000 @subsubheading Rationale
2002 You may wonder if it would not be better to leave translations as-is
2003 until you can really start updating translations. There are several
2004 reasons to do these maintenance tasks right now.
2007 @item This will have to be done sooner or later anyway, before updating
2008 translation of documentation contents, and this can already be done
2009 without needing to be redone later, as sections of documentation in
2010 English are mostly revised once. However, note that not all
2011 documentation sectioning has been revised in one go, so all this
2012 maintenance plan has to be repeated whenever a big reorganization is
2015 @item This just makes translated documentation take advantage of the new
2016 organization, which is better than the old one.
2018 @item Moving and renaming sections to match sectioning of documentation in
2019 English simplify future updating work: it allows updating the
2020 translation by side-by-side comparison, without bothering whether
2021 cross-reference names already exist in the translation.
2023 @item Each maintenance task except @q{Updating PO files} can be done by
2024 the same person for all languages, which saves overall time spent by
2025 translators to achieve this task: the node names and section titles
2026 are in English, so you can do. It is important to take advantage of
2027 this now, as it will be more complicated (but still possible) to do
2028 step 3 in all languages when documentation is compiled with
2029 @command{texi2html} and node names are directly translated in source
2034 @node Managing documentation translation with Git
2035 @unnumberedsubsubsec Managing documentation translation with Git
2037 This policy explains how to manage Git branches and commit
2038 translations to Git.
2041 @item Translation changes matching master branch are preferably made on
2042 @code{lilypond/translation} branch; they may be pushed directly to
2043 @code{master} only if they do not break compilation of LilyPond and
2044 its documentation, and in this case they should be pushed to
2045 @code{lilypond/translation} too. Similarly, changes matching
2046 @code{stable/X.Y} are preferably made on
2047 @code{lilypond/X.Ytranslation}.
2049 @item @code{lilypond/translation} Git branch may be merged into
2050 master only if LilyPond (@command{make all}) and documentation
2051 (@command{make doc}) compile succesfully.
2053 @item @code{master} Git branch may be merged into
2054 @code{lilypond/translation} whenever @command{make} and @command{make
2055 doc} are succesful (in order to ease documentation compilation by
2056 translators), or when significant changes had been made in
2057 documentation in English in master branch.
2059 @item General maintenance may be done by anybody who knows what he does
2060 in documentation in all languages, without informing translators
2061 first. General maintenance include simple text substitutions
2062 (e.g. automated by sed), compilation fixes, updating Texinfo or
2063 lilypond-book commands, updating macros, updating ly code, fixing
2064 cross-references, and operations described in @ref{Maintaining
2065 without updating translations}.
2069 @node Technical background
2070 @subsection Technical background
2072 A number of Python scripts handle a part of the documentation
2073 translation process. All scripts used to maintain the translations
2074 are located in @file{scripts/auxiliar/}.
2077 @item @file{check_translation.py} -- show diff to update a translation,
2078 @item @file{texi-langutils.py} -- quickly and dirtily parse Texinfo files to
2079 make message catalogs and Texinfo skeleton files,
2080 @item @file{texi-skeleton-update.py} -- update Texinfo skeleton files,
2081 @item @file{update-snippets.py} -- synchronize ly snippets with those
2083 @item @file{translations-status.py} -- update translations status pages and word
2084 counts in the file you are reading,
2085 @item @file{tely-gettext.py} -- gettext node names, section titles and references
2086 in the sources; WARNING only use this script once for each file, when support for
2087 "makeinfo --html" has been dropped.
2090 Other scripts are used in the build process, in @file{scripts/build/}:
2093 @item @file{mass-link.py} -- link or symlink files between English documentation
2094 and documentation in other languages.
2097 Python modules used by scripts in @file{scripts/auxiliar/} or @file{scripts/build/} (but
2098 not by installed Python scripts) are located in @file{python/auxiliar/}:
2100 @item @file{manuals_definitions.py} -- define manual names and name of
2101 cross-reference Texinfo macros,
2102 @item @file{buildlib.py} -- common functions (read piped output
2103 of a shell command, use Git),
2104 @item @file{postprocess_html.py} (module imported by @file{www_post.py}) -- add footer and
2105 tweak links in HTML pages.
2110 @item @file{python/langdefs.py} -- language definitions module