@item
@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.
+Use the @code{@@code@{@dots{}@}} command when referring to
+individual language-specific tokens (keywords, commands,
+engravers, scheme symbols, etc.) in the text. 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}. Do not use
+@code{@@code@{@dots{}@}} or @code{@@samp@{@dots{}@}} inside an
+@code{@@example} block, and do not use either 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}
@q{@code{@@q@{@@w@{@@code@{@@bs@{@}relative c''@}@}@}}}.
@item
-@code{@@command@{@dots{}@}} --- Use for command-line commands (eg.
-@samp{@@command@{lilypond-book@}}).
+@code{@@command@{@dots{}@}} --- Use when referring to command-line
+commands within the text (eg. @samp{@@command@{convert-ly@}}). Do
+not use inside an @code{@@example} block.
@item
@code{@@example} --- Use for examples of program code. Do not add
@code{@@smallexample} line by about 5 columns.
@item
-@code{@@file@{@dots{}@}} --- Use for filenames and directories.
+@code{@@file@{@dots{}@}} --- Use when referring to filenames and
+directories in the text. Do not use inside an @code{@@example}
+block.
@item
-@code{@@option@{@dots{}@}} --- Use for options to command-line
-commands (eg. @samp{@@option@{--format@}}).
+@code{@@option@{@dots{}@}} --- Use when referring to command-line
+options in the text (eg. @samp{@@option@{--format@}}). Do not use
+inside an @code{@@example} block.
@item
@code{@@verbatim} --- Prints the block exactly as it appears in
backslash (\), you must use @samp{@@bs@{@}}.
@item
-@code{@@var@{@dots{}@}} --- Use for variables.
+@code{@@var@{@dots{}@}} --- Use for metasyntactic variables (such
+as @code{@var{foo}}, @code{@var{bar}}, @code{@var{arg1}}, etc.).
+In most cases, when the @code{@@var@{@dots{}@}} command appears in
+the text (and not in an @code{@@example} block) it should be
+wrapped with an appropriate texinfo code-highlighting command
+(such as @code{@@code}, @code{@@samp}, @code{@@file},
+@code{@@command}, etc.). For example:
+@samp{@@code@{@@var@{foo@}@}},
+@samp{@@file@{@@var@{myfile.ly@}@}},
+@w{@samp{@@samp@{git checkout @@var@{branch@}@}}}, etc. This
+improves readability in the PDF and HTML output.
@item
@code{@@version@{@}} --- Return the current LilyPond version
but other than that all material goes into third-level sections
(i.e. 1.1.1 Writing Pitches).
+@item
+The @@knownissues should not discuss any issues that are in the
+tracker, unless the issue is Priority-Postponed. The goal is to
+discuss any overall architecture or syntax decisions which may be
+interpreted as bugs. Normal bugs should not be discussed here,
+because we have so many bugs that it would be a huge task to keep
+the @@knownissues current and accurate all the time.
+
@end itemize
@end example
@noindent
-do not bother with the @@code@{@} (they are added automatically).
+Do not bother with the @@code@{@} (they are added automatically).
These items are added to both the command index and the unified
-index.
+index. Both index commands should go in front of the actual material.
-Both index commands should go in front of the actual material.
-
-@@cindex entries should not be capitalized, ie
+@item
+@@cindex entries should not be capitalized, i.e.
@example
@@cindex time signature
@end example
@noindent
-is preferred instead of @qq{Time signature}, Only use capital
-letters for musical terms which demand them, like D.S. al Fine.
+is preferred instead of @qq{Time signature}. Only use capital
+letters for musical terms which demand them, e.g.
+@qq{D.S. al Fine}.
-For scheme functions, only include the final part, i.e.,
+@item
+For scheme function index entries, only include the final part, i.e.
@example
@@funindex modern-voice-cautionary
@end example
@item
-Preferred terms:
+Use American spelling. LilyPond's internal property
+names use this convention.
+
+@item
+Here is a list of preferred terms to be used:
@itemize
+@item
+@emph{Simultaneous} NOT concurrent.
@item
-In general, use the American spellings. The internal lilypond
-property names use this spelling.
+@emph{Measure}: the unit of music.
@item
-List of specific terms:
+@emph{Bar line}: the symbol delimiting a measure NOT barline.
-@example
-canceled
-simultaneous NOT concurrent
-measure: the unit of music
-bar line: the symbol delimiting a measure NOT barline
-note head NOT notehead
-chord construct NOT chord (when referring to <>)
-@end example
+@item
+@emph{Note head} NOT notehead.
+
+@item
+@emph{Chord construct} NOT just chord (when referring to < ... >)
+
+@item
+@emph{Staff} NOT stave.
+
+@item
+@emph{Staves} NOT Staffs:
+Phrases such as
+@q{multiple @@internalsref@{Staff@}s}
+should be rephrased to
+@q{multiple @@internalsref@{Staff@} contexts}.
@end itemize
+
@end itemize
Like @code{doc-section.sh}, @code{cg-section.sh} may need to be customized
for your installation.
-@subheading Stripping whitespace
+@subheading Stripping whitespace and generating menus
-@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
+@warning{This script assumes that the file conforms to our doc
+policy; a few files still need work in this regard.}
+
+To automatically regenerate @code{@@menu} portions and strip
+whitespace, use:
@example
-scripts/auxiliar/strip-whitespace.py Documentation/FILENAME
+scripts/auxiliar/node-menuify.py @var{FILENAME}
@end example
-@subheading Sectioning commands
+@subheading Stripping whitespace only
-@warning{These commands add whitespace.}
-
-The emacs @code{M-x texinfo-all-menus-update} command will
-regenerate @@menu blocks. This can also be run with this
-command-line script:
+@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
-#!/bin/sh
-emacs $1 -batch -f texinfo-all-menus-update -f save-buffer
+scripts/auxiliar/strip-whitespace.py Documentation/FILENAME
@end example
-@noindent
-(save the above as something like @command{texinfo-menus.sh}, make
-it executable, then run @command{texinfo-menus.sh foo.itely})
-
@subheading Updating doc with @command{convert-ly}
projects / lilypond.git / blobdiff