@node Documentation work
@chapter Documentation work
+There are currently 11 manuals for LilyPond, not including the
+translations. Each book is available in HTML, PDF, and info. The
+documentation is written in a language called @code{texinfo} --
+this allows us to generate different output formats from a single
+set of source files.
+
+To organize multiple authors working on the documentation, we use a
+Version Control System (VCS) called git, previously discussed in
+@ref{Starting with git}.
+
@menu
* Introduction to documentation work::
* Documentation suggestions::
* Documentation policy::
* Tips for writing docs::
* Updating docs with convert-ly::
+* Docstrings in scheme::
* Translating the documentation::
@end menu
of the specific chapter you wish to modify.
Developer manuals live in @file{Documentation/} too. Currently there is
-only one: the Contributors' Guide @file{contrib-guide.texi} you are
+only one: the Contributor's Guide @file{contrib-guide.texi} you are
reading.
Snippet files are part of documentation, and the Snippet List (SL) lives
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, tere will be an ugly line break in PDF output unless you
+space, there will be an ugly line break in PDF output unless you
enclose it with
@example
@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 ignore - example text that should be set as a
+@@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
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
@@notation@{A - men@} is centered"). Only use once per subsection
per term.
+
@item
@@q@{@} - Single quotes. Used for `vague' terms.
+
@item
@@qq@{@} - Double quotes. Used for actual quotes ("he said") or for
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.
-@item
-@@warning@{@} - produces a "Note: " box. Use for important messages.
+@@rcontrib@{@} - link to Contributor's Guide.
@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).
+@@ref@{@} - link within current manual (type the exact node name inside the
+@{@}).
@item
-@@ref@{@} - normal references (type the exact node name inside the
-@{@}).
+@@ressay@{@} - link to Engraving Essay.
+
@item
-@@ruser@{@} - link to the NR.
+@@rextend@{@} - link to Extending LilyPond.
+
@item
-@@rlearning@{@} - link to the LM.
+@@rglos@{@} - link to the Music Glossary.
+
@item
-@@rglos@{@} - link to the MG.
+@@rinternals@{@} - link to the Internals Reference.
+
@item
-@@rprogram@{@} - link to the AU.
+@@rlearning@{@} - link to Learning Manual.
+
@item
@@rlsr@{@} - link to a Snippet section.
+
+@item
+@@rprogram@{@} - link to Application Usage.
+
@item
-@@rinternals@{@} - link to the IR.
+@@ruser@{@} - link to Notation Reference.
+
+@item
+@@rweb@{@} - link to General Informaion.
+
+@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"
+
@item
@@uref@{@} - link to an external url.
+@item
+@@var - Use for variables.
+
+@item
+@@warning@{@} - produces a "Note: " box. Use for important messages.
+
@end itemize
Application Usage:
@@rprogram@{blah@}.
+Extending LilyPond:
+@@rextend@{frob@}.
+
Installed Files:
@@file@{path/to/dir/blahz@}.
+@node Docstrings in scheme
+@section Docstrings in scheme
+
+Material in the Internals reference is generated automatically
+from our source code. Any doc work on Internals therefore
+requires modifying files in @file{scm/*.scm}. Texinfo is allowed
+in these docstrings.
+
+Most documentation writers never touch these, though. If you want
+to work on them, please ask for help.
+
+
@node Translating the documentation
@section Translating the documentation
projects / lilypond.git / blobdiff