X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fcontributor%2Fdoc-work.itexi;h=701e2dcff99915bbe892e5db942af84c6d9e843d;hb=68dbc841e3401f14b900f6750ebb49b406caf357;hp=cdf0e26f8d518de9487f8198bc53f7c3054ad0ff;hpb=af60e9b57f205a3c2e044ac8db351b42ef3e26ad;p=lilypond.git diff --git a/Documentation/contributor/doc-work.itexi b/Documentation/contributor/doc-work.itexi index cdf0e26f8d..701e2dcff9 100644 --- a/Documentation/contributor/doc-work.itexi +++ b/Documentation/contributor/doc-work.itexi @@ -9,11 +9,12 @@ this allows us to generate different output formats from a single set of source files. To organize multiple authors working on the documentation, we use a -Version Control System (VCS) called git, previously discussed in +Version Control System (VCS) called Git, previously discussed in @ref{Starting with Git}. @menu * Introduction to documentation work:: +* version in documentation files:: * Documentation suggestions:: * Texinfo introduction and usage policy:: * Documentation policy:: @@ -66,6 +67,41 @@ Before undertaking any large documentation work, contributors are encouraged to contact the @ref{Meisters, Documentation Meister}. +@node version in documentation files +@section @code{\version} in documentation files + +Every documentation file which includes LilyPond code must begin +with a @code{\version} statement, since the build procedure +explicitly tests for its presence and will not continue otherwise. +The @code{\version} statement should reference a version of LilyPond +consistent with the syntax of the contained code. + +Since the @code{\version} statement is not valid Texinfo input it +must be commented out like this: + +@example +@@c \version "2.19.1" +@end example + +So, if you are adding LilyPond code which is not consistent with the +current version header, you should + +@enumerate + +@item +run convert-ly on the file using the latest version of LilyPond +(which should, if everybody has done proper maintenance, not change +anything); + +@item +add the new code; + +@item +modify the version number to match the new code. + +@end enumerate + + @node Documentation suggestions @section Documentation suggestions @@ -146,20 +182,42 @@ Please prepare a formal git patch. @end enumerate +@subheading Contributions that contain examples using overrides + +Examples that use overrides, tweaks, customer Scheme functions etc. are +(with very few exceptions) not included in the main text of the manuals; +as there would be far too many, equally useful, candidates. + +The correct way is to submit your example, with appropriate explanatory +text and tags, to the LilyPond Snippet Repository (LSR). Snippets that +have the @qq{docs} tag can then be easily added as a +@emph{selected snippet} in the documentation. It will also appear +automatically in the Snippets lists. See @ref{Introduction to LSR}. + +Snippets that @emph{don't} have the @qq{docs} tag will still be +searchable and viewable within the LSR, but will be not be included in +the Snippets list or be able to be included as part of the main +documentation. + +Generally, any new snippets that have the @qq{docs} tag are more +carefully checked for syntax and formatting. + +@subheading Announcing your snippet + Once you have followed these guidelines, please send a message to lilypond-devel with your documentation submissions. Unfortunately -there is a strict “no top-posting” check on the mailing list; to avoid +there is a strict @q{no top-posting} check on the mailing list; to avoid this, add: -> I'm not top posting. +@code{> I'm not top posting} + +(you must include the > ) to the top of your documentation addition. -(you must include the > ) to the top of your documentation -addition. +We may edit your suggestion for spelling, grammar, or style, and we may +not place the material exactly where you suggested, but if you give us +some material to work with, we can improve the manual much faster. -We may edit your suggestion for spelling, grammar, or style, and -we may not place the material exactly where you suggested, but if -you give us some material to work with, we can improve the manual -much faster. Thanks for your interest! +Thanks for your interest! @node Texinfo introduction and usage policy @@ -221,27 +279,50 @@ how to modify the snippet files and SL, see @ref{LSR work}. @node Sectioning commands @subsection Sectioning commands -Most of the manual operates at the +The Notation Reference uses section headings at four, occasionally +five, levels. + +@itemize + +@item Level 1: @@chapter +@item Level 2: @@section +@item Level 3: @@subsection +@item Level 4: @@unnumberedsubsubsec +@item Level 5: @@subsubsubheading +@end itemize + +The first three levels are numbered in HTML, the last two are not. +Numbered sections correspond to a single HTML page in the split HTML +documents. + +The first four levels always have accompanying nodes so they can be +referenced and are also included in the ToC in HTML. + +Most of the manual is written at level 4 under headings created with @example @@node Foo -@@subsubsection Foo +@@unnumberedsubsubsec Foo @end example -@noindent -level. Sections are created with +Level 3 subsections are created with @example @@node Foo @@subsection Foo @end example -@itemize -@item +Level 4 headings and menus must be preceded by level 3 headings and +menus, and so on for level 3 and level 2. If this is not what is +wanted, please use: + +@example +@@subsubsubheading Foo +@end example + Please leave two blank lines above a @code{@@node}; this makes it easier to find sections in texinfo. -@item Do not use any @code{@@} commands for a @code{@@node}. They may be used for any @code{@@sub...} sections or headings however. @@ -255,28 +336,47 @@ but instead: @@subsection @@code@{Foo@} Bar @end example -@item -With the exception of @code{@@} commands, the section name must -match the node name exactly. +No punctuation may be used in the node names. If the heading text +uses punctuation (in particular, colons and commas) simply leave +this out of the node name and menu. -@item -No commas may be used in the node names. +@example +@@menu +* Foo Bar:: +@@end menu -@item -If a heading is desired without creating a @code{@@node}, please use -the following: +@@node Foo Bar +@@subsection Foo: Bar +@end example + +Backslashes must not be used in node names or section headings. +If the heading text should include a backslash simply leave this +out of the node name and menu and replace it with @code{@@bs@{@}} +in the heading text. @example -@@subheading Foo +@@menu +* The set command +@@end menu + +@@node The set command +@@subsection The @@code@{@@bs@{@}set@} command @end example -@item +References to such a node may use the third argument of the +@code{@@ref} command to display the texually correct heading. + +@example +@@ref@{The set command,,The @@code@{@@bs@{@}set command@} +@end example + +With the exception of @code{@@} commands, @code{\} commands and +punctuation, the section name should match the node name exactly. + Sectioning commands (@code{@@node} and @code{@@section}) must not appear inside an @code{@@ignore}. Separate those commands with a space, ie @code{@@n}@tie{}@code{ode}. -@end itemize - Nodes must be included inside a @example @@ -287,8 +387,8 @@ Nodes must be included inside a @end example @noindent -construct. These are easily constructed with automatic tools; see -@ref{Scripts to ease doc work}. +construct. These can be constructed with scripts: +see @ref{Stripping whitespace and generating menus}. @node LilyPond formatting @@ -301,23 +401,10 @@ 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] +@@lilypond[verbatim,quote] @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 +If using @code{\book@{@}} in your example then 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 @@ -360,8 +447,8 @@ 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] +not: @@lilypond [verbatim, quote, fragment] +but instead: @@lilypond[verbatim,quote,fragment] @end example @item @@ -400,7 +487,7 @@ to get users accustomed to this scheme construct, i.e. @code{\set Staff.instrumentName = #"cello"} @item -Try to avoid using @code{#'} or @code{#`} within when describing +Try to avoid using @code{#'} or @code{#`} when describing context or layout properties outside of an @code{@@example} or @code{@@lilypond}, unless the description explicitly requires it. @@ -418,8 +505,8 @@ checks. @item Tweaks should, if possible, also occur on their own line. @example -not: \override TextScript #'padding = #3 c1^"hi" -but instead: \override TextScript #'padding = #3 +not: \override TextScript.padding = #3 c1^"hi" +but instead: \override TextScript.padding = #3 c1^"hi" @end example @@ -594,7 +681,7 @@ command ;) Enter the exact @code{@@node} name of the target reference between the brackets (eg.@tie{}@w{@samp{@@ref@{Syntax survey@}}}). Do not split a cross-reference across two lines -- this causes the -cross-reference to be rendered incorrectly in html documents. +cross-reference to be rendered incorrectly in HTML documents. @itemize @item @@ -845,6 +932,19 @@ the same format as @code{@@enumerate}. Do not use @node Special characters @unnumberedsubsubsec Special characters +@warning{In Texinfo, the backslash is an ordinary character, and +is entered without escaping (e.g. +@samp{The@tie{}@@code@{@bs{}foo@}@tie{}command}). However, within +double-quoted Scheme and/or LilyPond strings, backslashes +(including those ending up in Texinfo markup) need to be escaped +by doubling them: +@example +(define (foo x) + "The @@code@{@bs{}@bs{}foo@} command..." + ...) +@end example +} + @itemize @item @code{--}, @code{---} --- Create an en dash (--) or an em dash @@ -1191,15 +1291,6 @@ Note that you have to find yourself the source files to fix cross-references in the generated documentation such as the Internals Reference; e.g. you can grep scm/ and lily/. -@c temporary? how long will kainhofer be used? -gp -Also of interest may be the linkdoc checks on kainhofer.com. Be -warned that these docs are not completely rebuilt every day, so it -might not accurately reflect the current state of the docs. - -@example -@uref{http://kainhofer.com/~lilypond/linkdoc/} -@end example - @node General writing @subsection General writing @@ -1381,7 +1472,7 @@ good example of this. On the other side of this, @example -\override Score.Hairpin #'after-line-breaking = ##t +\override Score.Hairpin.after-line-breaking = ##t @end example clearly belongs in LSR. @@ -1410,13 +1501,28 @@ the difficulty. @node Scripts to ease doc work @section Scripts to ease doc work -@subheading Building only one section of the documentation +@menu +* Scripts to test the documentation:: +* Scripts to create documentation:: +@end menu + +@node Scripts to test the documentation +@subsection Scripts to test the documentation + +@menu +* Building only one section of the documentation:: +@end menu + +@node Building only one section of the documentation +@unnumberedsubsubsec Building only one section of the documentation In order to save build time, a script is available to build only -one section of the documentation in English with a default html +one section of the documentation in English with a default HTML appearance. -You can build a section of the documentation with: +If you do not yet have a @file{build/} subdirectory within the LilyPond +Git tree, you should create this first. You can then build a section of +the documentation with the following command: @example scripts/auxiliar/doc-section.sh MANUAL SECTION @@ -1435,12 +1541,12 @@ scripts/auxiliar/doc-section.sh notation pitches You can then see the generated document for the section at @example -tempdocs/pitches/out/pitches.html +build/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} +@uref{https://sourceforge.net/p/testlilyissues/issues/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/} @@ -1452,7 +1558,7 @@ 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' +Contributors' Guide. For building sections of the Contributors' Guide, use: @example @@ -1461,7 +1567,7 @@ scripts/auxiliar/cg-section.sh SECTION @noindent where @code{SECTION} is the name of the file containing the sections -to be built. For example, to build section 4 of the Contributors' guide, +to be built. For example, to build section 4 of the Contributors' Guide, use: @example @@ -1471,10 +1577,21 @@ scripts/auxiliar/cg-section.sh doc-work @code{cg-section.sh} uses the same environment variables and corresponding default values as @code{doc-section.sh}. -@subheading Stripping whitespace and generating menus +@node Scripts to create documentation +@subsection Scripts to create documentation + +@menu +* Stripping whitespace and generating menus:: +* Stripping whitespace only:: +* Updating doc with convert-ly:: +@end menu + +@node Stripping whitespace and generating menus +@unnumberedsubsubsec Stripping whitespace and generating menus @warning{This script assumes that the file conforms to our doc -policy; a few files still need work in this regard.} +policy, in particular with regard to @ref{Sectioning commands}; +a few files still need work in this regard.} To automatically regenerate @code{@@menu} portions and strip whitespace, use: @@ -1483,19 +1600,28 @@ whitespace, use: scripts/auxiliar/node-menuify.py @var{FILENAME} @end example +If you are adding documentation that requires new menus, +you will need to add a blank @code{@@menu} section: + +@example +@@menu +@@end menu +@end example -@subheading Stripping whitespace only +@node Stripping whitespace only +@unnumberedsubsubsec Stripping whitespace only @c TODO: should this be documented elsewhere? It's useful for @c more than just docs. To remove extra whitespace from the ends of lines, run @example -scripts/auxiliar/strip-whitespace.py Documentation/FILENAME +scripts/auxiliar/strip-whitespace.py @var{FILENAME} @end example -@subheading Updating doc with @command{convert-ly} +@node Updating doc with convert-ly +@unnumberedsubsubsec Updating doc with @command{convert-ly} Don't. This should be done by programmers when they add new features. If you notice that it hasn't been done, complain to @@ -1732,7 +1858,7 @@ will be handled by someone who will translate it to English and send it on bug-lilypond or add an issue in the tracker, then translate back the reply from developers. -@item @rweb{Help us}: this page should be translated very freely, +@item @rcontrib{Help us}: this page should be translated very freely, and possibly not at all: ask help for contributing to LilyPond for tasks that LilyPond community in your language is able and going to handle. @end itemize @@ -1804,11 +1930,6 @@ Spanish translation blah " @end example -@noindent -Then, you should get these translated strings into compiled snippets in -@file{Documentation/snippets}, see @q{General guidelines} in @ref{Adding -and editing snippets}. - @code{@@example} blocks need not be verbatim copies, e.g. variable names, file names and comments should be translated. @@ -2003,11 +2124,6 @@ the changes it made with @command{git diff} before committing; if you don't do so, some @code{@@lilypond} snippets might be broken or make no sense in their context. -When you have updated texidocs in -@file{Documentation/@var{MY-LANGUAGE}/texidocs}, you can get these -changes into compiled snippets in @file{Documentation/snippets}, see -@q{General guidelines} in @ref{Adding and editing snippets}. - Finally, a command runs the three update processes above for all enabled languages (from @file{Documentation/}): @@ -2042,27 +2158,21 @@ by doing git rev-list HEAD |head -1 @end example -A special case is updating Snippet documentation strings in -@file{Documentation/@var{MY-LANGUAGE}/texidocs}. For these to be -correctly marked as up-to-date, first run @code{makelsr.py} as -explained in @ref{Adding and editing snippets}, and commit the -resulting compiled snippets left in @file{Documentation/snippets/}. -Say the SHA1 ID code of this commit is . Now edit again your -translated files in @file{Documentation/@var{MY-LANGUAGE}/texidocs} -adjusting the 40-digit committish that appears in the text to be ; -finally, commit these updated files. Not doing so would result in -changes made both to your updates and original snippets to -persistently appear in the check-translation output as if they were -out of sync. - -This two-phase mechanism avoids the (practically) unsolvable problem -of guessing what committish will have our update, and pretending to -put this very committish on the files in the same commit. - @c http://lists.gnu.org/archive/html/lilypond-devel/2009-01/msg00245.html @c contains a helper script which could be used to perform massive @c committish updates. +Most of the changes in the LSR snippets included in the documentation concern +the syntax, not the description inside @code{texidoc=""}. This implies that +quite often you will have to update only the committish of the matching +.texidoc file. This can be a tedious work if there are many snippets to be +marked as up do date. You can use the following command to update the +committishes at once: + +@example +cd Documentation/LANG/texidocs +sed -i -r 's/[0-9a-z]@{40@}/NEW-COMMITTISH/' *.texidoc +@end example @seealso @ref{LSR work}.