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::
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
@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
@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.
@@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
+@@menu
+* The set command
+@@end menu
+
+@@node The set command
+@@subsection The @@code@{@@bs@{@}set@} command
+@end example
+
+References to such a node may use the third argument of the
+@code{@@ref} command to display the texually correct heading.
@example
-@@subheading Foo
+@@ref@{The set command,,The @@code@{@@bs@{@}set command@}
@end example
-@item
+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
@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
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
@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
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.
@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
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
@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
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
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.
@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
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/}
@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
@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
@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:
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
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
"
@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.
@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}.
projects / lilypond.git / blobdiff