]> git.donarmstrong.com Git - lilypond.git/blob - Documentation/contributor/doc-work.itexi
Doc: CG: minor additions.
[lilypond.git] / Documentation / contributor / doc-work.itexi
1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @node Documentation work
3 @chapter Documentation work
4
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
9 set of source files.
10
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}.
14
15 @menu
16 * Introduction to documentation work::
17 * Documentation suggestions::
18 * Texinfo introduction and usage policy::
19 * Documentation policy::
20 * Tips for writing docs::
21 * Updating docs with convert-ly::
22 * Docstrings in scheme::
23 * Translating the documentation::
24 @end menu
25
26
27 @node Introduction to documentation work
28 @section Introduction to documentation work
29
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.
39
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.
53
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.
59
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.
64
65
66 @node Documentation suggestions
67 @section Documentation suggestions
68
69 @subheading Small additions
70
71 For additions to the documentation,
72
73 @enumerate
74
75 @item
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").
78
79 @item
80 Please write exact changes to the text.
81
82 @item
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:
86
87 @verbatim
88 To: lilypond-devel@gnu.org
89 From: helpful-user@example.net
90 Subject: doc addition
91
92 In LM 2.13 (printing lyrics), above the last line ("More options,
93 like..."), please add:
94
95 ----
96 To add lyrics to a divided part, use blah blah blah.  For example,
97
98 \score {
99   \notes {blah <<blah>> }
100   \lyrics {blah <<blah>> }
101   blah blah blah
102 }
103 ----
104
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:
108 ----
109 To align lyrics with something, do this thing.
110 ----
111
112 Have a nice day,
113 Helpful User
114 @end verbatim
115
116 @end enumerate
117
118
119 @subheading Larger contributions
120
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.
124
125 @enumerate
126
127 @item
128 Ask on the lilypond-devel maillist if such a rewrite is necessary;
129 somebody else might already be working on this issue!
130
131 @item
132 Split your work into small sections; this makes it much easier to
133 compare the new and old documentation.
134
135 @item
136 Please prepare a formal git patch.
137
138 @end enumerate
139
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
143 this, add:
144
145 > I'm not top posting.
146
147 (you must include the > ) to the top of your documentation
148 addition.
149
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!
154
155
156 @node Texinfo introduction and usage policy
157 @section Texinfo introduction and usage policy
158
159 @menu
160 * Texinfo introduction::
161 * Documentation files::
162 * Sectioning commands::
163 * LilyPond formatting::
164 * Text formatting::
165 * Syntax survey::
166 * Other text concerns::
167 @end menu
168
169
170 @node Texinfo introduction
171 @subsection Texinfo introduction
172
173 The language is called Texinfo; you can see its manual here:
174
175 @uref{http://www.gnu.org/software/texinfo/manual/texinfo/}
176
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.
181
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.}
185
186
187 @node Documentation files
188 @subsection Documentation files
189
190 All manuals live in @file{Documentation/}.
191
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.
202
203 Developer manuals live in @file{Documentation/} too.  Currently there is
204 only one: the Contributor's Guide @file{contrib-guide.texi} you are
205 reading.
206
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}.
210
211
212 @node Sectioning commands
213 @subsection Sectioning commands
214
215 Most of the manual operates at the
216
217 @example
218 @@node Foo
219 @@subsubsection Foo
220 @end example
221
222 @noindent
223 level.  Sections are created with
224
225 @example
226 @@node Foo
227 @@subsection Foo
228 @end example
229
230 @itemize
231 @item
232 Please leave two blank lines above a @@node; this makes it
233 easier to find sections in texinfo.
234
235 @item
236 Sectioning commands (@@node and @@section) must not appear
237 inside an @@ignore.  Separate those commands with a space, ie @@n
238 ode.
239
240 @end itemize
241
242 Nodes must be included inside a
243
244 @example
245 @@menu
246 * foo::
247 * bar::
248 @@end menu
249 @end example
250
251 @noindent
252 construct.  These are easily constructed with the emacs
253 @code{M-x texinfo-all-menus-update} construct, or by this
254 command-line script:
255
256 @example
257 #!/bin/sh
258 emacs $1 -batch -f texinfo-all-menus-update -f save-buffer
259 @end example
260
261 @noindent
262 (save the above as something like @command{texinfo-menus.sh}, make
263 it executable, then run @command{texinfo-menus.sh foo.itely})
264
265
266 @node LilyPond formatting
267 @subsection LilyPond formatting
268
269 @itemize
270
271 @item
272 Use two spaces for indentation in lilypond examples.  (no
273 tabs)
274
275 @item
276 All text strings should be prefaced with #.  LilyPond does
277 not strictly require this, but it is helpful to get users
278 accustomed to this scheme construct.  ie @code{\set
279 Staff.instrumentName = #"cello"}
280
281 @item
282 All engravers should have double-quotes around them:
283
284 @example
285 \consists "Spans_arpeggio_engraver"
286 @end example
287
288 Again, LilyPond does not strictly require this, but it is a useful
289 standard to follow.
290
291 @item
292 Examples should end with a complete bar if possible.
293
294 @item
295 If possible, only write one bar per line.  The notes on each
296 line should be an independent line -- tweaks should occur on their
297 own line if possible.  Bad:
298
299 @example
300 \override textscript #'padding = #3 c1^"hi"
301 @end example
302
303 Good:
304
305 @example
306 \override textscript #'padding = #3
307 c1^"hi"
308 @end example
309
310 @item
311 Most LilyPond input should be produced with:
312
313 @example
314 @@lilypond[verbatim,quote,relative=2]
315 @end example
316
317 @noindent
318 or
319
320 @example
321 @@lilypond[verbatim,quote,relative=1]
322 @end example
323
324 If you want to use \layout@{@} or define variables, use
325
326 @example
327 @@lilypond[verbatim,quote]
328 @end example
329
330 In rare cases, other options may be used (or omitted), but ask first.
331
332 @item
333 Inspirational headwords are produced with
334
335 @example
336 @@lilypondfile[quote,ragged-right,line-width=16\cm,staffsize=16]
337 @{pitches-headword.ly@}
338 @end example
339
340 @item
341 LSR snippets are linked with
342
343 @example
344 @@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
345 @{filename.ly@}
346 @end example
347
348 @noindent
349 excepted in Templates, where `doctitle' may be omitted.
350
351 @item
352 Avoid long stretches of input code.  Noone is going to read
353 them in print.  Please create a smaller example.  (the smaller
354 example does not need to be minimal, however)
355
356 @item
357 Specify durations for at least the first note of every bar.
358
359 @item
360 If possible, end with a complete bar.
361
362 @item
363 Comments should go on their own line, and be placed before
364 the line(s) to which they refer.
365
366 @item
367 Add extra spaces around @{ @} marks; ie
368
369 @example
370 not:          \chordmode @{c e g@}
371 but instead:  \chordmode @{ c e g @}
372 @end example
373
374 @item
375 If you only have one bar per line, omit bar checks.  If you
376 put more than one bar per line (not recommended), then include bar
377 checks.
378
379 @item
380 If you want to work on an example outside of the manual (for
381 easier/faster processing), use this header:
382
383 @example
384 \paper @{
385   indent = 0\mm
386   line-width = 160\mm - 2.0 * 0.4\in
387   ragged-right = ##t
388   force-assignment = #""
389   line-width = #(- line-width (* mm  3.000000))
390 @}
391
392 \layout @{
393 @}
394 @end example
395
396 You may not change any of these values.  If you are making an
397 example demonstrating special \paper@{@} values, contact the
398 Documentation Editor.
399
400 @end itemize
401
402
403 @node Text formatting
404 @subsection Text formatting
405
406 @itemize
407
408 @item
409 Lines should be less than 72 characters long.  (I personally
410 recommend writing with 66-char lines, but don't bother modifying
411 existing material.)
412
413 @item
414 Do not use tabs.
415
416 @item
417 Do not use spaces at the beginning of a line (except in
418 @@example or @@verbatim environments), and do not use more than a
419 single space between words.  `makeinfo' copies the input lines
420 verbatim without removing those spaces.
421
422 @item
423 Use two spaces after a period.
424
425 @item
426 In examples of syntax, use @@var@{musicexpr@} for a music
427 expression.
428
429 @item
430 Don't use @@rinternals@{@} in the main text.  If you're
431 tempted to do so, you're probably getting too close to "talking
432 through the code".  If you really want to refer to a context, use
433 @@code@{@} in the main text and @@rinternals@{@} in the @@seealso.
434
435 @item
436 Variables or numbers which consist of a single character
437 (probably followed by a punctuation mark) should be tied properly,
438 either to the previous or the next word.  Example:
439
440 @example
441 The variable@@tie@{@}@@var@{a@} ...
442 @end example
443
444 @item
445 To get consistent indentation in the DVI output it is better
446 to avoid the @@verbatim environment.  Use the @@example
447 environment instead if possible, but without extraneous
448 indentation.  For example, this
449
450 @example
451 @@example
452   foo @{
453     bar
454   @}
455 @@end example
456 @end example
457
458 @noindent
459 should be replaced with
460
461 @example
462 @@example
463 foo @{
464   bar
465 @}
466 @@end example
467 @end example
468
469 @noindent
470 where `@@example' starts the line (without leading spaces).
471
472 @item
473 Do not compress the input vertically; this is, do not use
474
475 @example
476     Beginning of logical unit
477     @@example
478     ...
479     @@end example
480     continuation of logical unit
481 @end example
482
483 @noindent
484 but instead do
485
486 @example
487 Beginning of logical unit
488
489 @@example
490 ...
491 @@end example
492
493 @@noindent
494 continuation of logical unit
495 @end example
496
497 This makes it easier to avoid forgetting the `@@noindent'.  Only
498 use @@noindent if the material is discussing the same material;
499 new material should simply begin without anything special on the
500 line above it.
501
502 @item
503 in @@itemize use @@item
504 on a separate line like this:
505
506 @example
507 @@itemize
508 @@item
509 Foo
510
511 @@item
512 Bar
513 @end example
514
515 Do not use @@itemize @@bullet.
516
517 @item
518 To get LilyPond version, use @@version@{@} (this does not work
519 inside LilyPond snippets).  If you write "@@version@{@}" (enclosed
520 with quotes), or generally if @@version@{@} is not followed by a
521 space, there will be an ugly line break in PDF output unless you
522 enclose it with
523
524 @example
525 @@w@{ ... @}
526
527   e.g.
528
529 @@w@{"@@version@{@}"@}
530 @end example
531
532 @end itemize
533
534
535 @node Syntax survey
536 @subsection Syntax survey
537
538 @itemize
539 @item
540 @@bs - Generates a backslash inside @@warning.
541     Any `\' used inside @@warning (and @@q or @@qq) must be written as `@@bs@{@}'
542     (texinfo would also allow \\, but this breaks with PDF output).
543
544 @item
545 @@c - single line comments
546   "@@c NOTE:" is a comment which should remain in the final
547   version.  (gp only command ;)
548
549 @item
550 @@cindex - General index. Please add as many as you can.  Don't
551   capitalize the first word.
552
553 @item
554 @@code@{@} - typeset in a tt-font. Use for actual lilypond code or
555   property/context names.  If the name contains a space, wrap
556   the entire thing inside @@w@{@@code@{  @}@}.
557
558 @item
559 @@example ... @@end example - example text that should be set as a
560   blockquote.  Any @{@} must be escaped with @@@{ @}@@
561
562 @item
563 @@funindex - is for a \lilycommand.
564
565 @item
566 @@ignore ... @@end ignore - multi-line comment
567
568 @item
569 @@itemize @@item
570 A @@item
571 B ... @@end itemize - for bulleted lists.
572   Do not compress vertically like this.
573
574 @item
575 @@notation@{@} - refers to pieces of notation, e.g.
576   "@@notation@{cres.@}".  Also use to specific lyrics ("the
577   @@notation@{A - men@} is centered").  Only use once per subsection
578   per term.
579
580 @item
581 @@q@{@} - Single quotes. Used for `vague' terms.
582
583 @item
584 @@qq@{@} - Double quotes.  Used for actual quotes ("he said") or for
585   introducing special input modes.
586
587 @item
588 @@rchanges@{@} - link to Changes.
589
590 @item
591 @@rcontrib@{@} - link to Contributor's Guide.
592
593 @item
594 @@ref@{@} - link within current manual (type the exact node name inside the
595 @{@}).
596
597 @item
598 @@ressay@{@} - link to Engraving Essay.
599
600 @item
601 @@rextend@{@} - link to Extending LilyPond.
602
603 @item
604 @@rglos@{@} - link to the Music Glossary.
605
606 @item
607 @@rinternals@{@} - link to the Internals Reference.
608
609 @item
610 @@rlearning@{@} - link to Learning Manual.
611
612 @item
613 @@rlsr@{@} - link to a Snippet section.
614
615 @item
616 @@rprogram@{@} - link to Application Usage.
617
618 @item
619 @@ruser@{@} - link to Notation Reference.
620
621 @item
622 @@rweb@{@} - link to General Informaion.
623
624 @item
625 @@tie@{@} - Variables or numbers which consist of a single character
626   (probably followed by a punctuation mark) should be tied
627   properly, either to the previous or the next word.  Example:
628     "The letter@@tie@{@}@@q@{I@} is skipped"
629
630 @item
631 @@uref@{@} - link to an external url.
632
633 @item
634 @@var - Use for variables.
635
636 @item
637 @@warning@{@} - produces a "Note: " box. Use for important messages.
638
639 @end itemize
640
641
642
643 @node Other text concerns
644 @subsection Other text concerns
645
646 @itemize
647
648 @item
649 References must occur at the end of a sentence, for more
650 information see @@ref@{the texinfo manual@}.  Ideally this should
651 also be the final sentence of a paragraph, but this is not
652 required.  Any link in a doc section must be duplicated in the
653 @@seealso section at the bottom.
654
655 @item
656 Introducing examples must be done with
657
658 @example
659 . (ie finish the previous sentence/paragaph)
660 : (ie `in this example:')
661 , (ie `may add foo with the blah construct,')
662 @end example
663
664 The old @qq{sentence runs directly into the example} method is not
665 allowed any more.
666
667 @item
668 Abbrevs in caps, e.g., HTML, DVI, MIDI, etc.
669
670 @item
671 Colon usage
672
673 @enumerate
674
675 @item
676 To introduce lists
677
678 @item
679 When beginning a quote: "So, he said,...".
680
681 This usage is rarer.  Americans often just use a comma.
682
683 @item
684 When adding a defining example at the end of a sentence.
685
686 @end enumerate
687
688 @item
689 Non-ASCII characters which are in utf-8 should be directly used;
690 this is, don't say `Ba@@ss@{@}tuba' but `Baßtuba'.  This ensures
691 that all such characters appear in all output formats.
692
693 @end itemize
694
695
696
697
698 @node Documentation policy
699 @section Documentation policy
700
701 @menu
702 * Books::
703 * Section organization::
704 * Checking cross-references::
705 * General writing::
706 * Technical writing style::
707 @end menu
708
709 @node Books
710 @subsection Books
711
712 There are four parts to the documentation: the Learning Manual,
713 the Notation Reference, the Program Reference, and the Music
714 Glossary.
715
716 @itemize
717
718 @item
719 Learning Manual:
720
721 The LM is written in a tutorial style which introduces the most
722 important concepts, structure and syntax of the elements of a
723 LilyPond score in a carefully graded sequence of steps.
724 Explanations of all musical concepts used in the Manual can be
725 found in the Music Glossary, and readers are assumed to have no
726 prior knowledge of LilyPond.  The objective is to take readers to
727 a level where the Notation Reference can be understood and
728 employed to both adapt the templates in the Appendix to their
729 needs and to begin to construct their own scores.  Commonly used
730 tweaks are introduced and explained.  Examples are provided
731 throughout which, while being focussed on the topic being
732 introduced, are long enough to seem real in order to retain the
733 readers' interest.  Each example builds on the previous material,
734 and comments are used liberally.  Every new aspect is thoroughly
735 explained before it is used.
736
737 Users are encouraged to read the complete Learning Manual from
738 start-to-finish.
739
740
741 @item
742 Notation Reference: a (hopefully complete) description of LilyPond
743 input notation.  Some material from here may be duplicated in the
744 Learning Manual (for teaching), but consider the NR to be the
745 "definitive" description of each notation element, with the LM
746 being an "extra".  The goal is _not_ to provide a step-by-step
747 learning environment -- do not avoid using notation that has not
748 be introduced previously in the NR  (for example, use \break if
749 appropriate).  This section is written in formal technical writing
750 style.
751
752 Avoid duplication.  Although users are not expected to read this
753 manual from start to finish, they should be familiar with the
754 material in the Learning Manual (particularly ``Fundamental
755 Concepts''), so do not repeat that material in each section of
756 this book.  Also watch out for common constructs, like ^ - _ for
757 directions -- those are explained in NR 3.  In NR 1, you can
758 write: DYNAMICS may be manually placed above or below the staff,
759 see @@ref@{Controlling direction and placement@}.
760
761 Most tweaks should be added to LSR and not placed directly in the
762 .itely file.  In some cases, tweaks may be placed in the main
763 text, but ask about this first.
764
765 Finally, you should assume that users know what the notation
766 means; explaining musical concepts happens in the Music Glossary.
767
768
769 @item
770 Application Usage: information about using the program lilypond
771 with other programs (lilypond-book, operating systems, GUIs,
772 convert-ly, etc).  This section is written in formal technical
773 writing style.
774
775 Users are not expected to read this manual from start to finish.
776
777
778 @item
779 Music Glossary: information about the music notation itself.
780 Explanations and translations about notation terms go here.
781
782 Users are not expected to read this manual from start to finish.
783
784 @item
785 Internals Reference: not really a documentation book, since it is
786 automagically generated from the source, but this is its name.
787
788 @end itemize
789
790
791 @node Section organization
792 @subsection Section organization
793
794 @itemize
795
796 @item
797 The order of headings inside documentation sections should
798 be:
799
800 @example
801 main docs
802 @@predefined
803 @@endpredefined
804 @@snippets
805 @@seealso
806 @@knownissues
807 @end example
808
809 @item
810 You @emph{must} include a @@seealso.
811
812 @itemize
813 @item
814 The order of items inside the @@seealso section is
815
816 @example
817 Music Glossary:
818 @@rglos@{foo@},
819 @@rglos@{bar@}.
820
821 Learning Manual:
822 @@rlearning@{baz@},
823 @@rlearning@{foozle@}.
824
825 Notation Reference:
826 @@ruser@{faazle@},
827 @@ruser@{boo@}.
828
829 Application Usage:
830 @@rprogram@{blah@}.
831
832 Extending LilyPond:
833 @@rextend@{frob@}.
834
835 Installed Files:
836 @@file@{path/to/dir/blahz@}.
837
838 Snippets: @@rlsr@{section@}.
839
840 Internals Reference:
841 @@rinternals@{fazzle@},
842 @@rinternals@{booar@}.
843 @end example
844
845 @item
846 If there are multiple entries, separate them by commas but do not
847 include an `and'.
848
849 @item
850 Always end with a period.
851
852 @item
853 Place each link on a new line as above; this makes it much easier
854 to add or remove links.  In the output, they appear on a single
855 line.
856
857 ("Snippets" is REQUIRED; the others are optional)
858
859 @item
860 Any new concepts or links which require an explanation should go
861 as a full sentence(s) in the main text.
862
863 @item
864 Don't insert an empty line between @@seealso and the first entry!
865 Otherwise there is excessive vertical space in the PDF output.
866
867 @end itemize
868
869 @item
870 To create links, use @@ref@{@} if the link is within the same
871 manual.
872
873 @item
874 @@predefined ... @@endpredefined is for commands in ly/*-init.ly
875 FIXME?
876
877 @item
878 Do not include any real info in second-level sections (ie 1.1
879 Pitches).  A first-level section may have introductory material,
880 but other than that all material goes into third-level sections
881 (ie 1.1.1 Writing Pitches).
882
883 @end itemize
884
885
886 @node Checking cross-references
887 @subsection Checking cross-references
888
889 Cross-references between different manuals are heavily used in the
890 documentation, but they are not checked during compilation.
891 However, if you compile the documentation, a script called
892 check_texi_refs can help you with checking and fixing these
893 cross-references; for information on usage, cd into a source tree
894 where documentation has been built, cd into Documentation and run:
895
896 @example
897 make check-xrefs
898 make fix-xrefs
899 @end example
900
901 Note that you have to find yourself the source files to fix
902 cross-references in the generated documentation such as the
903 Internals Reference; e.g. you can grep scm/ and lily/.
904
905
906 @node General writing
907 @subsection General writing
908
909 @itemize
910
911 @item
912 Do not forget to create @@cindex entries for new sections of text.
913 Enter commands with @@funindex, i.e.
914
915 @example
916 @@cindex pitches, writing in different octaves
917 @@funindex \relative
918 @end example
919
920 @noindent
921 do not bother with the @@code@{@} (they are added automatically).
922 These items are added to both the command index and the unified
923 index.
924
925 Both index commands should go in front of the actual material.
926
927 @@cindex entries should not be capitalized, ie
928
929 @example
930 @@cindex time signature
931 @end example
932
933 @noindent
934 is preferred instead of @qq{Time signature},   Only use capital
935 letters for musical terms which demand them, like D.S. al Fine.
936
937 For scheme functions, only include the final part, i.e.,
938
939 @example
940 @@funindex modern-voice-cautionary
941      and NOT
942 @@funindex #(set-accidental-style modern-voice-cautionary)
943 @end example
944
945 @item
946 Preferred terms:
947
948 @itemize
949
950 @item
951 In general, use the American spellings.  The internal lilypond
952 property names use this spelling.
953
954 @item
955 List of specific terms:
956
957 @example
958 canceled
959 simultaneous    NOT concurrent
960 measure: the unit of music
961 bar line: the symbol delimiting a measure   NOT barline
962 note head   NOT notehead
963 chord construct   NOT chord (when referring to <>)
964 @end example
965
966 @end itemize
967
968 @end itemize
969
970
971 @node Technical writing style
972 @subsection Technical writing style
973
974 These refer to the NR.  The LM uses a more gentle, colloquial
975 style.
976
977 @itemize
978
979 @item
980 Do not refer to LilyPond in the text.  The reader knows what the
981 manual is about.  If you do, capitalization is LilyPond.
982
983 @item
984 If you explicitly refer to @q{lilypond} the program (or any other
985 command to be executed), write @code{@@command@{lilypond@}}.
986
987 @item
988 Do not explicitly refer to the reader/user.  There is no one else
989 besides the reader and the writer.
990
991 @item
992 Avoid contractions (don't, won't, etc.).  Spell the words out completely.
993
994 @item
995 Avoid abbreviations, except for commonly used abbreviations of foreign
996 language terms such as etc. and i.e.
997
998 @item
999 Avoid fluff (@qq{Notice that,} @qq{as you can see,}
1000 @qq{Currently,}).
1001
1002 @item
1003 The use of the word @q{illegal} is inappropriate in most cases.
1004 Say @q{invalid} instead.
1005
1006 @end itemize
1007
1008
1009 @node Tips for writing docs
1010 @section Tips for writing docs
1011
1012 In the NR, I highly recommend focusing on one subsection at a
1013 time.  For each subsection,
1014
1015 @itemize
1016
1017 @item
1018 check the mundane formatting.  Are the headings (@@predefined,
1019 @@seealso, etc.) in the right order?
1020
1021 @item
1022 add any appropriate index entries.
1023
1024 @item
1025 check the links in the @@seealso section -- links to music
1026 glossary, internal references, and other NR sections are the main
1027 concern.  Check for potential additions.
1028
1029 @item
1030 move LSR-worthy material into LSR.  Add the snippet, delete the
1031 material from the .itely file, and add a @@lilypondfile command.
1032
1033 @item
1034 check the examples and descriptions.  Do they still work?
1035 @strong{Do not} assume that the existing text is
1036 accurate/complete; some of the manual is highly out of date.
1037
1038 @item
1039 is the material in the @@knownissues  still accurate?
1040
1041 @item
1042 can the examples be improved (made more explanatory), or is there
1043 any missing info?  (feel free to ask specific questions on -user;
1044 a couple of people claimed to be interesting in being
1045 @qq{consultants} who would help with such questions)
1046
1047 @end itemize
1048
1049 In general, I favor short text explanations with good examples --
1050 @qq{an example is worth a thousand words}.  When I worked on the
1051 docs, I spent about half my time just working on those tiny
1052 lilypond examples.  Making easily-understandable examples is much
1053 harder than it looks.
1054
1055
1056 @subsubheading Tweaks
1057
1058 In general, any \set or \override commands should go in the
1059 @qq{select snippets} section, which means that they should go in
1060 LSR and not the .itely file.  For some cases, the command
1061 obviously belongs in the @qq{main text} (i.e. not inside
1062 @@predefined or @@seealso or whatever) -- instrument names are a
1063 good example of this.
1064
1065 @example
1066 \set Staff.instrumentName = #"foo"
1067 @end example
1068
1069 On the other side of this,
1070
1071 @example
1072 \override Score.Hairpin #'after-line-breaking = ##t
1073 @end example
1074
1075 clearly belongs in LSR.
1076
1077 I'm quite willing to discuss specific cases if you think that a
1078 tweaks needs to be in the main text.  But items that can go into
1079 LSR are easier to maintain, so I'd like to move as much as
1080 possible into there.
1081
1082
1083 It would be @qq{nice} if you spent a lot of time crafting nice
1084 tweaks for users@dots{} but my recommendation is @strong{not} to do
1085 this.  There's a lot of doc work to do without adding examples of
1086 tweaks.  Tweak examples can easily be added by normal users by adding
1087 them to the LSR.
1088
1089 One place where a documentation writer can profitably spend time writing
1090 or upgrading tweaks is creating tweaks to deal with known issues.  It
1091 would be ideal if every significant known issue had a workaround to avoid
1092 the difficulty.
1093
1094 @seealso
1095 @ref{Adding and editing snippets}.
1096
1097
1098 @node Updating docs with convert-ly
1099 @section Updating doc with @command{convert-ly}
1100
1101 cd into @file{Documentation/} and run
1102
1103 @example
1104 find . -name '*.itely' | xargs convert-ly -e
1105 @end example
1106
1107 @noindent
1108 This also updates translated documentation.
1109
1110
1111
1112 @node Docstrings in scheme
1113 @section Docstrings in scheme
1114
1115 Material in the Internals reference is generated automatically
1116 from our source code.  Any doc work on Internals therefore
1117 requires modifying files in @file{scm/*.scm}.  Texinfo is allowed
1118 in these docstrings.
1119
1120 Most documentation writers never touch these, though.  If you want
1121 to work on them, please ask for help.
1122
1123
1124 @node Translating the documentation
1125 @section Translating the documentation
1126
1127 The mailing list @code{translations@@lilynet.net} is dedicated to
1128 LilyPond web site and documentation translation; on this list, you will
1129 get support from the Translations Meister and experimented translators,
1130 and we regularly discuss translations issues common to all languagues.
1131 All people interested in LilyPond translations are invited to subscribe
1132 to this list regardless of the amount of their contribution, by sending
1133 an email to @code{translations-request@@lilynet.net} with subject
1134 @code{subscribe} and an empty message body.
1135
1136 @menu
1137 * Getting started with documentation translation::
1138 * Documentation translation details::
1139 * Documentation translation maintenance::
1140 * Translations management policies::
1141 * Technical background::
1142 @end menu
1143
1144 @node Getting started with documentation translation
1145 @subsection Getting started with documentation translation
1146
1147 First, get the sources from the Git repository, see @ref{Documentation
1148 translations source code}.
1149
1150 @menu
1151 * Translation requirements::
1152 * Which documentation can be translated::
1153 * Starting translation in a new language::
1154 @end menu
1155
1156 @node Translation requirements
1157 @unnumberedsubsubsec Translation requirements
1158
1159 Working on LilyPond documentation translations requires the following
1160 pieces of software, in order to make use of dedicated helper tools:
1161
1162 @itemize
1163 @item Python 2.4 or higher,
1164 @item GNU Make,
1165 @item Gettext,
1166 @item Git.
1167 @end itemize
1168
1169 It is not required to build LilyPond and the documentation to
1170 translate the documentation.  However, if you have enough time and
1171 motivation and a suitable system, it can be very useful to build at
1172 least the documentation so that you can check the output yourself and
1173 more quickly; if you are interested, see @ref{Compiling from source}.
1174
1175
1176 @node Which documentation can be translated
1177 @unnumberedsubsubsec Which documentation can be translated
1178
1179 FIXME: take into account the new web site integration in main sources.
1180
1181 The makefiles and scripts infrastructure currently supports translation
1182 of the following documentation:
1183
1184 @itemize
1185 @item documentation index (HTML);
1186 @item the Learning Manual, the Notation Reference and Application Usage
1187 -- Texinfo source, PDF and HTML output; Info output might be added if
1188 there is enough demand for it;
1189 @item the Changes document.
1190 @end itemize
1191
1192 Support for translating the following pieces of documentation should be
1193 added soon, by decreasing order of priority:
1194
1195 @itemize
1196 @item automatically generated documentation: markup commands,
1197 predefined music functions;
1198 @item the Snippets List;
1199 @item the Internals Reference.
1200 @end itemize
1201
1202
1203 @node Starting translation in a new language
1204 @unnumberedsubsubsec Starting translation in a new language
1205
1206 At top of the source directory, do
1207
1208 @example
1209 ./autogen.sh
1210 @end example
1211
1212 @noindent
1213 or (if you want to install your self-compiled LilyPond locally)
1214
1215 @example
1216 ./autogen.sh --prefix=$HOME
1217 @end example
1218
1219 @noindent
1220 If you want to compile LilyPond -- which is almost required to build
1221 the documentation, but is not required to do translation only -- fix
1222 all dependencies and rerun @command{./configure} (with the same
1223 options as for @command{autogen.sh}).
1224
1225 Then @command{cd} into @file{Documentation/} and run
1226
1227 @example
1228 make ISOLANG=@var{MY-LANGUAGE} new-lang
1229 @end example
1230
1231 @noindent
1232 where @var{MY-LANGUAGE} is the ISO 639 language code.
1233
1234 Finally, add a language definition for your language in
1235 @file{python/langdefs.py}.
1236
1237 Before starting the real translation work, it is recommended to commit
1238 changes you made so far to Git, so e.g. you are able to get back to
1239 this state of the sources easily if needed; see @ref{Sharing your
1240 changes}.
1241
1242
1243 @node Documentation translation details
1244 @subsection Documentation translation details
1245
1246 Please follow all the instructions with care to ensure quality work.
1247
1248 All files should be encoded in UTF-8.
1249
1250 @menu
1251 * Files to be translated::
1252 * Translating the Learning Manual and other Texinfo documentation::
1253 * Translating the Notation Reference and Application Usage::
1254 * Translating the Documentation index index.html.in::
1255 @end menu
1256
1257 @node Files to be translated
1258 @unnumberedsubsubsec Files to be translated
1259
1260 @include contributor/doc-translation-list.itexi
1261
1262 @node Translating the Learning Manual and other Texinfo documentation
1263 @unnumberedsubsubsec Translating the Learning Manual and other Texinfo documentation
1264
1265 @iftex
1266 @vskip 12pt
1267 @end iftex
1268 @cartouche
1269 @b{Note:} node names and section titles are now translated directly in
1270 Texinfo source files. In case you have files in your working tree that
1271 have not been converted, please pull first, then run
1272
1273 @example
1274 make -C Documentation/po doc
1275 export LYDOC_LOCALEDIR=Documentation/po/out-www
1276 export PYTHONPATH=python:python/auxiliar
1277 scripts/auxiliar/tely-gettext.py @var{manual.tely}
1278 @end example
1279
1280 @noindent
1281 This will also update files included in @file{@var{manual}.tely}, and of
1282 course this script can be used for individual @file{@var{foo}.itely}
1283 files too.
1284 @end cartouche
1285
1286 Every piece of text should be translated in the source file, except
1287 Texinfo comments, text in @code{@@lilypond} blocks and a few cases
1288 mentioned below.
1289
1290 Node names are translated, but the original node name in English should
1291 be kept as the argument of @code{@@translationof} put after the section
1292 title; that is, every piece in the original file like
1293
1294 @example
1295 @@node Foo bar
1296 @@@var{section_command} Bar baz
1297 @end example
1298
1299 @noindent
1300 should be translated as
1301
1302 @example
1303 @@node @var{translation of Foo bar}
1304 @@@var{section_command} @var{translation of Bar baz}
1305 @@translationof Foo bar
1306 @end example
1307
1308 The argument of @code{@@rglos} commands and the first argument of
1309 @code{@@rglosnamed} commands must not be translated, as it is the node
1310 name of an entry in Music Glossary.
1311
1312 Every time you translate a node name in a cross-reference, i.e. the
1313 argument of commands @code{@@ref, @@rprogram, @@rlearning, @@rlsr,
1314 @@ruser} or the first argument of their @code{@var{*}named} variants,
1315 you should make sure the target node is defined in the correct source
1316 file; if you do not intend to translate the target node right now, you
1317 should at least write the node definition (that is, the @code{@@node
1318 @@@var{section_commmand} @@translationof} trio mentioned above) in the
1319 expected source file and define all its parent nodes; for each node you
1320 have defined this way but have not translated, insert a line that
1321 contains @code{@@untranslated} and append @code{ @@c external} to the
1322 line that contains @code{@@translationof}. That is, you should end up
1323 for each untranslated node with something like
1324
1325 @example
1326 @@node @var{translation of Foo bar}
1327 @@@var{section_command} @var{translation of Bar baz}
1328 @@translationof Foo bar @@c external
1329
1330 @@untranslated
1331 @end example
1332
1333 @noindent
1334 Finally, press in Emacs @key{C-c C-u C-a} to update or generate
1335 menus. This process should be made easier in the future, when the helper
1336 script @command{texi-langutils.py} and the makefile target are updated.
1337
1338 Some pieces of text manipulated by build scripts that appear in the
1339 output are translated in a @file{.po} file -- just like LilyPond output
1340 messages -- in @file{Documentation/po}.  The Gettext domain is named
1341 @code{lilypond-doc}, and unlike @code{lilypond} domain it is not managed
1342 through the Free Translation Project.
1343
1344
1345 Take care of using typographic rules for your language, especially in
1346 @file{macros.itexi}.
1347
1348
1349 Please keep verbatim copies of music snippets (in @code{@@lilypond}
1350 blocs).  However, some music snippets containing text that shows in
1351 the rendered music, and sometimes translating this text really helps
1352 the user to understand the documentation; in this case, and only in
1353 this case, you may as an exception translate text in the music
1354 snippet, and then you must add a line immediately before the
1355 @code{@@lilypond} block, starting with
1356
1357 @example
1358 @@c KEEP LY
1359 @end example
1360
1361 @noindent
1362 Otherwise the music snippet would be reset to the same content as the
1363 English version at next @command{make snippet-update} run -- see
1364 @ref{Updating documentation translation}.
1365
1366 When you encounter
1367
1368 @example
1369 @@lilypondfile[<number of fragment options>,texidoc]@{@var{filename.ly}@}
1370 @end example
1371
1372 @noindent
1373 in the source, open @file{Documentation/snippets/@var{filename}.ly},
1374 translate the @code{texidoc} header field it contains, enclose it with
1375 @code{texidoc@var{MY-LANGUAGE} = "} and @code{"}, and write it into
1376 @file{Documentation/@var{MY-LANGUAGE}/texidocs/@var{filename}.texidoc}.
1377 Additionnally, you may translate the snippet's title in @code{doctitle}
1378 header field, in case @code{doctitle} is a fragment option used in
1379 @code{@@lilypondfile}; you can do this exactly the same way as
1380 @code{texidoc}.  For instance,
1381 @file{Documentation/@var{MY-LANGUAGE}/texidocs/@var{filename}.texidoc}
1382 may contain
1383
1384 @example
1385 doctitlees = "Spanish title baz"
1386 texidoces = "
1387 Spanish translation blah
1388 "
1389 @end example
1390
1391 @noindent
1392 Then, you should get these translated strings into compiled snippets in
1393 @file{Documentation/snippets}, see @q{General guidelines} in @ref{Adding
1394 and editing snippets}.
1395
1396 @code{@@example} blocs need not be verbatim copies, e.g. variable
1397 names, file names and comments should be translated.
1398
1399 Finally, please carefully apply every rule exposed in @ref{Texinfo
1400 introduction and usage policy}, and @ref{Documentation policy}.  If one
1401 of these rules conflicts with a rule specific to your language, please
1402 ask the Translation meister on @email{translations@@lilynet.net} list
1403 and/or the Documentation Editors on @email{lilypond-devel@@gnu.org}
1404 list.
1405
1406
1407 @node Translating the Notation Reference and Application Usage
1408 @unnumberedsubsubsec Translating the Notation Reference and Application Usage
1409
1410 Copy @file{notation.tely} (or @file{application.tely},
1411 respectively) into @file{@var{MY-LANGUAGE}}, then translate this
1412 file and run @code{skeleton-update} -- see @ref{Updating documentation
1413 translation}.  Your are now ready to translate the Notation Reference
1414 (Application Usage, respectively) exactly like the Learning Manual.
1415
1416
1417 @node Translating the Documentation index index.html.in
1418 @unnumberedsubsubsec Translating the Documentation index @file{index.html.in}
1419
1420 Unlike almost all HTML pages in this documentation, links in this page
1421 are not tweaked by @file{postprocess_html.py}, so links should be
1422 manually edited to link to existing translations.
1423
1424
1425 @node Documentation translation maintenance
1426 @subsection Documentation translation maintenance
1427
1428 Several tools have been developed to make translations maintenance
1429 easier.  These helper scripts make use of the power of Git, the
1430 version control system used for LilyPond development.
1431
1432 @menu
1433 * Check state of translation::
1434 * Updating documentation translation::
1435 @end menu
1436
1437 @node Check state of translation
1438 @unnumberedsubsubsec Check state of translation
1439
1440 First pull from Git, then cd into @file{Documentation/} (or at top of
1441 the source tree, replace @command{make} with @command{make -C
1442 Documentation}) and run
1443
1444 @example
1445 make ISOLANG=@var{MY_LANGUAGE} check-translation
1446 @end example
1447
1448 @noindent
1449 This presents a diff of the original files since the most recent
1450 revision of the translation.  To check a single file, cd into
1451 @file{Documentation/} and run
1452
1453 @example
1454 make CHECKED_FILES=@var{MY_LANGUAGE}/@var{manual}/@var{foo}.itely check-translation
1455 @end example
1456
1457 @noindent
1458 In case this file has been renamed since you last updated the
1459 translation, you should specify both old and new file names,
1460 e.g. @code{CHECKED_FILES=@var{MY_LANGUAGE}/@{@var{manual},user@}/@var{foo}.itely}.
1461
1462 To see only which files need to be updated, do
1463
1464 @example
1465 make ISOLANG=@var{MY_LANGUAGE} check-translation | grep 'diff --git'
1466 @end example
1467
1468 To avoid printing terminal colors control characters, which is often
1469 desirable when you redirect output to a file, run
1470
1471 @example
1472 make ISOLANG=@var{MY_LANGUAGE} NO_COLOR=1 check-translation
1473 @end example
1474
1475 Global state of the translation is recorded in
1476 @file{Documentation/translations.html.in}, which is used to generate
1477 Translations status page.  To update that page, do from
1478 @file{Documentation/}
1479
1480 @example
1481 make translation-status
1482 @end example
1483
1484 This will also leave @file{out/translations-status.txt}, which contains
1485 up-to-dateness percentages for each translated file, and update word
1486 counts of documentation files in this Guide.
1487
1488 @seealso
1489 @ref{Maintaining without updating translations}.
1490
1491
1492 @node Updating documentation translation
1493 @unnumberedsubsubsec Updating documentation translation
1494
1495 Instead of running @code{check-translation}, you may want to run
1496 @code{update-translation}, which will run your favorite text editor to
1497 update files.  First, make sure environment variable @code{EDITOR} is
1498 set to a text editor command, then run from @file{Documentation/}
1499
1500 @example
1501 make ISOLANG=@var{MY_LANGUAGE} update-translation
1502 @end example
1503
1504 @noindent
1505 or to update a single file
1506
1507 @example
1508 make CHECKED_FILES=@var{MY_LANGUAGE/@var{manual}/foo.itely} update-translation
1509 @end example
1510
1511 For each file to be udpated, @code{update-translation} will open your
1512 text editor with this file and a diff of the file in English; if the
1513 diff cannot be generated or is bigger than the file in English itself,
1514 the full file in English will be opened instead.
1515
1516 Texinfo skeleton files, i.e. @file{.itely} files not yet translated,
1517 containing only the Texinfo structure can be updated automatically:
1518 whenever @command{make check-translation} shows that such files should
1519 be updated, run from @file{Documentation/}
1520
1521 @example
1522 make ISOLANG=@var{MY_LANGUAGE} skeleton-update
1523 @end example
1524
1525 @file{.po} message catalogs in @file{Documentation/po/} may be updated
1526 by issuing from @file{Documentation/} or @file{Documentation/po/}
1527
1528 @example
1529 make po-update
1530 @end example
1531
1532 @warning{if you run po-update and somebody else does the same and
1533 pushes before you push or send a patch to be applied, there will be a
1534 conflict when you pull.  Therefore, it is better that only the
1535 Translation meister runs this command.}
1536
1537 Updating music snippets can quickly become cumbersome, as most
1538 snippets should be identical in all languages.  Fortunately, there is
1539 a script that can do this odd job for you (run from
1540 @file{Documentation/}):
1541
1542 @example
1543 make ISOLANG=@var{MY_LANGUAGE} snippet-update
1544 @end example
1545
1546 This script overwrites music snippets in
1547 @file{@var{MY_LANGUAGE/foo/every.itely}} with music snippets from
1548 @file{@var{foo/every.itely}}.  It ignores skeleton files, and keeps
1549 intact music snippets preceded with a line starting with @code{@@c
1550 KEEP LY}; it reports an error for each @file{.itely} that has not the
1551 same music snippet count in both languages.  Always use this script
1552 with a lot of care, i.e. run it on a clean Git working tree, and check
1553 the changes it made with @command{git diff} before committing; if you
1554 don't do so, some @code{@@lilypond} snippets might be broken or make
1555 no sense in their context.
1556
1557 When you have updated texidocs in
1558 @file{Documentation/@var{MY-LANGUAGE}/texidocs}, you can get these
1559 changes into compiled snippets in @file{Documentation/snippets}, see
1560 @q{General guidelines} in @ref{Adding and editing snippets}.
1561
1562 Finally, a command runs the three update processes above for all
1563 enabled languages (from @file{Documentation/}):
1564
1565 @example
1566 make all-translations-update
1567 @end example
1568
1569 Use this command with caution, and keep in mind it will not be really
1570 useful until translations are stabilized after the end of GDP and GOP.
1571
1572 @seealso
1573 @ref{Maintaining without updating translations},
1574 @ref{Adding and editing snippets}.
1575
1576
1577 @node Translations management policies
1578 @subsection Translations management policies
1579
1580 These policies show the general intent of how the translations should
1581 be managed, they aim at helping translators, developers and
1582 coordinators work efficiently.
1583
1584 @menu
1585 * Maintaining without updating translations::
1586 * Managing documentation translation with Git::
1587 @end menu
1588
1589 @node Maintaining without updating translations
1590 @unnumberedsubsubsec Maintaining without updating translations
1591
1592 Keeping translations up to date under heavy changes in the documentation
1593 in English may be almost impossible, especially as during the former
1594 Grand Documentation Project (GDP) or the Grand Organization Project
1595 (GOP) when a lot of contributors brings changes.  In addition,
1596 translators may be --- and that is a very good thing --- involved in
1597 these projects too.
1598
1599 it is possible --- and even recommended --- to perform some maintenance
1600 that keeps translated documentation usable and eases future translation
1601 updating.  The rationale below the tasks list motivates this plan.
1602
1603 The following tasks are listed in decreasing priority order.
1604
1605 @enumerate
1606 @item Update macros.itexi.
1607 For each obsolete macro definition, if it is possible to update macro
1608 usage in documentation with an automatic text or regexp substitution,
1609 do it and delete the macro definition from macros.itexi; otherwise,
1610 mark this macro definition as obsolete with a comment, and keep it in
1611 macros.itexi until the documentation translation has been updated and
1612 no longer uses this macro.
1613
1614 @item Update @file{*.tely} files completely with
1615 @command{make check-translation} -- you may want to redirect ouptput
1616 to a file because of overwhelming output, or call check-translation.py
1617 on individual files, see @ref{Check state of translation}.
1618
1619 @item In @file{.itelys}, match sections and .itely file names with those from
1620 English docs, which possibly involves moving nodes contents in block
1621 between files, without updating contents itself.  In other words, the
1622 game is catching where has gone each section.  In Learning manual, and
1623 in Notation Reference sections which have been revised in GDP, there may
1624 be completely new sections: in this case, copy @code{@@node} and
1625 @code{@@section}-command from English docs, and add the marker for
1626 untranslated status @code{@@untranslated} on a single line.  Note that
1627 it is not possible to exactly match subsections or subsubsections of
1628 documentation in English, when contents has been deeply revised; in this
1629 case, keep obsolete (sub)subsections in the translation, marking them
1630 with a line @code{@@c obsolete} just before the node.
1631
1632 Emacs with Texinfo mode makes this step easier:
1633
1634 @itemize
1635 @item without Emacs AucTeX installed, @key{C-c C-s} shows structure of current
1636 Texinfo file in a new buffer @code{*Occur*}; to show structure of two files
1637 simultaneously, first split Emacs window in 4 tiles (with @key{C-x 1}
1638 and @key{C-x 2}), press @key{C-c C-s} to show structure of one file
1639 (e.g. the translated file), copy @code{*Occur*} contents into
1640 @code{*Scratch*}, then press @key{C-c C-s} for the other file.
1641
1642 If you happen to have installed AucTeX, you can either call the macro
1643 by doing @key{M-x texinfo-show-structure} or create a key binding in your
1644 @file{~/.emacs}, by adding the four following lines:
1645
1646 @example
1647 (add-hook 'Texinfo-mode-hook
1648           '(lambda ()
1649              (define-key Texinfo-mode-map "\C-cs"
1650               'texinfo-show-structure)))
1651 @end example
1652
1653 @noindent
1654 and then obtain the structure in the @code{*Occur*} buffer with @key{C-c
1655 s}.
1656
1657 @item Do not bother updating @code{@@menu}s when all menu entries are in the same
1658 file, just do @key{C-c C-u C-a} (@qq{update all menus}) when you have
1659 updated all the rest of the file.
1660
1661 @item Moving to next or previous node using incremental search: press
1662 @key{C-s} and type @code{node} (or @key{C-s @@node} if the text
1663 contains the word @q{node}) then press @key{C-s} to move to next node
1664 or @key{C-r} to move to previous node.  Similar operation can be used
1665 to move to the next/previous section.  Note that every cursor move
1666 exits incremental search, and hitting @key{C-s} twice starts
1667 incremental search with the text entered in previous incremental
1668 search.
1669
1670 @item Moving a whole node (or even a sequence of nodes): jump to beginning
1671 of the node (quit incremental search by pressing an arrow), press
1672 @key{C-SPACE}, press @key{C-s node} and repeat @key{C-s} until you
1673 have selected enough text, cut it with @key{C-w} or @key{C-x}, jump to
1674 the right place (moving between nodes with the previous hint is often
1675 useful) and paste with @key{C-y} or @key{C-v}.
1676 @end itemize
1677
1678 @item Update sections finished in the English documentation; check
1679 sections status at
1680 @uref{http://lilypondwiki.tuxfamily.org/index.php?title=Documentation_coordination}.
1681
1682 @item Update documentation PO.  It is recommended not to update
1683 strings which come from documentation that is currently deeply revised
1684 in English, to avoid doing the work more than once.
1685
1686 @item Fix broken cross-references by running (from @file{Documentation/})
1687
1688 @example
1689 make ISOLANG=@var{YOUR-LANGUAGE} fix-xrefs
1690 @end example
1691
1692 @noindent
1693 This step requires a sucessful documentation build (with @command{make
1694 doc}).  Some cross-references are broken because they point to a node
1695 that exists in the documentation in English, which has not been added
1696 to the translation; in this case, do not fix the cross-reference but
1697 keep it "broken", so that the resulting HTML link will point to an
1698 existing page of documentation in English.
1699 @end enumerate
1700
1701 @subsubheading Rationale
1702
1703 You may wonder if it would not be better to leave translations as-is
1704 until you can really start updating translations.  There are several
1705 reasons to do these maintenance tasks right now.
1706
1707 @itemize
1708 @item This will have to be done sooner or later anyway, before updating
1709 translation of documentation contents, and this can already be done
1710 without needing to be redone later, as sections of documentation in
1711 English are mostly revised once.  However, note that not all
1712 documentation sectioning has been revised in one go, so all this
1713 maintenance plan has to be repeated whenever a big reorganization is
1714 made.
1715
1716 @item This just makes translated documentation take advantage of the new
1717 organization, which is better than the old one.
1718
1719 @item Moving and renaming sections to match sectioning of documentation in
1720 English simplify future updating work: it allows updating the
1721 translation by side-by-side comparison, without bothering whether
1722 cross-reference names already exist in the translation.
1723
1724 @item Each maintenance task except @q{Updating PO files} can be done by
1725 the same person for all languages, which saves overall time spent by
1726 translators to achieve this task: the node names and section titles
1727 are in English, so you can do.  It is important to take advantage of
1728 this now, as it will be more complicated (but still possible) to do
1729 step 3 in all languages when documentation is compiled with
1730 @command{texi2html} and node names are directly translated in source
1731 files.
1732 @end itemize
1733
1734
1735 @node Managing documentation translation with Git
1736 @unnumberedsubsubsec Managing documentation translation with Git
1737
1738 This policy explains how to manage Git branches and commit
1739 translations to Git.
1740
1741 @itemize
1742 @item Translation changes matching master branch are preferably made on
1743 @code{lilypond/translation} branch; they may be pushed directly to
1744 @code{master} only if they do not break compilation of LilyPond and
1745 its documentation, and in this case they should be pushed to
1746 @code{lilypond/translation} too.  Similarly, changes matching
1747 @code{stable/X.Y} are preferably made on
1748 @code{lilypond/X.Ytranslation}.
1749
1750 @item @code{lilypond/translation} Git branch may be merged into
1751 master only if LilyPond (@command{make all}) and documentation
1752 (@command{make doc}) compile succesfully.
1753
1754 @item @code{master} Git branch may be merged into
1755 @code{lilypond/translation} whenever @command{make} and @command{make
1756 doc} are succesful (in order to ease documentation compilation by
1757 translators), or when significant changes had been made in
1758 documentation in English in master branch.
1759
1760 @item General maintenance may be done by anybody who knows what he does
1761 in documentation in all languages, without informing translators
1762 first.  General maintenance include simple text substitutions
1763 (e.g. automated by sed), compilation fixes, updating Texinfo or
1764 lilypond-book commands, updating macros, updating ly code, fixing
1765 cross-references, and operations described in @ref{Maintaining
1766 without updating translations}.
1767 @end itemize
1768
1769
1770 @node Technical background
1771 @subsection Technical background
1772
1773 A number of Python scripts handle a part of the documentation
1774 translation process.  All scripts used to maintain the translations
1775 are located in @file{scripts/auxiliar/}.
1776
1777 @itemize
1778 @item @file{check_translation.py}  -- show diff to update a translation,
1779 @item @file{texi-langutils.py}  -- quickly and dirtily parse Texinfo files to
1780 make message catalogs and Texinfo skeleton files,
1781 @item @file{texi-skeleton-update.py} -- update Texinfo skeleton files,
1782 @item @file{update-snippets.py} -- synchronize ly snippets with those
1783 from English docs,
1784 @item @file{translations-status.py} -- update translations status pages and word
1785 counts in the file you are reading,
1786 @item @file{tely-gettext.py} -- gettext node names, section titles and references
1787 in the sources; WARNING only use this script once for each file, when support for
1788 "makeinfo --html" has been dropped.
1789 @end itemize
1790
1791 Other scripts are used in the build process, in @file{scripts/build/}:
1792
1793 @itemize
1794 @item @file{mass-link.py} -- link or symlink files between English documentation
1795 and documentation in other languages.
1796 @end itemize
1797
1798 Python modules used by scripts in @file{scripts/auxiliar/} or @file{scripts/build/} (but
1799 not by installed Python scripts) are located in @file{python/auxiliar/}:
1800 @itemize
1801 @item @file{manuals_definitions.py} -- define manual names and name of
1802 cross-reference Texinfo macros,
1803 @item @file{buildlib.py} -- common functions (read piped output
1804 of a shell command, use Git),
1805 @item @file{postprocess_html.py} (module imported by @file{www_post.py}) -- add footer and
1806 tweak links in HTML pages.
1807 @end itemize
1808
1809 And finally
1810 @itemize
1811 @item @file{python/langdefs.py}  -- language definitions module
1812 @end itemize