they also stem from attempting to find the most effective use of
limited documentation help.
+Before undertaking any large documentation work, contributors are
+encouraged to contact the @ref{Meisters, Documentation Meister}.
+
@node Documentation suggestions
@section Documentation suggestions
@itemize
@item
-Please leave two blank lines above a @@node; this makes it
+Please leave two blank lines above a @code{@@node}; this makes it
easier to find sections in texinfo.
@item
-If a heading is desired without creating a node, please use
+Do not use any @code{@@} commands for a @code{@@node}. They may be
+used for any @code{@@sub...} sections or headings however.
+
+@example
+not:
+@@node @@code@{Foo@} Bar
+@@subsection @@code@{Foo@} Bar
+
+but instead:
+@@node Foo Bar
+@@subsection @@code@{Foo@} Bar
+@end example
+
+@item
+If a heading is desired without creating a @code{@@node}, please use
the following:
@example
@end example
@item
-Sectioning commands (@@node and @@section) must not appear
-inside an @@ignore. Separate those commands with a space, ie
-@@n@tie{}ode.
+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
@itemize
@item
-Use two spaces for indentation in lilypond examples. (no
-tabs)
-
-@item
-All text strings should be prefaced with #. LilyPond does
-not strictly require this, but it is helpful to get users
-accustomed to this scheme construct. ie @code{\set
-Staff.instrumentName = #"cello"}
+Use two spaces for indentation in lilypond examples (no tabs).
@item
All engravers should have double-quotes around them:
\consists "Spans_arpeggio_engraver"
@end example
-Again, LilyPond does not strictly require this, but it is a useful
-standard to follow.
+LilyPond does not strictly require this, but it is a useful
+convention to follow.
+
+@item
+All context or layout object strings should be prefaced with @code{#}.
+Again, LilyPond does not strictly require this, but it is helpful
+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
+context or layout properties outside of an @code{@@example} or @code{@@lilypond}, unless
+the description explicitly requires it.
+
+ie @qq{...setting the @code{transparent} property leaves the object where it
+is, but makes it invisible.}
@item
If possible, only write one bar per line.
@item
Tweaks should, if possible, also occur on their own line.
-Bad:
-
-@example
-\override textscript #'padding = #3 c1^"hi"
-@end example
-
-Good:
-
@example
-\override textscript #'padding = #3
-c1^"hi"
+not: \override TextScript #'padding = #3 c1^"hi"
+but instead: \override TextScript #'padding = #3
+ c1^"hi"
@end example
@item
@@lilypond[verbatim,quote,relative=1]
@end example
-If you want to use \layout@{@} or define variables, use
+If you want to use @code{\layout@{@}} or define variables, use
@example
@@lilypond[verbatim,quote]
the line(s) to which they refer.
@item
-Add extra spaces around @{ @} marks; ie
+For clarity, always use @{ @} marks even if they are not technically
+required; ie
+
+@example
+not:
+
+\context Voice \repeat unfold 2 \relative c' @{
+ c2 d
+@}
+
+but instead:
+
+\context Voice @{
+ \repeat unfold 2 @{
+ \relative c' @{
+ c2 d
+ @}
+ @}
+@}
+@end example
+
+@item
+Add a space around @{ @} marks; ie
@example
-not: \chordmode @{c e g@}
+not: \chordmode@{c e g@}
but instead: \chordmode @{ c e g @}
@end example
+@item
+Use @{ @} marks for additional @code{\markup} format comands; ie
+
+@example
+not: c^\markup \tiny\sharp
+but instead: c^\markup @{ \tiny \sharp @}
+@end example
+
+@item
+Remove any space around @code{<} @code{>} marks; ie
+
+@example
+not: < c e g > 4
+but instead: <c e g>4
+@end example
+
+@item
+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,\)
+@end example
+
@item
If you want to work on an example outside of the manual (for
easier/faster processing), use this header:
@end example
You may not change any of these values. If you are making an
-example demonstrating special \paper@{@} values, contact the
+example demonstrating special @code{\paper@{@}} values, contact the
Documentation Editor.
@end itemize
@item
@code{@@uref@{@var{URL}[, @var{link text}]@}} --- link to an
-external url.
+external url. Use within an @code{@@example ... @@end example}.
+
+@example
+@@example
+@@uref@{URL [, link text ]@}
+@@end example
+@end example
@end itemize
contains spaces, use @code{@@w@{@@code@{@dots{}@}@}} or
@code{@@w@{@@samp@{@dots{}@}@}} to prevent unexpected line breaks.
+The Texinfo settings @code{txicodequoteundirected} and
+@code{txicodequotebacktick} are both set in the manuals, so
+backticks (@code{`}) and apostrophes (@code{'}) placed within
+blocks of @code{@@code}, @code{@@example}, or @code{@@verbatim}
+are not converted to left- and right-angled quotes
+(@code{@quoteleft{} @quoteright{}}) as they normally are within
+the text, so the apostrophes in
+@q{@w{@code{@@w@{@@code@{@bs{}relative c''@}@}}}} will display
+correctly. However, these settings do not affect the PDF output
+for anything within a @code{@@samp} block (even if it includes a
+nested @code{@@code} block), so entering
+@q{@code{@@w@{@@samp@{@bs{}relative c''@}@}}} wrongly produces
+@q{@w{@code{@bs{}relative c@quoteright{}@quoteright{}}}} in PDF.
+Consequently, if you want to use a @code{@@samp@{@dots{}@}} block
+which contains backticks or apostrophes, you should instead use
+@q{@code{@@q@{@@code@{@dots{}@}@}}} (or
+@q{@code{@@q@{@@w@{@@code@{@dots{}@}@}@}}} if the block also
+contains spaces). Note that backslashes within
+@code{@@q@{@dots{}@}} blocks must be entered as @samp{@@bs@{@}},
+so the example above would be coded as
+@q{@code{@@q@{@@w@{@@code@{@@bs@{@}relative c''@}@}@}}}.
+
@item
@code{@@command@{@dots{}@}} --- Use for command-line commands (eg.
@samp{@@command@{lilypond-book@}}).
least the documentation so that you can check the output yourself and
more quickly; if you are interested, see @ref{Compiling}.
+Before undertaking any large translation work, contributors are
+encouraged to contact the @ref{Meisters, Translation Meister}.
+
@node Which documentation can be translated
@unnumberedsubsubsec Which documentation can be translated
@seeCommittishesUpdate
-@warning{translation status generation is currently broken, so
-translation status pages have been removed; it will be regenerated again
-as soon as possible, in Texinfo format.}
-
Global state of the translation is recorded in
-@file{Documentation/translations.html.in}, which is used to generate
+@file{Documentation/translations.itexi}, which is used to generate
Translations status page. To update that page, do from
@file{Documentation/}
@seealso
@ref{Maintaining without updating translations}.
-
@node Updating documentation translation
@unnumberedsubsubsec Updating documentation translation
@seealso
@ref{LSR work}.
-
@node Translations management policies
@subsection Translations management policies
projects / lilypond.git / blobdiff