Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(718)

Side by Side Diff: Documentation/contributor/doc-work.itexi

Issue 4445070: Doc: Adjusted CG Policy on @lilypond[] variables (Closed)
Patch Set: another draft with corrections Created 12 years, 11 months ago
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
View unified diff | Download patch
« no previous file with comments | « no previous file | no next file » | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
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
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]
Graham Percival (old account) 2011/05/03 12:36:26 this is a .itexi, not a .itely, so you can't use @
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
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
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
OLDNEW
« no previous file with comments | « no previous file | no next file » | no next file with comments »

Powered by Google App Engine
RSS Feeds Recent Issues | This issue
This is Rietveld f62528b