CG: add warning about announcing a patch.
[lilypond/patrick.git] / Documentation / macros.itexi
blobea63eb63d506ff3b23d877da07e6562aa1eee4d8
1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @ignore
3     Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
5     When revising a translation, copy the HEAD committish of the
6     version that you are working on.  For details, see the Contributors'
7     Guide, node Updating translation committishes..
8 @end ignore
11 @include version.itexi
12 @include common-macros.itexi
14 @ignore
15 ****************************
16 MACRO DEFINITIONS GUIDELINES
17 ****************************
19 This file should contain macro definitions which are common to all
20 languages, i.e. all macro definitions which do not contain text that
21 should be translated (namely text visible in the output).
23 Macro definitions which contain text that should be translated in
24 translations should be in macros.itexi.
25 @end ignore
27 @c   ***** Displaying text *****
29 @c To get decent quotes in `foo' and ``foo''.
31 @macro q{TEXT}
32 @quoteleft{}\TEXT\@quoteright{}
33 @end macro
35 @macro qq{TEXT}
36 @quotedblleft{}\TEXT\@quotedblright{}
37 @end macro
40 @ifhtml
42 @macro warning{TEXT}
43 @html
44 <div class="warning">
45 @end html
46 @strong{Note:} \TEXT\
47 @c keep the space for proper nesting of </p>
49 @html
50 </div>
51 @end html
52 @end macro
54 @end ifhtml
56 @ifnothtml
58 @macro warning{TEXT}
59 @quotation
60 @quotation
61 @cartouche
62 @b{Note:} \TEXT\
63 @end cartouche
64 @end quotation
65 @end quotation
66 @end macro
68 @end ifnothtml
70 @c do not translate the following macro -- it is used in
71 @c an untranslated manual.
73 @ifhtml
75 @macro advanced{TEXT}
76 @html
77 <div class="advanced">
78 @end html
79 @strong{Advanced note:} \TEXT\
80 @c keep the space for proper nesting of </p>
82 @html
83 </div>
84 @end html
85 @end macro
87 @end ifhtml
89 @ifnothtml
91 @macro advanced{TEXT}
92 @quotation
93 @b{Advanced note:} \TEXT\
94 @end quotation
95 @end macro
97 @end ifnothtml
100 @macro docMain
101 @cartouche
102 For more information about how this manual fits with the other
103 documentation, or to read this manual in other formats, see
104 @rweb{Manuals}.
106 If you are missing any manuals, the complete documentation can be
107 found at @w{@uref{http://@/www@/.lilypond@/.org/}}.
108 @end cartouche
109 @end macro
112 @macro lilyTitlePage{TITLE}
113 @c  This produces the unified index
114 @syncodeindex fn cp
115 @syncodeindex vr cp
118 @c   ***** Copyright stuff *****
119 @ifset FDL
120 @copying
121 @copyrightDeclare
123 @quotation
124 Permission is granted to copy, distribute and/or modify this document
125 under the terms of the GNU Free Documentation License, Version 1.1
126 or any later version published by the Free Software Foundation;
127 with no Invariant Sections.
128 A copy of the license is included in the section entitled ``GNU
129 Free Documentation License''.
130 @end quotation
131 @end copying
132 @end ifset
134 @ifclear FDL
135 @copying
136 This document has been placed in the public domain.
137 @end copying
138 @end ifclear
142 @c   ***** Title page *****
143 @ifnottex
144 @node Top
145 @top LilyPond --- \TITLE\
147 @cartouche
148 @manualIntro{}
149 @end cartouche
150 @end ifnottex
152 @finalout
154 @titlepage
155 @title LilyPond
156 @subtitle The music typesetter
157 @titlefont{\TITLE\}
158 @author The LilyPond development team
160 @vskip 60pt
162 @cartouche
163 @manualIntro{}
164 @end cartouche
166 @vskip 40pt
168 @docMain{}
170 @vskip 0pt plus 1filll
172 @insertcopying
174 For LilyPond version @version{}
175 @end titlepage
177 @end macro
180 @c   ***** Headings in a doc subsection *****
182 @c The next macro is a dummy currently since texinfo doesn't
183 @c provide a real ragged-right environment yet.
185 @c Don't insert an empty line after @predefined!  Right now
186 @c it doesn't matter, but a future implementation will probably
187 @c add some code which needs this restriction.
189 @macro predefined
190 @noindent
191 @subsubheading Predefined commands
192 @end macro
194 @c Due to a bug in texi2html (texi2html.pl CVS versions <= 1.245)
195 @c the next macro must not be empty.
197 @macro endpredefined
199 @end macro
202 @macro snippets
203 @noindent
204 @subsubheading Selected Snippets
205 @end macro
208 @c Don't insert an empty line after @seealso!  Otherwise we get
209 @c unwanted extra vertical space in the PDF output.
211 @macro seealso
212 @noindent
213 @subsubheading See also
214 @indent
215 @end macro
218 @macro knownissues
219 @noindent
220 @subsubheading Known issues and warnings
221 @end macro
225 @c   ***** Links and references *****
227 @c  Definitions for references:
229 @c     @rweb
230 @c     @ressay
231 @c     @rglos
232 @c     @rinternals
233 @c     @rlearning
234 @c     @rlsr
235 @c     @rprogram
236 @c     @ruser
237 @c     @rchanges
238 @c     @rextend
239 @c     @rcontrib
241 @c  All these also have a @...named version which allows to specify the
242 @c  displayed text for the reference as second argument.
244 @c ***** HTML + bigpage is a special case (other manual names); all other
245 @c formats are treated similarly.
248 @c *** not TeX ***
250 @ifnottex
252 @c ** bigpage **
254 @ifset bigpage
256 @macro rglos{TEXT}
257 @vindex \TEXT\
258 @ref{\TEXT\,,,music-glossary-big-page,Music Glossary}
259 @end macro
261 @macro rglosnamed{TEXT,DISPLAY}
262 @vindex \TEXT\
263 @ref{\TEXT\,,\DISPLAY\,music-glossary-big-page,Music Glossary}
264 @end macro
266 @macro rlearning{TEXT}
267 @vindex \TEXT\
268 @ref{\TEXT\,,,learning-big-page,Learning Manual}
269 @end macro
271 @macro rlearningnamed{TEXT,DISPLAY}
272 @vindex \TEXT\
273 @ref{\TEXT\,,\DISPLAY\,learning-big-page,Learning Manual}
274 @end macro
276 @macro ruser{TEXT}
277 @vindex \TEXT\
278 @ref{\TEXT\,,,notation-big-page,Notation Reference}
279 @end macro
281 @macro rusernamed{TEXT,DISPLAY}
282 @vindex \TEXT\
283 @ref{\TEXT\,,\DISPLAY\,notation-big-page,Notation Reference}
284 @end macro
286 @macro rextend{TEXT}
287 @vindex \TEXT\
288 @ref{\TEXT\,,,extending-big-page,Extending}
289 @end macro
291 @macro rextendnamed{TEXT,DISPLAY}
292 @vindex \TEXT\
293 @ref{\TEXT\,,\DISPLAY\,extending-big-page,Extending}
294 @end macro
296 @macro rchanges{TEXT}
297 @vindex \TEXT\
298 @ref{\TEXT\,,,changes-big-page,Changes}
299 @end macro
301 @macro rchangesnamed{TEXT,DISPLAY}
302 @vindex \TEXT\
303 @ref{\TEXT\,,\DISPLAY\,changes-big-page,Changes}
304 @end macro
306 @macro rcontrib{TEXT}
307 @vindex \TEXT\
308 @ref{\TEXT\,,,contributor-big-page,Contributor's Guide}
309 @end macro
311 @macro rcontribnamed{TEXT,DISPLAY}
312 @vindex \TEXT\
313 @ref{\TEXT\,,\DISPLAY\,contributor-big-page,Contributor's Guide}
314 @end macro
316 @macro rweb{TEXT}
317 @vindex \TEXT\
318 @ref{\TEXT\,,,web-big-page,General Information}
319 @end macro
321 @macro rwebnamed{TEXT,DISPLAY}
322 @vindex \TEXT\
323 @ref{\TEXT\,,\DISPLAY\,web-big-page,General Information}
324 @end macro
326 @macro ressay{TEXT}
327 @vindex \TEXT\
328 @ref{\TEXT\,,,essay-big-page,Essay}
329 @end macro
331 @macro ressaynamed{TEXT,DISPLAY}
332 @vindex \TEXT\
333 @ref{\TEXT\,,\DISPLAY\,essay-big-page,Essay}
334 @end macro
336 @macro rprogram{TEXT}
337 @vindex \TEXT\
338 @ref{\TEXT\,,,usage-big-page,Application Usage}
339 @end macro
341 @macro rprogramnamed{TEXT,DISPLAY}
342 @vindex \TEXT\
343 @ref{\TEXT\,,\DISPLAY\,usage-big-page,Application Usage}
344 @end macro
346 @macro rlsr{TEXT}
347 @ref{\TEXT\,,,snippets-big-page,Snippets}
348 @end macro
350 @macro rlsrnamed{TEXT,DISPLAY}
351 @ref{\TEXT\,,\DISPLAY\,snippets-big-page,Snippets}
352 @end macro
354 @macro rinternals{TEXT}
355 @vindex \TEXT\
356 @ref{\TEXT\,,,internals-big-page,Internals Reference}
357 @end macro
359 @macro rinternalsnamed{TEXT,DISPLAY}
360 @vindex \TEXT\
361 @ref{\TEXT\,,\DISPLAY\,internals-big-page,Internals Reference}
362 @end macro
364 @end ifset
367 @c ** not bigpage **
369 @ifclear bigpage
371 @ifnotinfo
373 @macro rglos{TEXT}
374 @vindex \TEXT\
375 @ref{\TEXT\,,,music-glossary,Music Glossary}
376 @end macro
378 @macro rglosnamed{TEXT,DISPLAY}
379 @vindex \TEXT\
380 @ref{\TEXT\,,\DISPLAY\,music-glossary,Music Glossary}
381 @end macro
383 @macro rlearning{TEXT}
384 @vindex \TEXT\
385 @ref{\TEXT\,,,learning,Learning Manual}
386 @end macro
388 @macro rlearningnamed{TEXT,DISPLAY}
389 @vindex \TEXT\
390 @ref{\TEXT\,,,learning,Learning Manual}
391 @end macro
393 @macro ruser{TEXT}
394 @vindex \TEXT\
395 @ref{\TEXT\,,,notation,Notation Reference}
396 @end macro
398 @macro rusernamed{TEXT,DISPLAY}
399 @vindex \TEXT\
400 @ref{\TEXT\,,\DISPLAY\,notation,Notation Reference}
401 @end macro
403 @macro rchanges{TEXT}
404 @vindex \TEXT\
405 @ref{\TEXT\,,,changes,Changes}
406 @end macro
408 @macro rchangesnamed{TEXT,DISPLAY}
409 @vindex \TEXT\
410 @ref{\TEXT\,,\DISPLAY\,changes,Changes}
411 @end macro
413 @macro rextend{TEXT}
414 @vindex \TEXT\
415 @ref{\TEXT\,,,extending,Extending}
416 @end macro
418 @macro rextendnamed{TEXT,DISPLAY}
419 @vindex \TEXT\
420 @ref{\TEXT\,,\DISPLAY\,extending,Extending}
421 @end macro
423 @macro rcontrib{TEXT}
424 @vindex \TEXT\
425 @ref{\TEXT\,,,contributor,Contributor's Guide}
426 @end macro
428 @macro rcontribnamed{TEXT,DISPLAY}
429 @vindex \TEXT\
430 @ref{\TEXT\,,\DISPLAY\,contributor,Contributor's Guide}
431 @end macro
433 @macro rweb{TEXT}
434 @vindex \TEXT\
435 @ref{\TEXT\,,,web,General Information}
436 @end macro
438 @macro rwebnamed{TEXT,DISPLAY}
439 @vindex \TEXT\
440 @ref{\TEXT\,,\DISPLAY\,web,General Information}
441 @end macro
443 @macro ressay{TEXT}
444 @vindex \TEXT\
445 @ref{\TEXT\,,,essay,Essay}
446 @end macro
448 @macro ressaynamed{TEXT,DISPLAY}
449 @vindex \TEXT\
450 @ref{\TEXT\,,\DISPLAY\,essay,Essay}
451 @end macro
453 @macro rprogram{TEXT}
454 @vindex \TEXT\
455 @ref{\TEXT\,,,usage,Application Usage}
456 @end macro
458 @macro rprogramnamed{TEXT,DISPLAY}
459 @vindex \TEXT\
460 @ref{\TEXT\,,\DISPLAY\,usage,Application Usage}
461 @end macro
463 @macro rlsr{TEXT}
464 @ref{\TEXT\,,,snippets,Snippets}
465 @end macro
467 @macro rlsrnamed{TEXT,DISPLAY}
468 @ref{\TEXT\,,\DISPLAY\,snippets,Snippets}
469 @end macro
471 @macro rinternals{TEXT}
472 @vindex \TEXT\
473 @ref{\TEXT\,,,internals,Internals Reference}
474 @end macro
476 @macro rinternalsnamed{TEXT,DISPLAY}
477 @vindex \TEXT\
478 @ref{\TEXT\,,\DISPLAY\,internals,Internals Reference}
479 @end macro
481 @end ifnotinfo
483 @ifinfo
485 @macro rglos{TEXT}
486 @vindex \TEXT\
487 @ref{\TEXT\,,,music-glossary,Music Glossary}
488 @end macro
490 @macro rglosnamed{TEXT,DISPLAY}
491 @vindex \TEXT\
492 @ref{\TEXT\,,\DISPLAY\,music-glossary,Music Glossary}
493 @end macro
495 @macro rlearning{TEXT}
496 @vindex \TEXT\
497 @ref{\TEXT\,,,lilypond-learning,Learning Manual}
498 @end macro
500 @macro rlearningnamed{TEXT,DISPLAY}
501 @vindex \TEXT\
502 @ref{\TEXT\,,,lilypond-learning,Learning Manual}
503 @end macro
505 @macro ruser{TEXT}
506 @vindex \TEXT\
507 @ref{\TEXT\,,,lilypond-notation,Notation Reference}
508 @end macro
510 @macro rusernamed{TEXT,DISPLAY}
511 @vindex \TEXT\
512 @ref{\TEXT\,,\DISPLAY\,lilypond-notation,Notation Reference}
513 @end macro
515 @macro rchanges{TEXT}
516 @vindex \TEXT\
517 @ref{\TEXT\,,,lilypond-changes,Changes}
518 @end macro
520 @macro rchangesnamed{TEXT,DISPLAY}
521 @vindex \TEXT\
522 @ref{\TEXT\,,\DISPLAY\,lilypond-changes,Changes}
523 @end macro
525 @macro rextend{TEXT}
526 @vindex \TEXT\
527 @ref{\TEXT\,,,lilypond-extending,Extending}
528 @end macro
530 @macro rextendnamed{TEXT,DISPLAY}
531 @vindex \TEXT\
532 @ref{\TEXT\,,\DISPLAY\,lilypond-extending,Extending}
533 @end macro
535 @macro rcontrib{TEXT}
536 @vindex \TEXT\
537 @ref{\TEXT\,,,lilypond-contributor,Contributor's Guide}
538 @end macro
540 @macro rcontribnamed{TEXT,DISPLAY}
541 @vindex \TEXT\
542 @ref{\TEXT\,,\DISPLAY\,lilypond-contributor,Contributor's Guide}
543 @end macro
545 @macro rweb{TEXT}
546 @vindex \TEXT\
547 @ref{\TEXT\,,,lilypond-web,General Information}
548 @end macro
550 @macro rwebnamed{TEXT,DISPLAY}
551 @vindex \TEXT\
552 @ref{\TEXT\,,\DISPLAY\,lilypond-web, General Information}
553 @end macro
555 @macro ressay{TEXT}
556 @vindex \TEXT\
557 @ref{\TEXT\,,,lilypond-essay,Essay}
558 @end macro
560 @macro ressaynamed{TEXT,DISPLAY}
561 @vindex \TEXT\
562 @ref{\TEXT\,,\DISPLAY\,lilypond-essay,Essay}
563 @end macro
565 @macro rprogram{TEXT}
566 @vindex \TEXT\
567 @ref{\TEXT\,,,lilypond-usage,Application Usage}
568 @end macro
570 @macro rprogramnamed{TEXT,DISPLAY}
571 @vindex \TEXT\
572 @ref{\TEXT\,,\DISPLAY\,lilypond-usage,Application Usage}
573 @end macro
575 @macro rlsr{TEXT}
576 @ref{\TEXT\,,,lilypond-snippets,Snippets}
577 @end macro
579 @macro rlsrnamed{TEXT,DISPLAY}
580 @ref{\TEXT\,,\DISPLAY\,lilypond-snippets,Snippets}
581 @end macro
583 @macro rinternals{TEXT}
584 @vindex \TEXT\
585 @ref{\TEXT\,,,lilypond-internals,Internals Reference}
586 @end macro
588 @macro rinternalsnamed{TEXT,DISPLAY}
589 @vindex \TEXT\
590 @ref{\TEXT\,,\DISPLAY\,lilypond-internals,Internals Reference}
591 @end macro
593 @end ifinfo
595 @end ifclear
597 @end ifnottex
600 @c *** TeX ***
602 @iftex
604 @c All commands below should work in the middle of the line;
605 @c we thus must not use @vindex directly since it works only if placed
606 @c on a line of its own.  To overcome this problem, we define a
607 @c replacement macro using the internal definition of @vindex which
608 @c delimits arguments in the standard way (i.e., with braces).
610 @tex
611 \gdef\lilyvindex#1{\doind{vr}{\code{#1}}\ignorespaces}
612 @end tex
614 @macro rglos{TEXT}
615 @lilyvindex{\TEXT\}
616 @ref{\TEXT\,,,music-glossary,Music Glossary}
617 @end macro
619 @macro rglosnamed{TEXT,DISPLAY}
620 @lilyvindex{\TEXT\}
621 @ref{\TEXT\,,\DISPLAY\,music-glossary,Music Glossary}
622 @end macro
624 @macro rlearning{TEXT}
625 @lilyvindex{\TEXT\}
626 @ref{\TEXT\,,,learning,Learning Manual}
627 @end macro
629 @macro rlearningnamed{TEXT,DISPLAY}
630 @lilyvindex{\TEXT\}
631 @ref{\TEXT\,,\DISPLAY\,learning,Learning Manual}
632 @end macro
634 @macro ruser{TEXT}
635 @lilyvindex{\TEXT\}
636 @ref{\TEXT\,,,notation,Notation Reference}
637 @end macro
639 @macro rusernamed{TEXT,DISPLAY}
640 @lilyvindex{\TEXT\}
641 @ref{\TEXT\,,\DISPLAY\,notation,Notation Reference}
642 @end macro
644 @macro rchanges{TEXT}
645 @lilyvindex{\TEXT\}
646 @ref{\TEXT\,,,changes,Changes}
647 @end macro
649 @macro rchangesnamed{TEXT,DISPLAY}
650 @lilyvindex{\TEXT\}
651 @ref{\TEXT\,,\DISPLAY\,changes,Changes}
652 @end macro
654 @macro rextend{TEXT}
655 @lilyvindex{\TEXT\}
656 @ref{\TEXT\,,,extending,Extending}
657 @end macro
659 @macro rextendnamed{TEXT,DISPLAY}
660 @lilyvindex{\TEXT\}
661 @ref{\TEXT\,,\DISPLAY\,extending,Extending}
662 @end macro
664 @macro rcontrib{TEXT}
665 @lilyvindex{\TEXT\}
666 @ref{\TEXT\,,,contributor,Contributor's Guide}
667 @end macro
669 @macro rcontribnamed{TEXT,DISPLAY}
670 @lilyvindex{\TEXT\}
671 @ref{\TEXT\,,\DISPLAY\,contributor,Contributor's Guide}
672 @end macro
674 @macro rweb{TEXT}
675 @lilyvindex{\TEXT\}
676 @ref{\TEXT\,,,web,General Information}
677 @end macro
679 @macro rwebnamed{TEXT,DISPLAY}
680 @lilyvindex{\TEXT\}
681 @ref{\TEXT\,,\DISPLAY\,web,General Information}
682 @end macro
684 @macro ressay{TEXT}
685 @lilyvindex{\TEXT\}
686 @ref{\TEXT\,,,essay,Essay}
687 @end macro
689 @macro ressaynamed{TEXT,DISPLAY}
690 @lilyvindex{\TEXT\}
691 @ref{\TEXT\,,\DISPLAY\,essay,Essay}
692 @end macro
694 @macro rprogram{TEXT}
695 @lilyvindex{\TEXT\}
696 @ref{\TEXT\,,,usage,Application Usage}
697 @end macro
699 @macro rprogramnamed{TEXT,DISPLAY}
700 @lilyvindex{\TEXT\}
701 @ref{\TEXT\,,\DISPLAY\,usage,Application Usage}
702 @end macro
704 @macro rlsr{TEXT}
705 @lilyvindex{\TEXT\}
706 @ref{\TEXT\,,,snippets,Snippets}
707 @end macro
709 @macro rlsrnamed{TEXT,DISPLAY}
710 @lilyvindex{\TEXT\}
711 @ref{\TEXT\,,\DISPLAY\,snippets,Snippets}
712 @end macro
714 @macro rinternals{TEXT}
715 @lilyvindex{\TEXT\}
716 @ref{\TEXT\,,,internals,Internals Reference}
717 @end macro
719 @macro rinternalsnamed{TEXT,DISPLAY}
720 @lilyvindex{\TEXT\}
721 @ref{\TEXT\,,\DISPLAY\,internals,Internals Reference}
722 @end macro
724 @end iftex
726 @c  ***** Macros specific to the web site *****
728 @ifset web
730 @macro exampleImage{IMAGE-FILE}
731 @html
732 <div class="float-center">
733   <a class="clickable" href="ly-examples/\IMAGE-FILE\.png">
734     <img src="ly-examples/\IMAGE-FILE\-small.png" alt="\IMAGE-FILE\">
735   </a>
736   <p style="text-align: center">
737     (click to enlarge)
738   </p>
739 </div>
740 @end html
741 @iftex
742 @image{ly-examples/\IMAGE-FILE\-small,,,\IMAGE-FILE\,png}
743 @end iftex
744 @ifinfo
745 @image{lilypond/ly-examples/\IMAGE-FILE\,,,\IMAGE-FILE\,png}
746 @end ifinfo
747 @end macro
749 @macro help{TEXT}
750 @html
751 <div class="help">
752 <strong>
753   <span style="text-decoration:blink">Help wanted:</span>
754 </strong> \TEXT\
755 </div>
756 @end html
757 @end macro
760 @c LEGALESE
762 @macro logoLegalLinux
763 Tux the Linux Penguin was created by
764 @uref{mailto:lewing@@isc.tamu.edu, lewing@@isc.tamu.edu} with
765 @uref{http://www.isc.tamu.edu/~lewing/gimp/, the Gnu Image
766 Manipulation Program}.
768 @end macro
770 @macro logoLegalFreeBSD
771 The FreeBSD logo is a registered trademark of
772 @uref{http://www.freebsd.org/, The FreeBSD Foundation}.
774 @end macro
776 @macro logoLegalMacOSX
777 The @qq{X image} is not a registered trademark.  It was created by
778 @uref{http://en.wikipedia.org/wiki/User:Nihonjoe, Nihonjoe} and
779 @uref{http://en.wikipedia.org/wiki/User:CyberSkull, CyberSkull}, and
780 placed under the GNU Free Documentation License version 1.2 or later.
781 We found the image on
782 @uref{http://commons.wikimedia.org/wiki/File:Mac_OS_X_Userbox_X.png,
783 this Wikimedia Commons page}.
785 @end macro
787 @macro logoLegalWindows
788 The @qq{four colored rectangles image} is not a registered
789 trademark.  It was created by
790 @uref{http://en.wikipedia.org/wiki/User:Rohitbd, Rohitbd} and
791 placed under the GNU Free Documentation License version 1.2.  We
792 found the image on
793 @uref{http://commons.wikimedia.org/wiki/Category:Microsoft_Windows_logos,
794 this Wikimedia Commons page}.
796 @end macro
798 @end ifset