OLD | NEW |
1 @c -*- coding: utf-8; mode: texinfo; -*- | 1 @c -*- coding: utf-8; mode: texinfo; -*- |
2 @node Documentation work | 2 @node Documentation work |
3 @chapter Documentation work | 3 @chapter Documentation work |
4 | 4 |
5 There are currently 11 manuals for LilyPond, not including the | 5 There are currently 11 manuals for LilyPond, not including the |
6 translations. Each book is available in HTML, PDF, and info. The | 6 translations. Each book is available in HTML, PDF, and info. The |
7 documentation is written in a language called @code{texinfo} -- | 7 documentation is written in a language called @code{texinfo} -- |
8 this allows us to generate different output formats from a single | 8 this allows us to generate different output formats from a single |
9 set of source files. | 9 set of source files. |
10 | 10 |
(...skipping 272 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
283 construct. These are easily constructed with automatic tools; see | 283 construct. These are easily constructed with automatic tools; see |
284 @ref{Scripts to ease doc work}. | 284 @ref{Scripts to ease doc work}. |
285 | 285 |
286 | 286 |
287 @node LilyPond formatting | 287 @node LilyPond formatting |
288 @subsection LilyPond formatting | 288 @subsection LilyPond formatting |
289 | 289 |
290 @itemize | 290 @itemize |
291 | 291 |
292 @item | 292 @item |
| 293 Most LilyPond examples throughout the documentation can be produced |
| 294 with: |
| 295 |
| 296 @example |
| 297 @@lilypond[verbatim,quote,relative=1] |
| 298 @end example |
| 299 |
| 300 or |
| 301 |
| 302 @example |
| 303 @@lilypond[verbatim,quote,relative=2] |
| 304 @end example |
| 305 |
| 306 If using any combination of @code{\header@{@}}, @code{\score@{@}} or |
| 307 @code{\layout@{@}} in your example, then you must omit the |
| 308 @code{relative} variable and either use absolute entry mode or an |
| 309 explicit @code{\relative@{@}} construction. |
| 310 |
| 311 If using @code{\book@{@}} in your example then you must also omit the |
| 312 @code{relative} variable and either use absolute entry mode or an |
| 313 explicit @code{\relative@{@}} construction. However, you must also |
| 314 include the @code{papersize=X} variable, where @code{X} is a defined |
| 315 paper size from within @file{scm/paper.scm}. This is to avoid the |
| 316 default @code{a4} paper size being used and leaving too much unnecessary |
| 317 whitespace and potentially awkward page breaks in the PDFs. |
| 318 |
| 319 The preferred @code{papersize}s are @code{a5}, @code{a6} or |
| 320 @code{a8landscape}. |
| 321 |
| 322 @code{a8landscape} works best for a single measure with a single title |
| 323 and/or single @code{tagline}: |
| 324 |
| 325 @lilypond[papersize=a8landscape,verbatim] |
| 326 \book { |
| 327 \header { |
| 328 title = "A scale in LilyPond" |
| 329 } |
| 330 \relative { |
| 331 c d e f |
| 332 } |
| 333 } |
| 334 @end lilypond |
| 335 |
| 336 and can also be used to easily show features that require page breaks |
| 337 (i.e. page numbers) without taking large amounts of space within the |
| 338 documentation. Do not use the @code{quote} option with this paper size. |
| 339 |
| 340 @code{a5} or @code{a6} paper sizes are best used for examples that have |
| 341 more than two measures of music or require multiple staves (i.e. to |
| 342 illustrate cross-staff features, RH and LH parts etc.) and where |
| 343 @code{\book@{@}} constructions are required or where @code{a8landscape} |
| 344 produces an example that is too cramped. Depending on the example the |
| 345 @code{quote} option may need to be omitted. |
| 346 |
| 347 In rare cases, other options may be used (or omitted), but ask first. |
| 348 |
| 349 @item |
| 350 Please avoid using extra spacing either after or within the |
| 351 @code{@@lilypond} parameters. |
| 352 |
| 353 @example |
| 354 not: @@lilypond [verbatim, quote, relative=1] |
| 355 but instead: @@lilypond[verbatim,quote,relative=1] |
| 356 @end example |
| 357 |
| 358 @item |
| 359 Inspirational headwords are produced with: |
| 360 |
| 361 @example |
| 362 @@lilypondfile[quote,ragged-right,line-width=16\cm,staffsize=16] |
| 363 @{pitches-headword.ly@} |
| 364 @end example |
| 365 |
| 366 @item |
| 367 LSR snippets are linked with: |
| 368 |
| 369 @example |
| 370 @@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle] |
| 371 @{filename.ly@} |
| 372 @end example |
| 373 |
| 374 @item |
293 Use two spaces for indentation in lilypond examples (no tabs). | 375 Use two spaces for indentation in lilypond examples (no tabs). |
294 | 376 |
295 @item | 377 @item |
296 All engravers should have double-quotes around them: | 378 All engravers should have double-quotes around them: |
297 | 379 |
298 @example | 380 @example |
299 \consists "Spans_arpeggio_engraver" | 381 \consists "Spans_arpeggio_engraver" |
300 @end example | 382 @end example |
301 | 383 |
302 LilyPond does not strictly require this, but it is a useful | 384 LilyPond does not strictly require this, but it is a useful |
(...skipping 22 matching lines...) Expand all Loading... |
325 checks. | 407 checks. |
326 | 408 |
327 @item | 409 @item |
328 Tweaks should, if possible, also occur on their own line. | 410 Tweaks should, if possible, also occur on their own line. |
329 @example | 411 @example |
330 not: \override TextScript #'padding = #3 c1^"hi" | 412 not: \override TextScript #'padding = #3 c1^"hi" |
331 but instead: \override TextScript #'padding = #3 | 413 but instead: \override TextScript #'padding = #3 |
332 c1^"hi" | 414 c1^"hi" |
333 @end example | 415 @end example |
334 | 416 |
335 @item | |
336 Most LilyPond input should be produced with: | |
337 | |
338 @example | |
339 @@lilypond[verbatim,quote,relative=2] | |
340 @end example | |
341 | |
342 @noindent | |
343 or | |
344 | |
345 @example | |
346 @@lilypond[verbatim,quote,relative=1] | |
347 @end example | |
348 | |
349 Please avoid using extra spacing either after or within the | |
350 @code{@@lilypond} parameters. | |
351 | |
352 @example | |
353 not: @@lilypond [verbatim, quote, relative=1] | |
354 but instead: @@lilypond[verbatim,quote,relative=1] | |
355 @end example | |
356 | |
357 If you want to use @code{\layout@{@}} or define variables, use | |
358 | |
359 @example | |
360 @@lilypond[verbatim,quote] | |
361 @end example | |
362 | |
363 In rare cases, other options may be used (or omitted), but ask first. | |
364 | |
365 @item | |
366 Inspirational headwords are produced with | |
367 | |
368 @example | |
369 @@lilypondfile[quote,ragged-right,line-width=16\cm,staffsize=16] | |
370 @{pitches-headword.ly@} | |
371 @end example | |
372 | |
373 @item | |
374 LSR snippets are linked with | |
375 | |
376 @example | |
377 @@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle] | |
378 @{filename.ly@} | |
379 @end example | |
380 | |
381 @noindent | 417 @noindent |
382 excepted in Templates, where `doctitle' may be omitted. | 418 excepted in Templates, where `doctitle' may be omitted. |
383 | 419 |
384 @item | 420 @item |
385 Avoid long stretches of input code. Nobody is going to read | 421 Avoid long stretches of input code. Nobody is going to read |
386 them in print. Create small examples. However, this does not mean | 422 them in print. Create small examples. However, this does not mean |
387 it has be minimal. | 423 it has be minimal. |
388 | 424 |
389 @item | 425 @item |
390 Specify durations for at least the first note of every bar. | 426 Specify durations for at least the first note of every bar. |
(...skipping 1860 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
2251 @item @file{buildlib.py} -- common functions (read piped output | 2287 @item @file{buildlib.py} -- common functions (read piped output |
2252 of a shell command, use Git), | 2288 of a shell command, use Git), |
2253 @item @file{postprocess_html.py} (module imported by @file{www_post.py}) -- add
footer and | 2289 @item @file{postprocess_html.py} (module imported by @file{www_post.py}) -- add
footer and |
2254 tweak links in HTML pages. | 2290 tweak links in HTML pages. |
2255 @end itemize | 2291 @end itemize |
2256 | 2292 |
2257 And finally | 2293 And finally |
2258 @itemize | 2294 @itemize |
2259 @item @file{python/langdefs.py} -- language definitions module | 2295 @item @file{python/langdefs.py} -- language definitions module |
2260 @end itemize | 2296 @end itemize |
OLD | NEW |