@node Introduction to documentation work
@section Introduction to documentation work
-Our documentation tries to adhere to the @ref{Documentation
-policy} as strictly as possible. One policy in particular is
-often questioned by potential contributors: we do not repeat
-material in the Notation Reference, and instead provide links to
-the @qq{definitive} presentation of that information.
-
-Some people point out, with good reason, that this makes the
-documentation harder to read. If we repeated certain information
-in relevant places, readers would be less likely to miss that
-information.
+Our documentation tries to adhere to our @ref{Documentation
+policy}. This policy contains a few items which may seem odd.
+One policy in particular is often questioned by potential
+contributors: we do not repeat material in the Notation Reference,
+and instead provide links to the @qq{definitive} presentation of
+that information. Some people point out, with good reason, that
+this makes the documentation harder to read. If we repeated
+certain information in relevant places, readers would be less
+likely to miss that information.
That reasoning is sound, but we have two counter-arguments.
First, the Notation Reference -- one of @emph{five} manuals for
@subsection Sectioning commands
Most of the manual operates at the
+
+@example
@@node Foo
@@subsubsection Foo
+@end example
+
+@noindent
level. Sections are created with
+
+@example
@@node Foo
@@subsection Foo
-commands.
+@end example
+
+@itemize
+@item Please leave two blank lines above a @@node; this makes it
+easier to find sections in texinfo.
-* Please leave two blank lines above a @@node; this makes it easier
- to findw sections in texinfo.
+@item Sectioning commands (@@node and @@section) must not appear
+inside an @@ignore. Separate those commands with a space, ie @@n
+ode.
-* sectioning commands (@@node and @@section) must not appear inside
- an @@ignore. Separate those commands with a space, ie @@n ode.
+@end itemize
@subsection LilyPond formatting
-* Use two spaces for indentation in lilypond examples. (no tabs)
+@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"}
-* 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
- \set Staff.instrumentName = #"cello"
+@item All engravers should have double-quotes around them:
-* All engravers should have double-quotes around them:
+@example
\consists "Spans_arpeggio_engraver"
- Again, LilyPond does not strictly require this, but it is a
- useful standard to follow.
+@end example
-* Examples should end with a complete bar if possible.
+Again, LilyPond does not strictly require this, but it is a useful
+standard to follow.
-* If possible, only write one bar per line. The notes on each
- line should be an independent line -- tweaks should occur on
- their own line if possible.
- Bad:
- \override textscript #'padding = #3 c1^"hi"
- Good:
- \override textscript #'padding = #3
- c1^"hi"
+@item Examples should end with a complete bar if possible.
-* Most LilyPond input should be produced with:
- @@lilypond[verbatim,quote,relative=2]
- or
- @@lilypond[verbatim,quote,relative=1]
+@item If possible, only write one bar per line. The notes on each
+line should be an independent line -- tweaks should occur on their
+own line if possible. Bad:
- If you want to use \layout@{@} or define variables, use
- @@lilypond[verbatim,quote]
+@example
+\override textscript #'padding = #3 c1^"hi"
+@end example
- In rare cases, other options may be used (or omitted), but ask first.
+Good:
-* Inspirational headwords are produced with
- @@lilypondfile[quote,ragged-right,line-width=16\cm,staffsize=16]
- @{pitches-headword.ly@}
+@example
+\override textscript #'padding = #3
+c1^"hi"
+@end example
-* LSR snippets are linked with
- @@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
- @{filename.ly@}
- excepted in Templates, where `doctitle' may be omitted.
+@item Most LilyPond input should be produced with:
-* Avoid long stretches of input code. Noone is going to read them
- in print. Please create a smaller example. (the smaller
- example does not need to be minimal, however)
+@example
+@@lilypond[verbatim,quote,relative=2]
+@end example
-* Specify durations for at least the first note of every bar.
+@noindent
+or
-* If possible, end with a complete bar.
+@example
+@@lilypond[verbatim,quote,relative=1]
+@end example
-* Comments should go on their own line, and be placed before the
- line(s) to which they refer.
+If you want to use \layout@{@} or define variables, use
-* Add extra spaces around @{ @} marks; ie
- not: \chordmode @{c e g@}
- but instead: \chordmode @{ c e g @}
+@example
+@@lilypond[verbatim,quote]
+@end example
+
+In rare cases, other options may be used (or omitted), but ask first.
-* If you only have one bar per line, omit bar checks. If you
- put more than one bar per line (not recommended), then include
- bar checks.
+@item
+Inspirational headwords are produced with
-* If you want to work on an example outside of the manual (for
- easier/faster processing), use this header:
+@example
+@@lilypondfile[quote,ragged-right,line-width=16\cm,staffsize=16]
+@{pitches-headword.ly@}
+@end example
+@item LSR snippets are linked with
+
+@example
+@@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+@{filename.ly@}
+@end example
+
+@noindent
+excepted in Templates, where `doctitle' may be omitted.
+
+@item Avoid long stretches of input code. Noone is going to read
+them in print. Please create a smaller example. (the smaller
+example does not need to be minimal, however)
+
+@item Specify durations for at least the first note of every bar.
+
+@item If possible, end with a complete bar.
+
+@item 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
+
+@example
+not: \chordmode @{c e g@}
+but instead: \chordmode @{ c e g @}
+@end example
+
+@item If you only have one bar per line, omit bar checks. If you
+put more than one bar per line (not recommended), then include bar
+checks.
+
+@item If you want to work on an example outside of the manual (for
+easier/faster processing), use this header:
+
+@example
\paper @{
#(define dump-extents #t)
indent = 0\mm
\layout @{
@}
+@end example
- You may not change any of these values. If you are making an
- example demonstrating special \paper@{@} values, contact the
- Documentation Editor.
+You may not change any of these values. If you are making an
+example demonstrating special \paper@{@} values, contact the
+Documentation Editor.
+
+@end itemize
@subsection Text formatting
+@itemize
+
+@item
* Lines should be less than 72 characters long. (I personally
recommend writing with 66-char lines, but don't bother modifying
existing material.)
+@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.
+@item
* Use two spaces after a period.
+@item
* In examples of syntax, use @@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.
+@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:
The variable@@tie@{@}@@var@{a@} ...
+@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
where `@@example' starts the line (without leading spaces).
+@item
* Do not compress the input vertically; this is, do not use
Beginning of logical unit
new material should simply begin without anything special on the
line above it.
+@item
* in @@itemize use @@item on a separate line like this:
@@itemize
@@item
Do not use @@itemize @@bullet.
+@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,
@@w@{"@@version@{@}"@}
to prevent an ugly line break in PDF output.
+@end itemize
@subsection Syntax survey
+@itemize
+@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.
+@item
@@example ... @@end ignore - example text that should be set as a
blockquote. Any @{@} must be escaped with @@@{ @}@@
+@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
@@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"
+@item
@@var - Use for variables.
+@item
@@warning@{@} - produces a "Note: " box. Use for important messages.
+@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).
+@end itemize
+
@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.
+@item
* Introducing examples must be done with
. (ie finish the previous sentence/paragaph)
: (ie `in this example:')
The old "sentence runs directly into the example" method is not
allowed any more.
+@item
* Abbrevs in caps, e.g., HTML, DVI, MIDI, etc.
+@item
* Colon usage
1. To introduce lists
This usage is rarer. Americans often just use a comma.
3. When adding a defining example at the end of a sentence.
+@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.
+@end itemize
+
the Notation Reference, the Program Reference, and the Music
Glossary.
+@itemize
+
+@item
* Learning Manual:
The LM is written in a tutorial style which introduces the most
important concepts, structure and syntax of the elements of a
start-to-finish.
+@item
* Notation Reference: a (hopefully complete) description of
LilyPond input notation. Some material from here may be
duplicated in the Learning Manual (for teaching), but consider
means; explaining musical concepts happens in the Music Glossary.
+@item
* Application Usage: information about using the program lilypond
with other programs (lilypond-book, operating systems, GUIs,
convert-ly, etc). This section is written in formal technical
Users are not expected to read this manual from start to finish.
+@item
* Music Glossary: information about the music notation itself.
Explanations and translations about notation terms go here.
Users are not expected to read this manual from start to finish.
+@item
* Internals Reference: not really a documentation book, since it
is automagically generated from the source, but this is its
name.
+@end itemize
+
@subsection Section organization
-The order of headings inside documentation sections should be:
+@itemize
+
+@item The order of headings inside documentation sections should
+be:
+@example
main docs
@@predefined
@@endpredefined
@@snippets
@@seealso
@@knownissues
+@end example
+@item
* You _must_ include a @@seealso. The order of items inside the
@@seealso section is
Don't insert an empty line between @@seealso and the first entry!
Otherwise there is excessive vertical space in the PDF output.
+@item
* To create links, use @@ref@{@} if the link is within the same
manual.
+@item
* @@predefined ... @@endpredefined is for commands in ly/*-init.ly
FIXME?
+@item
* Do not include any real info in second-level sections (ie 1.1
Pitches). A first-level section may have introductory material,
but other than that all material goes into third-level sections
(ie 1.1.1 Writing Pitches).
+@end itemize
+
@subsection Checking cross-references
@subsection General writing
+@itemize
+
+@item
* Do not forget to create @@cindex entries for new sections of text.
Enter commands with @@funindex, i.e.
@@cindex pitches, writing in different octaves
and NOT
@@funindex #(set-accidental-style modern-voice-cautionary)
+@item
* Preferred terms:
- in general, use the American spellings. The internal
lilypond property names use this spelling.
note head NOT notehead
chord construct NOT chord (when referring to <>)
+@end itemize
+
@subsection Technical writing style
+@itemize
+
+@item
* Do not refer to LilyPond in the text. The reader knows what the
manual is about. If you do, capitalization is LilyPond.
+@item
* If you explicitly refer to `lilypond' the program (or any other
command to be executed), say `@@command@{lilypond@}'.
+@item
* Do not explicitly refer to the reader/user. There is no one
else besides the reader and the writer.
+@item
* Do not use abbreviations (don't, won't, etc.). If you do, use a
comma after it:
blabla blabla, i.e., blabla blabla
+@item
* Avoid fluff (``Notice that,'' ``as you can see,''
``Currently,'').
+@item
* The use of the word `illegal' is inappropriate in most cases.
Say `invalid' instead.
+@end itemize
+
@node Tips for writing docs
@section Tips for writing docs
projects / lilypond.git / commitdiff