X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fcontributor%2Fdoc-work.itexi;h=dabb13beb4b581609003bce4fd6e6c7f0b60138f;hb=b5a72fde8d11be3bbcf2b78d98ece9e513c0de57;hp=cbe4ce2271e58864b3c9eb7ec44b1475955e1dc6;hpb=9a40bd63b77375ac7ac1085d7eda9f5680bf06dd;p=lilypond.git diff --git a/Documentation/contributor/doc-work.itexi b/Documentation/contributor/doc-work.itexi index cbe4ce2271..dabb13beb4 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 @@ -249,6 +255,13 @@ but instead: @@subsection @@code@{Foo@} Bar @end example +@item +With the exception of @code{@@} commands, the section name must +match the node name exactly. + +@item +No commas may be used in the node names. + @item If a heading is desired without creating a @code{@@node}, please use the following: @@ -283,6 +296,90 @@ 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}: + +@example +@@lilypond[papersize=a8landscape,verbatim] +\book @{ + \header @{ + title = "A scale in LilyPond" + @} + \relative @{ + c d e f + @} +@} +@@end lilypond +@end example + +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,quote,ragged-right,texidoc,doctitle] +@{filename.ly@} +@end example + @item Use two spaces for indentation in lilypond examples (no tabs). @@ -326,52 +423,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. @@ -452,8 +503,6 @@ easier/faster processing), use this header: \paper @{ indent = 0\mm line-width = 160\mm - 2.0 * 0.4\in - ragged-right = ##t - force-assignment = #"" line-width = #(- line-width (* mm 3.000000)) @} @@ -1367,24 +1416,7 @@ In order to save build time, a script is available to build only one section of the documentation in English with a default html appearance. -The script is available as: - -@example -scripts/auxiliar/doc-section.sh -@end example - -This script will require customization for your site if your -LilyPond git repository is anyplace but @code{$HOME/lilypond}. - -Assuming that no customization is required, you can setup the -single section build with: - -@example -mkdir $HOME/lilypond/tempdocs -cp $HOME/lilypond/Documentation/out/version.itexi $HOME/lilypond/tempdocs -@end example - -You can then build a section of the documentation with: +You can build a section of the documentation with: @example scripts/auxiliar/doc-section.sh MANUAL SECTION @@ -1400,6 +1432,25 @@ Notation Reference, use the command: scripts/auxiliar/doc-section.sh notation pitches @end example +You can then see the generated document for the section at + +@example +tempdocs/pitches/out/pitches.html +@end example + +According to +@uref{http://code.google.com/p/lilypond/issues/detail?id=1236,Lilypond issue 1236}, +the location of the lilypond git tree is taken from @code{$LILYPOND_GIT} +if specified, otherwise it is auto-detected. + +It is assumed that compilation takes place in the @file{build/} +subdirectory, but this can be overridden by setting the environment +variable @code{LILYPOND_BUILD_DIR}. + +Similarly, output defaults to @file{build/tempdocs/} but this can be +overridden by setting the environment variable +@code{LILYPOND_TEMPDOCS}. + This script will not work for building sections of the Contributors' guide. For building sections of the Contributors' Guide, use: @@ -1417,8 +1468,8 @@ use: scripts/auxiliar/cg-section.sh doc-work @end example -Like @code{doc-section.sh}, @code{cg-section.sh} may need to be customized -for your installation. +@code{cg-section.sh} uses the same environment variables and +corresponding default values as @code{doc-section.sh}. @subheading Stripping whitespace and generating menus @@ -1491,7 +1542,7 @@ take some time before your request or contribution is handled. @node Getting started with documentation translation @subsection Getting started with documentation translation -First, get the sources of branch @code{lilypond/translation} from the +First, get the sources of branch @code{translation} from the Git repository, see @ref{Starting with Git}. @menu @@ -2119,7 +2170,9 @@ useful) and paste with @key{C-y} or @key{C-v}. @item Update sections finished in the English documentation; check sections status at +@smallexample @uref{http://lilypondwiki.tuxfamily.org/index.php?title=Documentation_coordination}. +@end smallexample @item Update documentation PO. It is recommended not to update strings which come from documentation that is currently deeply revised @@ -2182,19 +2235,19 @@ translations to Git. @itemize @item Translation changes matching master branch are preferably made on -@code{lilypond/translation} branch; they may be pushed directly to +@code{translation} branch; they may be pushed directly to @code{master} only if they do not break compilation of LilyPond and its documentation, and in this case they should be pushed to -@code{lilypond/translation} too. Similarly, changes matching +@code{translation} too. Similarly, changes matching @code{stable/X.Y} are preferably made on @code{lilypond/X.Ytranslation}. -@item @code{lilypond/translation} Git branch may be merged into +@item @code{translation} Git branch may be merged into master only if LilyPond (@command{make all}) and documentation (@command{make doc}) compile successfully. @item @code{master} Git branch may be merged into -@code{lilypond/translation} whenever @command{make} and @command{make +@code{translation} whenever @command{make} and @command{make doc} are successful (in order to ease documentation compilation by translators), or when significant changes had been made in documentation in English in master branch.