X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fcontributor%2Fdoc-work.itexi;h=1ac3076a43131cec1230d8e98cc343cda4203f87;hb=a0112838d85cb2187e3b27f24f68f8f51fb90fea;hp=b1bcd14d1f7a584be2a47adb170fb0ffeeb16f63;hpb=95a4237d0aca94993bd3b91afc4ff0e4e2daec9f;p=lilypond.git diff --git a/Documentation/contributor/doc-work.itexi b/Documentation/contributor/doc-work.itexi index b1bcd14d1f..1ac3076a43 100644 --- a/Documentation/contributor/doc-work.itexi +++ b/Documentation/contributor/doc-work.itexi @@ -84,11 +84,17 @@ Please write exact changes to the text. @item A formal patch to the source code is @emph{not} required; we can -take care of the technical details. Here is an example of a -perfect documentation report: +take care of the technical details. + +@item +Send the suggestions to the @code{bug-lilypond} mailing list as +discussed in @rweb{Contact}. + +@item +Here is an example of a perfect documentation report: @verbatim -To: lilypond-devel@gnu.org +To: bug-lilypond@gnu.org From: helpful-user@example.net Subject: doc addition @@ -283,6 +289,88 @@ construct. These are easily constructed with automatic tools; see @itemize +@item +Most LilyPond examples throughout the documentation can be produced +with: + +@example +@@lilypond[verbatim,quote,relative=1] +@end example + +or + +@example +@@lilypond[verbatim,quote,relative=2] +@end example + +If using any combination of @code{\header@{@}}, @code{\score@{@}} or +@code{\layout@{@}} in your example, then you must omit the +@code{relative} variable and either use absolute entry mode or an +explicit @code{\relative@{@}} construction. + +If using @code{\book@{@}} in your example then you must also omit the +@code{relative} variable and either use absolute entry mode or an +explicit @code{\relative@{@}} construction. However, you must also +include the @code{papersize=X} variable, where @code{X} is a defined +paper size from within @file{scm/paper.scm}. This is to avoid the +default @code{a4} paper size being used and leaving too much unnecessary +whitespace and potentially awkward page breaks in the PDFs. + +The preferred @code{papersize}s are @code{a5}, @code{a6} or +@code{a8landscape}. + +@code{a8landscape} works best for a single measure with a single title +and/or single @code{tagline}: + +@lilypond[papersize=a8landscape,verbatim] +\book { + \header { + title = "A scale in LilyPond" + } + \relative { + c d e f + } +} +@end lilypond + +and can also be used to easily show features that require page breaks +(i.e. page numbers) without taking large amounts of space within the +documentation. Do not use the @code{quote} option with this paper size. + +@code{a5} or @code{a6} paper sizes are best used for examples that have +more than two measures of music or require multiple staves (i.e. to +illustrate cross-staff features, RH and LH parts etc.) and where +@code{\book@{@}} constructions are required or where @code{a8landscape} +produces an example that is too cramped. Depending on the example the +@code{quote} option may need to be omitted. + +In rare cases, other options may be used (or omitted), but ask first. + +@item +Please avoid using extra spacing either after or within the +@code{@@lilypond} parameters. + +@example +not: @@lilypond [verbatim, quote, relative=1] +but instead: @@lilypond[verbatim,quote,relative=1] +@end example + +@item +Inspirational headwords are produced with: + +@example +@@lilypondfile[quote,ragged-right,line-width=16\cm,staffsize=16] +@{pitches-headword.ly@} +@end example + +@item +LSR snippets are linked with: + +@example +@@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle] +@{filename.ly@} +@end example + @item Use two spaces for indentation in lilypond examples (no tabs). @@ -326,52 +414,6 @@ but instead: \override TextScript #'padding = #3 c1^"hi" @end example -@item -Most LilyPond input should be produced with: - -@example -@@lilypond[verbatim,quote,relative=2] -@end example - -@noindent -or - -@example -@@lilypond[verbatim,quote,relative=1] -@end example - -Please avoid using extra spacing either after or within the -@code{@@lilypond} parameters. - -@example -not: @@lilypond [verbatim, quote, relative=1] -but instead: @@lilypond[verbatim,quote,relative=1] -@end example - -If you want to use @code{\layout@{@}} or define variables, use - -@example -@@lilypond[verbatim,quote] -@end example - -In rare cases, other options may be used (or omitted), but ask first. - -@item -Inspirational headwords are produced with - -@example -@@lilypondfile[quote,ragged-right,line-width=16\cm,staffsize=16] -@{pitches-headword.ly@} -@end example - -@item -LSR snippets are linked with - -@example -@@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle] -@{filename.ly@} -@end example - @noindent excepted in Templates, where `doctitle' may be omitted. @@ -441,7 +483,7 @@ Beam, slur and tie marks should begin immediately after the first note with beam and phrase marks ending immediately after the last. @example -a8(\ ais16[ b cis( d] b) cis4~ b' cis,\) +a8\( ais16[ b cis( d] b) cis4~ b' cis,\) @end example @item @@ -1058,6 +1100,9 @@ Notation Reference: Application Usage: @@rprogram@{blah@}. +Essay on automated music engraving: +@@ressay@{yadda@}. + Extending LilyPond: @@rextend@{frob@}. @@ -1735,12 +1780,12 @@ When you encounter in the source, open @file{Documentation/snippets/@var{filename}.ly}, translate the @code{texidoc} header field it contains, enclose it with @code{texidoc@var{MY-LANGUAGE} = "} and @code{"}, and write it into -@file{Documentation/@var{MY-LANGUAGE}/texidocs/@var{filename}.texidoc}. +@file{Documentation/@var{MY-LANGUAGE}/texidocs/@/@var{filename}.texidoc}. Additionally, you may translate the snippet's title in @code{doctitle} header field, in case @code{doctitle} is a fragment option used in @code{@@lilypondfile}; you can do this exactly the same way as @code{texidoc}. For instance, -@file{Documentation/@var{MY-LANGUAGE}/texidocs/@var{filename}.texidoc} +@file{Documentation/@var{MY-LANGUAGE}/texidocs/@/@var{filename}.texidoc} may contain @example