* Texinfo introduction and usage policy::
* Documentation policy::
* Tips for writing docs::
-* Updating docs with convert-ly::
+* Scripts to ease doc work::
* Docstrings in scheme::
* Translating the documentation::
@end menu
@end example
@noindent
-construct. These are easily constructed with the emacs
-@code{M-x texinfo-all-menus-update} construct, or by this
-command-line script:
-
-@example
-#!/bin/sh
-emacs $1 -batch -f texinfo-all-menus-update -f save-buffer
-@end example
-
-@noindent
-(save the above as something like @command{texinfo-menus.sh}, make
-it executable, then run @command{texinfo-menus.sh foo.itely})
+construct. These are easily constructed with automatic tools; see
+@ref{Scripts to ease doc work}.
@node LilyPond formatting
@subsection Syntax survey
@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).
+
@item
@@c - single line comments
"@@c NOTE:" is a comment which should remain in the final
version. (gp only command ;)
-@item
-@@ignore ... @@end ignore - multi-line comment
@item
@@cindex - General index. Please add as many as you can. Don't
capitalize the first word.
+
@item
-@@funindex - is for a \lilycommand.
+@@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@{ @}@}.
@item
@@example ... @@end example - example text that should be set as a
blockquote. Any @{@} must be escaped with @@@{ @}@@
+@item
+@@funindex - is for a \lilycommand.
+
+@item
+@@ignore ... @@end ignore - multi-line comment
+
@item
@@itemize @@item
A @@item
B ... @@end itemize - for bulleted lists.
Do not compress vertically like this.
-@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@{ @}@}.
-
@item
@@notation@{@} - refers to pieces of notation, e.g.
"@@notation@{cres.@}". Also use to specific lyrics ("the
introducing special input modes.
@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"
+@@rchanges@{@} - link to Changes.
@item
-@@var - Use for variables.
+@@rcontrib@{@} - link to Contributor's Guide.
@item
-@@warning@{@} - produces a "Note: " box. Use for important messages.
+@@ref@{@} - link within current manual (type the exact node name inside the
+@{@}).
@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).
+@@ressay@{@} - link to Engraving Essay.
@item
-@@ref@{@} - link within current manual (type the exact node name inside the
-@{@}).
+@@rextend@{@} - link to Extending LilyPond.
@item
-@@ruser@{@} - link to Notation Reference.
+@@rglos@{@} - link to the Music Glossary.
+
+@item
+@@rinternals@{@} - link to the Internals Reference.
@item
@@rlearning@{@} - link to Learning Manual.
@item
-@@rglos@{@} - link to the Music Glossary.
+@@rlsr@{@} - link to a Snippet section.
@item
@@rprogram@{@} - link to Application Usage.
@item
-@@rlsr@{@} - link to a Snippet section.
+@@ruser@{@} - link to Notation Reference.
@item
-@@rinternals@{@} - link to the Internals Reference.
+@@rweb@{@} - link to General Informaion.
@item
-@@rextend@{@} - link to Extending LilyPond.
+@@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"
@item
@@uref@{@} - link to an external url.
+@item
+@@var - Use for variables.
+
+@item
+@@version@{@} - Return the current LilyPond version string
+
+@item
+@@warning@{@} - produces a "Note: " box. Use for important messages.
+
@end itemize
However, if you compile the documentation, a script called
check_texi_refs can help you with checking and fixing these
cross-references; for information on usage, cd into a source tree
-where documentation has been built, cd into Documentation and look
-for check-xrefs and fix-xrefs targets in 'make help' output. Note
-that you have to find yourself the source files to fix
+where documentation has been built, cd into Documentation and run:
+
+@example
+make check-xrefs
+make fix-xrefs
+@end example
+
+Note that you have to find yourself the source files to fix
cross-references in the generated documentation such as the
Internals Reference; e.g. you can grep scm/ and lily/.
+@c temporary? how long will kainhofer be used? -gp
+Also of interest may be the linkdoc checks on kainhofer.com. Be
+warned that these docs are not completely rebuilt every day, so it
+might not accurately reflect the current state of the docs.
+
+@example
+@uref{http://kainhofer.com/~lilypond/linkdoc/}
+@end example
+
@node General writing
@subsection General writing
@ref{Adding and editing snippets}.
-@node Updating docs with convert-ly
-@section Updating doc with @command{convert-ly}
+@node Scripts to ease doc work
+@section Scripts to ease doc work
+
+@subheading Stripping whitespace
+
+@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
+scripts/auxiliar/strip-whitespace.py Documentation/FILENAME
+@end example
+
+
+@subheading Sectioning commands
+
+@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:
+
+@example
+#!/bin/sh
+emacs $1 -batch -f texinfo-all-menus-update -f save-buffer
+@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}
cd into @file{Documentation/} and run
projects / lilypond.git / blobdiff