X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fcontributor%2Fdoc-work.itexi;h=c002698f1c1d19b56360aadef1f611dd8d9ac885;hb=3f6f94a2a94833abcd8dc280e1e97da3c42d68d3;hp=70bb1d72b756648ba16dac75da97f2dba8d2379a;hpb=77cc43a987b539afc330fd4be9dd846985338379;p=lilypond.git

diff --git a/Documentation/contributor/doc-work.itexi b/Documentation/contributor/doc-work.itexi
index 70bb1d72b7..c002698f1c 100644
--- a/Documentation/contributor/doc-work.itexi
+++ b/Documentation/contributor/doc-work.itexi
@@ -62,6 +62,9 @@ the main portion of NR 1+2) may also seem counter-intuitive, but
 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
@@ -229,11 +232,25 @@ level.  Sections are created with
 
 @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
@@ -241,9 +258,9 @@ the following:
 @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
 
@@ -267,14 +284,7 @@ construct.  These are easily constructed with automatic tools; see
 @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:
@@ -283,8 +293,22 @@ 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.
@@ -296,17 +320,10 @@ checks.
 
 @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
@@ -323,7 +340,7 @@ or
 @@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]
@@ -366,13 +383,59 @@ Comments should go on their own line, and be placed before
 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:
@@ -391,7 +454,7 @@ 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
@@ -401,31 +464,11 @@ Documentation Editor.
 @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.
@@ -449,232 +492,355 @@ 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 @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@}}}).
 
-@@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}.
 
-@item
-@code{@@ref@{@}} --- link within current manual (type the exact
-node name inside the @code{@{@}}).
+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
+
+
+@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
@@ -695,30 +861,25 @@ Abbrevs in caps, e.g., HTML, DVI, MIDI, etc.
 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
 
@@ -1240,7 +1401,10 @@ It is not required to build LilyPond and the documentation to
 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
@@ -1589,12 +1753,8 @@ to make your translation up to date.
 
 @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/}
 
@@ -1609,7 +1769,6 @@ counts of documentation files in this Guide.
 @seealso
 @ref{Maintaining without updating translations}.
 
-
 @node Updating documentation translation
 @unnumberedsubsubsec Updating documentation translation
 
@@ -1741,7 +1900,6 @@ put this very committish on the files in the same commit.
 @seealso
 @ref{LSR work}.
 
-
 @node Translations management policies
 @subsection Translations management policies