X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fcontributor%2Fdoc-work.itexi;h=b9f1c7a77e149b7c4bdb6a648affef6ab77ad731;hb=f938685c1aa5af0316d762068577460c8fc663e6;hp=bd7a4aa317e9b8082044abcbd00347b688bd498a;hpb=d0b51cc48c2d66efbd1cbdc682dd622e7a2a93f9;p=lilypond.git diff --git a/Documentation/contributor/doc-work.itexi b/Documentation/contributor/doc-work.itexi index bd7a4aa317..b9f1c7a77e 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 @@ -158,7 +194,7 @@ 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} tage will still be +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. @@ -255,12 +291,12 @@ five, levels. @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 +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. +referenced and are also included in the ToC in HTML. Most of the manual is written at level 4 under headings created with @@ -276,12 +312,17 @@ Level 3 subsections are created with @@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. @@ -295,27 +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: +@@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 -@@subsubsubheading 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 @@ -326,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 @@ -340,23 +401,10 @@ Most LilyPond examples throughout the documentation can be produced with: @example -@@lilypond[verbatim,quote,relative=1] +@@lilypond[verbatim,quote] @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 +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 @@ -399,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 @@ -439,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. @@ -457,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 @@ -633,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 @@ -884,6 +932,18 @@ 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 @@ -1230,15 +1290,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 @@ -1420,7 +1471,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. @@ -1449,13 +1500,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 @@ -1474,12 +1540,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/} @@ -1491,7 +1557,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 @@ -1500,7 +1566,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 @@ -1510,10 +1576,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: @@ -1522,19 +1599,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 @@ -1771,7 +1857,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