@ref{Starting with Git}.
@menu
-* Introduction to documentation work::
-* Documentation suggestions::
-* Texinfo introduction and usage policy::
-* Documentation policy::
-* Tips for writing docs::
-* Scripts to ease doc work::
-* Docstrings in scheme::
-* Translating the documentation::
+* Introduction to documentation work::
+* Documentation suggestions::
+* Texinfo introduction and usage policy::
+* Documentation policy::
+* Tips for writing docs::
+* Scripts to ease doc work::
+* Docstrings in scheme::
+* Translating the documentation::
@end menu
@section Texinfo introduction and usage policy
@menu
-* Texinfo introduction::
-* Documentation files::
-* Sectioning commands::
-* LilyPond formatting::
-* Text formatting::
-* Syntax survey::
-* Other text concerns::
+* Texinfo introduction::
+* Documentation files::
+* Sectioning commands::
+* LilyPond formatting::
+* Text formatting::
+* Syntax survey::
+* Other text concerns::
@end menu
Please leave two blank lines above a @@node; this makes it
easier to find sections in texinfo.
+@item
+If a heading is desired without creating a node, please use
+the following:
+
+@example
+@@subheading Foo
+@end example
+
@item
Sectioning commands (@@node and @@section) must not appear
-inside an @@ignore. Separate those commands with a space, ie @@n
-ode.
+inside an @@ignore. Separate those commands with a space, ie
+@@n@tie{}ode.
@end itemize
@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]
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).
+existing material). Also see the recommendations for fixed-width
+fonts in the @ref{Syntax survey}.
@item
Do not use tabs.
@item
Do not use spaces at the beginning of a line (except in
-@@example or @@verbatim environments), and do not use more than a
-single space between words. `makeinfo' copies the input lines
-verbatim without removing those spaces.
+@code{@@example} or @code{@@verbatim} environments), and do not
+use more than a single space between words. @q{makeinfo} copies
+the input lines verbatim without removing those spaces.
@item
Use two spaces after a period.
@item
-In examples of syntax, use @@var@{musicexpr@} for a music
-expression.
+In examples of syntax, use @code{@@var@{@var{musicexpr}@}} for a
+music expression.
@item
-Don't use @@rinternals@{@} in the main text. If you're
-tempted to do so, you're probably getting too close to "talking
-through the code". If you really want to refer to a context, use
-@@code@{@} in the main text and @@rinternals@{@} in the @@seealso.
+Don't use @code{@@rinternals@{@}} in the main text. If you're
+tempted to do so, you're probably getting too close to @qq{talking
+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 @@verbatim environment. Use the @@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 `@@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; this 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@}}}).
-@@noindent
-continuation of logical unit
-@end example
+@itemize
+@item
+@code{@@ref@{@dots{}@}} --- link within current manual.
-This makes it easier to avoid forgetting the `@@noindent'. Only
-use @@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 @@itemize use @@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 @@itemize @@bullet.
+@item
+@code{@@rglos@{@dots{}@}} --- link to the Music Glossary.
@item
-To get LilyPond version, use @@version@{@} (this does not work
-inside LilyPond snippets). If you write "@@version@{@}" (enclosed
-with quotes), or generally if @@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
-@@bs - Generates a backslash inside @@warning.
- Any `\' used inside @@warning (and @@q or @@qq) must be written as `@@bs@{@}'
- (texinfo would also allow \\, but this breaks with PDF output).
+@code{@@email@{@dots{}@}} --- create a @code{mailto:} E-mail link.
@item
-@@c - single line comments
- "@@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.
+@end itemize
-@item
-@@cindex - General index. Please add as many as you can. Don't
- capitalize the first word.
-@item
-@@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 @@w@{@@code@{ @}@}.
+@node Fixed-width font
+@unnumberedsubsubsec Fixed-width font
+@itemize
@item
-@@example ... @@end example - example text that should be set as a
- blockquote. Any @{@} must be escaped with @@@{ @}@@
+@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.
+
+@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
-@@funindex - is for a \lilycommand.
+@example
+@var{@dots{}text leading into the example@dots{}}
-@item
-@@ignore ... @@end ignore - multi-line comment
+@@example
+@dots{}
+@@end example
-@item
-@@itemize @@item
-A @@item
-B ... @@end itemize - for bulleted lists.
- Do not compress vertically like this.
+@@noindent
+@var{continuation of the text@dots{}}
+@end example
-@item
-@@notation@{@} - refers to pieces of notation, e.g.
- "@@notation@{cres.@}". Also use to specific lyrics ("the
- @@notation@{A - men@} is centered"). Only use once per subsection
- per term.
+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.
-@item
-@@q@{@} - Single quotes. Used for `vague' terms.
+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
-@@qq@{@} - Double quotes. Used for actual quotes ("he said") or for
- introducing special input modes.
+@code{@@file@{@dots{}@}} --- Use for filenames and directories.
@item
-@@rchanges@{@} - link to Changes.
+@code{@@option@{@dots{}@}} --- Use for options to command-line
+commands (eg. @samp{@@option@{--format@}}).
@item
-@@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
-@@ref@{@} - link within current manual (type the exact node name inside the
-@{@}).
+@node Indexing
+@unnumberedsubsubsec Indexing
+
+@itemize
@item
-@@ressay@{@} - link to Engraving Essay.
+@code{@@cindex @dots{}} --- General index. Please add as many as you can.
+Don't capitalize the first word.
@item
-@@rextend@{@} - link to Extending LilyPond.
+@code{@@funindex @dots{}} --- is for a \lilycommand.
+@end itemize
+
+@node Lists
+@unnumberedsubsubsec Lists
+
+@itemize
@item
-@@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
-@@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
-@@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
-@@rlsr@{@} - link to a Snippet section.
+@code{@@@@}, @code{@@@{}, @code{@@@}} --- Create an at-sign (@@),
+a left curly bracket (@{), or a right curly bracket (@}).
@item
-@@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
-@@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
-@@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
-@@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:
- "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
-@@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
-@@var - Use for variables.
+@code{@@var@{@dots{}@}} --- Use for variables.
@item
-@@version@{@} - Return the current LilyPond version string
+@code{@@version@{@}} --- Return the current LilyPond version
+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
-@@warning@{@} - produces a "Note: " 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 `Ba@@ss@{@}tuba' but `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
@menu
-* Books::
-* Section organization::
-* Checking cross-references::
-* General writing::
-* Technical writing style::
+* Books::
+* Section organization::
+* Checking cross-references::
+* General writing::
+* Technical writing style::
@end menu
@node Books
manual.
@item
-@@predefined ... @@endpredefined is for commands in ly/*-init.ly
-FIXME?
+@@predefined ... @@endpredefined is for commands in
+@file{ly/*-init.ly}
@item
Do not include any real info in second-level sections (ie 1.1
email to these lists.
@menu
-* Getting started with documentation translation::
-* Documentation translation details::
-* Documentation translation maintenance::
-* Translations management policies::
-* Technical background::
+* Getting started with documentation translation::
+* Documentation translation details::
+* Documentation translation maintenance::
+* Translations management policies::
+* Technical background::
@end menu
@node Getting started with documentation translation
Git repository, see @ref{Starting with Git}.
@menu
-* Translation requirements::
-* Which documentation can be translated::
-* Starting translation in a new language::
+* Translation requirements::
+* Which documentation can be translated::
+* Starting translation in a new language::
@end menu
@node Translation requirements
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}.
@node Which documentation can be translated
All files should be encoded in UTF-8.
@menu
-* Files to be translated::
-* Translating the Web site and other Texinfo documentation::
-* Adding a Texinfo manual::
+* Files to be translated::
+* Translating the Web site and other Texinfo documentation::
+* Adding a Texinfo manual::
@end menu
@node Files to be translated
@include contributor/doc-translation-list.itexi
+In addition, not listed above, Snippets' titles and descriptions
+should be translated; they are a part of the Notation Reference and
+therefore their priority is 5.
+
@node Translating the Web site and other Texinfo documentation
@unnumberedsubsubsec Translating the Web site and other Texinfo documentation
@@@var{section_commmand} @@translationof} trio mentioned above) in the
expected source file and define all its parent nodes; for each node you
have defined this way but have not translated, insert a line that
-contains @code{@@untranslated} and append @code{ @@c external} to the
-line that contains @code{@@translationof}. That is, you should end up
+contains @code{@@untranslated}. That is, you should end up
for each untranslated node with something like
@example
@@node @var{translation of Foo bar}
@@@var{section_command} @var{translation of Bar baz}
-@@translationof Foo bar @@c external
+@@translationof Foo bar
@@untranslated
@end example
@file{Documentation/snippets}, see @q{General guidelines} in @ref{Adding
and editing snippets}.
-@code{@@example} blocs need not be verbatim copies, e.g. variable
+@code{@@example} blocks need not be verbatim copies, e.g. variable
names, file names and comments should be translated.
Finally, please carefully apply every rule exposed in @ref{Texinfo
@ref{Maintaining without updating translations}.
@menu
-* Check state of translation::
-* Updating documentation translation::
-* Updating translation committishes::
+* Check state of translation::
+* Updating documentation translation::
+* Updating translation committishes::
@end menu
@macro seeCommittishesUpdate{}
@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
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 <C>. 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 <C>;
+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.
+
+
+@seealso
+@ref{LSR work}.
@node Translations management policies
@subsection Translations management policies
coordinators work efficiently.
@menu
-* Maintaining without updating translations::
-* Managing documentation translation with Git::
+* Maintaining without updating translations::
+* Managing documentation translation with Git::
@end menu
@node Maintaining without updating translations
projects / lilypond.git / blobdiff