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
-Sectioning commands (@@node and @@section) must not appear
-inside an @@ignore. Separate those commands with a space, ie @@n
-ode.
+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
+@@subheading Foo
+@end example
+
+@item
+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: \chordmode @{c e g@}
+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@}
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
@subsection Text formatting
@itemize
-
@item
Lines should be less than 72 characters long. (We personally
recommend writing with 66-char lines, but do not bother modifying
-existing material). However, see the note below regarding line
-lengths within @code{@@example} blocks.
-
-@item
-Individual lines within an @code{@@example} block should not
-exceed 74 characters; otherwise they will run into the margin in
-the pdf output, and may get clipped. If an @code{@@example} block
-is part of an @code{@@item} within an @code{@@itemize} or
-@code{@@enumerate} block, each line of the @code{@@example} should
-not exceed 70 columns---each additional level of @code{@@itemize}
-or @code{@@enumerate} shortens the line by about 4 columns.
-
-For command line examples, if possible, use a trailing backslash
-to break up a single line, indenting the next line with 2 spaces.
-If this isn't feasible, use @code{@@smallexample ...
-@@end@tie{}smallexample} instead, which uses a smaller fontsize.
-Use @code{@@example} whenever possible, but if needed,
-@code{@@smallexample} can fit up to 96 characters per line before
-running into the pdf margin. Each additional level of
-@code{@@itemize} or @code{@@enumerate} shortens a
-@code{@@smallexample} line by about 5 columns.
+existing material). Also see the recommendations for fixed-width
+fonts in the @ref{Syntax survey}.
@item
Do not use tabs.
through the code}. If you really want to refer to a context, use
@code{@@code@{@}} in the main text and @code{@@rinternals@{@}} in
the @code{@@seealso}.
+@end itemize
-@item
-Variables or numbers which consist of a single character (probably
-followed by a punctuation mark) should be tied properly, either to
-the previous or the next word. Example:
-@example
-The variable@@tie@{@}@@var@{a@} ...
-@end example
+@node Syntax survey
+@subsection Syntax survey
-@item
-To get consistent indentation in the DVI output it is better to
-avoid the @code{@@verbatim} environment. Use the @code{@@example}
-environment instead if possible, but without extraneous
-indentation. For example, this
-@example
-@@example
- foo @{
- bar
- @}
-@@end example
-@end example
+@menu
+* Comments::
+* Cross references::
+* External links::
+* Fixed-width font::
+* Indexing::
+* Lists::
+* Special characters::
+* Miscellany::
+@end menu
-@noindent
-should be replaced with
-@example
-@@example
-foo @{
- bar
-@}
-@@end example
-@end example
+@node Comments
+@unnumberedsubsubsec Comments
-@noindent
-where @q{@code{@@example}} starts the line (without leading
-spaces).
+@itemize
+@item
+@code{@@c @dots{}} --- single line comment. @samp{@@c NOTE:} is a
+comment which should remain in the final version. (gp only
+command ;)
@item
-Do not compress the input vertically; that is, do not use
+@code{@@ignore} --- multi-line comment:
@example
-Beginning of logical unit
-@@example
-...
-@@end example
-continuation of logical unit
+@@ignore
+@dots{}
+@@end ignore
@end example
+@end itemize
-@noindent
-but instead do
-@example
-Beginning of logical unit
+@node Cross references
+@unnumberedsubsubsec Cross references
-@@example
-...
-@@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.
-@@noindent
-continuation of logical unit
-@end example
+@itemize
+@item
+@code{@@ref@{@dots{}@}} --- link within current manual.
-This makes it easier to remember the @q{@code{@@noindent}}. Only
-use @code{@@noindent} if the material is discussing the same
-material; new material should simply begin without anything
-special on the line above it.
+@item
+@code{@@rchanges@{@dots{}@}} --- link to Changes.
@item
-in @code{@@itemize} and @code{@@enumerate} blocks, use
-@code{@@item} on a separate line like this:
+@code{@@rcontrib@{@dots{}@}} --- link to Contributor's Guide.
-@example
-@@itemize
-@@item
-Foo
+@item
+@code{@@ressay@{@dots{}@}} --- link to Engraving Essay.
-@@item
-Bar
-@end example
+@item
+@code{@@rextend@{@dots{}@}} --- link to Extending LilyPond.
-Do not use @code{@@itemize@tie{}@@bullet}.
+@item
+@code{@@rglos@{@dots{}@}} --- link to the Music Glossary.
@item
-To get LilyPond version, use @code{@@version@{@}} (this does not
-work inside LilyPond snippets). If you write
-@code{"@@version@{@}"} (enclosed with quotes), or generally if
-@code{@@version@{@}} is not followed by a space, there will be an
-ugly line break in PDF output unless you enclose it with
+@code{@@rinternals@{@dots{}@}} --- link to the Internals Reference.
-@example
-@@w@{ ... @}
+@item
+@code{@@rlearning@{@dots{}@}} --- link to Learning Manual.
- e.g.
+@item
+@code{@@rlsr@{@dots{}@}} --- link to a Snippet section.
-@@w@{"@@version@{@}"@}
-@end example
+@item
+@code{@@rprogram@{@dots{}@}} --- link to Application Usage.
+
+@item
+@code{@@ruser@{@dots{}@}} --- link to Notation Reference.
+@item
+@code{@@rweb@{@dots{}@}} --- link to General Informaion.
@end itemize
-@node Syntax survey
-@subsection Syntax survey
+@node External links
+@unnumberedsubsubsec External links
@itemize
@item
-@code{@@bs} --- Generates a backslash inside @code{@@warning}.
-Any @q{@bs{}} used inside @code{@@warning} (and @code{@@q} or
-@code{@@qq}) must be written as @q{@code{@@bs@{@}}} (texinfo would
-also allow @q{@bs{}@bs{}}, but this breaks with PDF output).
+@code{@@email@{@dots{}@}} --- create a @code{mailto:} E-mail link.
@item
-@code{@@c} --- single line comments. @qq{@code{@@c NOTE:}} is a
-comment which should remain in the final version. (gp only
-command ;)
+@code{@@uref@{@var{URL}[, @var{link text}]@}} --- link to an
+external url. Use within an @code{@@example ... @@end example}.
-@item
-@code{@@cindex} --- General index. Please add as many as you can.
-Don't capitalize the first word.
+@example
+@@example
+@@uref@{URL [, link text ]@}
+@@end example
+@end example
+@end itemize
-@item
-@code{@@code@{@}} --- typeset in a tt-font. Use for actual
-LilyPond code or property/context names. If the name contains a
-space, wrap the entire thing inside @code{@@w@{@@code@{ @}@}}.
-@item
-@code{@@example ... @@end example} --- example text that should be
-set as a blockquote. Any @code{@{@tie{}@}} must be escaped with
-@code{@@@{@tie{}@@@}}.
+@node Fixed-width font
+@unnumberedsubsubsec Fixed-width font
+@itemize
@item
-@code{@@funindex} --- is for a \lilycommand.
+@code{@@code@{@dots{}@}}, @code{@@samp@{@dots{}@}} ---
+
+Use the @code{@@code@{@dots{}@}} command for individual
+language-specific tokens (keywords, commands, engravers, scheme
+symbols, etc.). Ideally, a single @code{@@code@{@dots{}@}} block
+should fit within one line in the PDF output. Use the
+@code{@@samp@{@dots{}@}} command when you have a short example of
+user input, unless it constitutes an entire @code{@@item} by
+itself, in which case @code{@@code@{@dots{}@}} is preferable.
+Otherwise, both should only be used when part of a larger sentence
+within a paragraph or @code{@@item}. Never use a
+@code{@@code@{@dots{}@}} or @code{@@samp@{@dots{}@}} block as a
+free-standing paragraph; use @code{@@example} instead.
+
+A single unindented line in the PDF has space for about 79
+fixed-width characters (76 if indented). Within an @code{@@item}
+there is space for about 75 fixed-width characters. Each
+additional level of @code{@@itemize} or @code{@@enumerate}
+shortens the line by about 4 columns.
+
+However, even short blocks of @code{@@code@{@dots{}@}} and
+@code{@@samp@{@dots{}@}} can run into the margin if the Texinfo
+line-breaking algorithm gets confused. Additionally, blocks that
+are longer than this may in fact print nicely; it all depends
+where the line breaks end up. If you compile the docs yourself,
+check the PDF output to make sure the line breaks are
+satisfactory.
+
+The Texinfo setting @code{@@allowcodebreaks} is set to
+@code{false} in the manuals, so lines within
+@code{@@code@{@dots{}@}} or @code{@@samp@{@dots{}@}} blocks will
+only break at spaces, not at hyphens or underscores. If the block
+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@}}).
+
+@item
+@code{@@example} --- Use for examples of program code. Do not add
+extraneous indentation (ie. don't start every line with
+whitespace). Use the following layout (notice the use of blank
+lines). Omit the @code{@@noindent} if the text following the
+example starts a new paragraph:
-@item
-@code{@@ignore ... @@end ignore} --- multi-line comment
+@example
+@var{@dots{}text leading into the example@dots{}}
-@item
-@code{@@itemize @@item A @@item B ... @@end itemize} --- for
-bulleted lists. Do not compress vertically like this.
+@@example
+@dots{}
+@@end example
-@item
-@code{@@notation@{@}} --- refers to pieces of notation, e.g.
-@qq{@code{@@notation@{clef}.@}}. Also use for specific lyrics
-(@qq{the @code{@@notation@{}A@tie{}-@tie{}men@} is centered}).
-Only use once per subsection per term.
+@@noindent
+@var{continuation of the text@dots{}}
+@end example
-@item
-@code{@@q@{@}} --- Single quotes. Used for @q{vague} terms.
+Individual lines within an @code{@@example} block should not
+exceed 74 characters; otherwise they will run into the margin in
+the PDF output, and may get clipped. If an @code{@@example} block
+is part of an @code{@@item}, individual lines in the
+@code{@@example} block should not exceed 70 columns. Each
+additional level of @code{@@itemize} or @code{@@enumerate}
+shortens the line by about 4 columns.
+
+For long command line examples, if possible, use a trailing
+backslash to break up a single line, indenting the next line with
+2 spaces. If this isn't feasible, use @samp{@@smallexample
+@dots{} @@end@tie{}smallexample} instead, which uses a smaller
+fontsize. Use @code{@@example} whenever possible, but if needed,
+@code{@@smallexample} can fit up to 90 characters per line before
+running into the PDF margin. Each additional level of
+@code{@@itemize} or @code{@@enumerate} shortens a
+@code{@@smallexample} line by about 5 columns.
@item
-@code{@@qq@{@}} --- Double quotes. Used for actual quotes (@qq{he
-said}) or for introducing special input modes.
+@code{@@file@{@dots{}@}} --- Use for filenames and directories.
@item
-@code{@@rchanges@{@}} --- link to Changes.
+@code{@@option@{@dots{}@}} --- Use for options to command-line
+commands (eg. @samp{@@option@{--format@}}).
@item
-@code{@@rcontrib@{@}} --- link to Contributor's Guide.
+@code{@@verbatim} --- Prints the block exactly as it appears in
+the source file (including whitespace, etc.). For program code
+examples, use @code{@@example} instead. @code{@@verbatim} uses
+the same format as @code{@@example}.
+
+Individual lines within an @code{@@verbatim} block should not
+exceed 74 characters; otherwise they will run into the margin in
+the PDF output, and may get clipped. If an @code{@@verbatim}
+block is part of an @code{@@item}, individual lines in the
+@code{@@verbatim} block should not exceed 70 columns. Each
+additional level of @code{@@itemize} or @code{@@enumerate}
+shortens the line by about 4 columns.
+@end itemize
-@item
-@code{@@ref@{@}} --- link within current manual (type the exact
-node name inside the @code{@{@}}).
+@node Indexing
+@unnumberedsubsubsec Indexing
+
+@itemize
@item
-@code{@@ressay@{@}} --- link to Engraving Essay.
+@code{@@cindex @dots{}} --- General index. Please add as many as you can.
+Don't capitalize the first word.
@item
-@code{@@rextend@{@}} --- link to Extending LilyPond.
+@code{@@funindex @dots{}} --- is for a \lilycommand.
+@end itemize
+
+
+@node Lists
+@unnumberedsubsubsec Lists
+@itemize
@item
-@code{@@rglos@{@}} --- link to the Music Glossary.
+@code{@@enumerate} --- Create an ordered list (with numbers).
+Always put @samp{@@item} on its own line, and separate consecutive
+items with a blank line:
+
+@example
+@@enumerate
+@@item
+Foo
+
+@@item
+Bar
+@@end enumerate
+@end example
@item
-@code{@@rinternals@{@}} --- link to the Internals Reference.
+@code{@@itemize} --- Create an unordered list (with bullets). Use
+the same format as @code{@@enumerate}. Do not use
+@samp{@@itemize@tie{}@@bullet}.
+@end itemize
+
+@node Special characters
+@unnumberedsubsubsec Special characters
+
+@itemize
@item
-@code{@@rlearning@{@}} --- link to Learning Manual.
+@code{--}, @code{---} --- Create an en dash (--) or an em dash
+(---) in the text. To print two or three literal hyphens in a
+row, wrap one of them in a @code{@@w@{@dots{}@}} (eg.
+@samp{-@@w@{-@}-}).
@item
-@code{@@rlsr@{@}} --- link to a Snippet section.
+@code{@@@@}, @code{@@@{}, @code{@@@}} --- Create an at-sign (@@),
+a left curly bracket (@{), or a right curly bracket (@}).
@item
-@code{@@rprogram@{@}} --- link to Application Usage.
+@code{@@bs@{@}} --- Create a backslash within a
+@code{@@q@{@dots{}@}}, @code{@@qq@{@dots{}@}}, or
+@code{@@warning@{@dots{}@}} block. This is a custom LilyPond
+macro, not a builtin @@-command in Texinfo. Texinfo would also
+allow @samp{\\}, but this breaks the PDF output.
@item
-@code{@@ruser@{@}} --- link to Notation Reference.
+@code{@@tie@{@}} --- Create a @emph{variable-width} non-breaking
+space in the text (use @w{@samp{@@w@{ @}}} for a single
+@emph{fixed-width} non-breaking space). Variables or numbers
+which consist of a single character (probably followed by a
+punctuation mark) should be tied properly, either to the previous
+or the next word. Example: @samp{The letter@@tie@{@}@@q@{I@} is
+skipped}
+@end itemize
+
+@node Miscellany
+@unnumberedsubsubsec Miscellany
+
+@itemize
@item
-@code{@@rweb@{@}} --- link to General Informaion.
+@code{@@notation@{@dots{}@}} --- refers to pieces of notation, e.g.
+@samp{@@notation@{clef@}}. Also use for specific lyrics
+(@samp{the @@notation@{A@tie{}-@tie{}men@} is centered}).
+Only use once per subsection per term.
@item
-@code{@@tie@{@}} --- Variables or numbers which consist of a
-single character (probably followed by a punctuation mark) should
-be tied properly, either to the previous or the next word.
-Example: @q{@code{The letter@@tie@{@}@@q@{I@} is skipped}}
+@code{@@q@{@dots{}@}} --- Single quotes. Used for
+@quoteleft{}vague@quoteright{} terms. To get a backslash
+(\), you must use @samp{@@bs@{@}}.
@item
-@code{@@uref@{@}} --- link to an external url.
+@code{@@qq@{@dots{}@}} --- Double quotes. Used for actual quotes
+(@qq{he said}) or for introducing special input modes. To get a
+backslash (\), you must use @samp{@@bs@{@}}.
@item
-@code{@@var} --- Use for variables.
+@code{@@var@{@dots{}@}} --- Use for variables.
@item
@code{@@version@{@}} --- Return the current LilyPond version
-string.
+string. Use @samp{@@w@{@@version@{@}@}} if it's at the end of a
+line (to prevent an ugly line break in PDF); use
+@samp{@@w@{"@@version@{@}"@}} if you need it in quotes.
@item
-@code{@@warning@{@}} --- produces a @qq{Note:@tie{}} box. Use for
-important messages.
+@code{@@w@{@dots{}@}} --- Do not allow any line breaks.
+@item
+@code{@@warning@{@dots{}@}} --- produces a @qq{Note:@tie{}} box.
+Use for important messages. To get a backslash (\), you must use
+@samp{@@bs@{@}}.
@end itemize
-
@node Other text concerns
@subsection Other text concerns
@itemize
-
@item
References must occur at the end of a sentence, for more
-information see @@ref@{the texinfo manual@}. Ideally this should
-also be the final sentence of a paragraph, but this is not
-required. Any link in a doc section must be duplicated in the
-@@seealso section at the bottom.
+information see the
+@uref{http://www.gnu.org/software/texinfo/manual/texinfo/,texinfo
+manual}. Ideally this should also be the final sentence of a
+paragraph, but this is not required. Any link in a doc section
+must be duplicated in the @code{@@seealso} section at the bottom.
@item
Introducing examples must be done with
Colon usage
@enumerate
-
@item
To introduce lists
@item
-When beginning a quote: "So, he said,...".
+When beginning a quote: @qq{So, he said,...}.
This usage is rarer. Americans often just use a comma.
@item
When adding a defining example at the end of a sentence.
-
@end enumerate
@item
Non-ASCII characters which are in utf-8 should be directly used;
-this is, don't say @q{Ba@@ss@{@}tuba} but @q{Baßtuba}. This ensures
-that all such characters appear in all output formats.
-
+this is, don't say @samp{Ba@@ss@{@}tuba} but @samp{Baßtuba}. This
+ensures that all such characters appear in all output formats.
@end itemize
-
-
@node Documentation policy
@section Documentation policy
translate the documentation. However, if you have enough time and
motivation and a suitable system, it can be very useful to build at
least the documentation so that you can check the output yourself and
-more quickly; if you are interested, see @ref{Compiling from source}.
+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
@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