@item
A formal patch to the source code is @emph{not} required; we can
-take care of the technical details. Here is an example of a
-perfect documentation report:
+take care of the technical details.
+
+@item
+Send the suggestions to the @code{bug-lilypond} mailing list as
+discussed in @rweb{Contact}.
+
+@item
+Here is an example of a perfect documentation report:
@verbatim
-To: lilypond-devel@gnu.org
+To: bug-lilypond@gnu.org
From: helpful-user@example.net
Subject: doc addition
All manuals live in @file{Documentation/}.
In particular, there are four user manuals, their respective master
-source files are @file{learning@/.tely} (LM, Learning Manual),
-@file{notation@/.tely} (NR, Notation Reference),
-@file{music@/-glossary@/.tely} (MG, Music Glossary), and
-@file{lilypond@/-program} (AU). Each chapter is written in a separate
+source files are @file{learning.tely} (LM, Learning Manual),
+@file{notation.tely} (NR, Notation Reference),
+@file{music-glossary.tely} (MG, Music Glossary), and
+@file{lilypond-program} (AU). Each chapter is written in a separate
file, ending in @file{.itely} for files containing lilypond code, and
@file{.itexi} for files without lilypond code, located in a subdirectory
-associated to the manual (@file{learning/} for @file{learning@/.tely}, and
+associated to the manual (@file{learning/} for @file{learning.tely}, and
so on); list the subdirectory of each manual to determine the filename
of the specific chapter you wish to modify.
Developer manuals live in @file{Documentation/} too. Currently there is
-only one: the Contributor's 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
@@subsection @@code@{Foo@} Bar
@end example
+@item
+With the exception of @code{@@} commands, the section name must
+match the node name exactly.
+
+@item
+No commas may be used in the node names.
+
@item
If a heading is desired without creating a @code{@@node}, please use
the following:
@itemize
+@item
+Most LilyPond examples throughout the documentation can be produced
+with:
+
+@example
+@@lilypond[verbatim,quote,relative=1]
+@end example
+
+or
+
+@example
+@@lilypond[verbatim,quote,relative=2]
+@end example
+
+If using any combination of @code{\header@{@}}, @code{\score@{@}} or
+@code{\layout@{@}} in your example, then you must omit the
+@code{relative} variable and either use absolute entry mode or an
+explicit @code{\relative@{@}} construction.
+
+If using @code{\book@{@}} in your example then you must also omit the
+@code{relative} variable and either use absolute entry mode or an
+explicit @code{\relative@{@}} construction. However, you must also
+include the @code{papersize=X} variable, where @code{X} is a defined
+paper size from within @file{scm/paper.scm}. This is to avoid the
+default @code{a4} paper size being used and leaving too much unnecessary
+whitespace and potentially awkward page breaks in the PDFs.
+
+The preferred @code{papersize}s are @code{a5}, @code{a6} or
+@code{a8landscape}.
+
+@code{a8landscape} works best for a single measure with a single title
+and/or single @code{tagline}:
+
+@example
+@@lilypond[papersize=a8landscape,verbatim]
+\book @{
+ \header @{
+ title = "A scale in LilyPond"
+ @}
+ \relative @{
+ c d e f
+ @}
+@}
+@@end lilypond
+@end example
+
+and can also be used to easily show features that require page breaks
+(i.e. page numbers) without taking large amounts of space within the
+documentation. Do not use the @code{quote} option with this paper size.
+
+@code{a5} or @code{a6} paper sizes are best used for examples that have
+more than two measures of music or require multiple staves (i.e. to
+illustrate cross-staff features, RH and LH parts etc.) and where
+@code{\book@{@}} constructions are required or where @code{a8landscape}
+produces an example that is too cramped. Depending on the example the
+@code{quote} option may need to be omitted.
+
+In rare cases, other options may be used (or omitted), but ask first.
+
+@item
+Please avoid using extra spacing either after or within the
+@code{@@lilypond} parameters.
+
+@example
+not: @@lilypond [verbatim, quote, relative=1]
+but instead: @@lilypond[verbatim,quote,relative=1]
+@end example
+
+@item
+Inspirational headwords are produced with:
+
+@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
+
@item
Use two spaces for indentation in lilypond examples (no tabs).
c1^"hi"
@end example
-@item
-Most LilyPond input should be produced with:
-
-@example
-@@lilypond[verbatim,quote,relative=2]
-@end example
-
-@noindent
-or
-
-@example
-@@lilypond[verbatim,quote,relative=1]
-@end example
-
-If you want to use @code{\layout@{@}} or define variables, use
-
-@example
-@@lilypond[verbatim,quote]
-@end example
-
-In rare cases, other options may be used (or omitted), but ask first.
-
-@item
-Inspirational headwords are produced with
-
-@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.
note with beam and phrase marks ending immediately after the last.
@example
-a8(\ ais16[ b cis( d] b) cis4~ b' cis,\)
+a8\( ais16[ b cis( d] b) cis4~ b' cis,\)
@end example
@item
\paper @{
indent = 0\mm
line-width = 160\mm - 2.0 * 0.4\in
- ragged-right = ##t
- force-assignment = #""
line-width = #(- line-width (* mm 3.000000))
@}
@itemize
@item
@code{@@enumerate} --- Create an ordered list (with numbers).
-Always put @samp{@@item} on its own line, and separate consecutive
-items with a blank line:
+Always put @samp{@@item} on its own line. As an exception, if all
+the items in the list are short enough to fit on single lines, placing
+them on the @samp{@@item} lines is also permissible. @samp{@@item}
+and @samp{@@end@tie{}enumerate} should always be preceded by a blank
+line.
@example
@@enumerate
+
@@item
-Foo
+A long multi-line item like this one must begin
+on a line of its own and all the other items in
+the list must do so too.
@@item
-Bar
+Even short ones
+
+@@end enumerate
+@end example
+
+@example
+@@enumerate
+
+@@item Short item
+
+@@item Short item
+
@@end enumerate
@end example
see @@ref@{Controlling direction and placement@}.
Most tweaks should be added to LSR and not placed directly in the
-.itely file. In some cases, tweaks may be placed in the main
+@file{.itely} file. In some cases, tweaks may be placed in the main
text, but ask about this first.
Finally, you should assume that users know what the notation
Application Usage:
@@rprogram@{blah@}.
+Essay on automated music engraving:
+@@ressay@{yadda@}.
+
Extending LilyPond:
@@rextend@{frob@}.
@item
@@predefined ... @@endpredefined is for commands in
-@file{ly/@/*-init@/.ly}
+@file{ly/*-init.ly}
@item
Do not include any real info in second-level sections (i.e. 1.1
@item
move LSR-worthy material into LSR. Add the snippet, delete the
-material from the .itely file, and add a @@lilypondfile command.
+material from the @file{.itely} file, and add a @@lilypondfile command.
@item
check the examples and descriptions. Do they still work?
In general, any \set or \override commands should go in the
@qq{select snippets} section, which means that they should go in
-LSR and not the .itely file. For some cases, the command
+LSR and not the @file{.itely} file. For some cases, the command
obviously belongs in the @qq{main text} (i.e. not inside
@@predefined or @@seealso or whatever) -- instrument names are a
good example of this.
@subheading Updating doc with @command{convert-ly}
-cd into @file{Documentation/} and run
-
-@example
-find . -name '*.itely' | xargs convert-ly -e
-@end example
-
-@noindent
-This also updates translated documentation.
-
+Don't. This should be done by programmers when they add new
+features. If you notice that it hasn't been done, complain to
+@code{lilypond-devel}.
@node 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
+requires modifying files in @file{scm/*.scm}. Texinfo is allowed
in these docstrings.
Most documentation writers never touch these, though. If you want
where @var{MY-LANGUAGE} is the ISO 639 language code.
Finally, add a language definition for your language in
-@file{python/@/langdefs@/.py}.
+@file{python/langdefs.py}.
@node Documentation translation details
Some pieces of text manipulated by build scripts that appear in the
output are translated in a @file{.po} file -- just like LilyPond output
-messages -- in @file{Documentation/@/po}. The Gettext domain is named
+messages -- in @file{Documentation/po}. The Gettext domain is named
@code{lilypond-doc}, and unlike @code{lilypond} domain it is not managed
through the Free Translation Project.
Take care of using typographic rules for your language, especially in
-@file{macros@/.itexi}.
+@file{macros.itexi}.
If you wonder whether a word, phrase or larger piece of text should be
translated, whether it is an argument of a Texinfo command or a small
piece sandwiched between two Texinfo commands, try to track whether and
where it appears in PDF and/or HTML output as visible text. This piece
-of advice is especially useful for translating @file{macros@/.itexi}.
+of advice is especially useful for translating @file{macros.itexi}.
Please keep verbatim copies of music snippets (in @code{@@lilypond}
blocs). However, some music snippets containing text that shows in
@end example
@noindent
-in the source, open @file{Documentation/@/snippets/@/@var{filename}@/.ly},
+in the source, open @file{Documentation/snippets/@var{filename}.ly},
translate the @code{texidoc} header field it contains, enclose it with
@code{texidoc@var{MY-LANGUAGE} = "} and @code{"}, and write it into
-@file{Documentation/@/@var{MY-LANGUAGE}/@/texidocs/@/@var{filename}@/.texidoc}.
+@file{Documentation/@var{MY-LANGUAGE}/texidocs/@/@var{filename}.texidoc}.
Additionally, you may translate the snippet's title in @code{doctitle}
header field, in case @code{doctitle} is a fragment option used in
@code{@@lilypondfile}; you can do this exactly the same way as
@code{texidoc}. For instance,
-@file{Documentation/@/@var{MY-LANGUAGE}/@/texidocs/@/@var{filename}@/.texidoc}
+@file{Documentation/@var{MY-LANGUAGE}/texidocs/@/@var{filename}.texidoc}
may contain
@example
@noindent
Then, you should get these translated strings into compiled snippets in
-@file{Documentation/@/snippets}, see @q{General guidelines} in @ref{Adding
+@file{Documentation/snippets}, see @q{General guidelines} in @ref{Adding
and editing snippets}.
@code{@@example} blocks need not be verbatim copies, e.g. variable
@seeCommittishesUpdate
Global state of the translation is recorded in
-@file{Documentation/@/translations@/.itexi}, 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/}
make translation-status
@end example
-This will also leave @file{out/@/translations@/-status@/.txt}, which contains
+This will also leave @file{out/translations-status.txt}, which contains
up-to-dateness percentages for each translated file, and update word
counts of documentation files in this Guide.
make ISOLANG=@var{MY_LANGUAGE} skeleton-update
@end example
-@file{.po} message catalogs in @file{Documentation/@/po/} may be updated
-by issuing from @file{Documentation/} or @file{Documentation/@/po/}
+@file{.po} message catalogs in @file{Documentation/po/} may be updated
+by issuing from @file{Documentation/} or @file{Documentation/po/}
@example
make po-update
@end example
This script overwrites music snippets in
-@file{@var{MY_LANGUAGE/@/foo/@/every@/.itely}} with music snippets from
-@file{@var{foo/@/every@/.itely}}. It ignores skeleton files, and keeps
+@file{@var{MY_LANGUAGE/foo/every.itely}} with music snippets from
+@file{@var{foo/every.itely}}. It ignores skeleton files, and keeps
intact music snippets preceded with a line starting with @code{@@c
KEEP LY}; it reports an error for each @file{.itely} that has not the
same music snippet count in both languages. Always use this script
no sense in their context.
When you have updated texidocs in
-@file{Documentation/@/@var{MY-LANGUAGE}/@/texidocs}, you can get these
-changes into compiled snippets in @file{Documentation/@/snippets}, see
+@file{Documentation/@var{MY-LANGUAGE}/texidocs}, you can get these
+changes into compiled snippets in @file{Documentation/snippets}, see
@q{General guidelines} in @ref{Adding and editing snippets}.
Finally, a command runs the three update processes above for all
@end example
A special case is updating Snippet documentation strings in
-@file{Documentation/@/@var{MY-LANGUAGE}/@/texidocs}. For these to be
+@file{Documentation/@var{MY-LANGUAGE}/texidocs}. For these to be
correctly marked as up-to-date, first run @code{makelsr.py} as
explained in @ref{Adding and editing snippets}, and commit the
-resulting compiled snippets left in @file{Documentation/@/snippets/}.
+resulting compiled snippets left in @file{Documentation/snippets/}.
Say the SHA1 ID code of this commit is <C>. Now edit again your
-translated files in @file{Documentation/@/@var{MY-LANGUAGE}/@/texidocs}
+translated files in @file{Documentation/@var{MY-LANGUAGE}/texidocs}
adjusting the 40-digit committish that appears in the text to be <C>;
finally, commit these updated files. Not doing so would result in
changes made both to your updates and original snippets to
@item Update macros.itexi.
For each obsolete macro definition, if it is possible to update macro
usage in documentation with an automatic text or regexp substitution,
-do it and delete the macro definition from macros.itexi; otherwise,
+do it and delete the macro definition from @file{macros.itexi}; otherwise,
mark this macro definition as obsolete with a comment, and keep it in
-macros.itexi until the documentation translation has been updated and
+@file{macros.itexi} until the documentation translation has been updated and
no longer uses this macro.
@item Update @file{*.tely} files completely with
@item Update sections finished in the English documentation; check
sections status at
+@smallexample
@uref{http://lilypondwiki.tuxfamily.org/index.php?title=Documentation_coordination}.
+@end smallexample
@item Update documentation PO. It is recommended not to update
strings which come from documentation that is currently deeply revised
A number of Python scripts handle a part of the documentation
translation process. All scripts used to maintain the translations
-are located in @file{scripts/@/auxiliar/}.
+are located in @file{scripts/auxiliar/}.
@itemize
@item @file{check_translation.py} -- show diff to update a translation,
"makeinfo --html" has been dropped.
@end itemize
-Other scripts are used in the build process, in @file{scripts/@/build/}:
+Other scripts are used in the build process, in @file{scripts/build/}:
@itemize
@item @file{mass-link.py} -- link or symlink files between English documentation
and documentation in other languages.
@end itemize
-Python modules used by scripts in @file{scripts/@/auxiliar/} or @file{scripts/@/build/} (but
-not by installed Python scripts) are located in @file{python/@/auxiliar/}:
+Python modules used by scripts in @file{scripts/auxiliar/} or @file{scripts/build/} (but
+not by installed Python scripts) are located in @file{python/auxiliar/}:
@itemize
@item @file{manuals_definitions.py} -- define manual names and name of
cross-reference Texinfo macros,
@item @file{buildlib.py} -- common functions (read piped output
of a shell command, use Git),
-@item @file{postprocess_html.py} (module imported by @file{www_post@/.py}) -- add footer and
+@item @file{postprocess_html.py} (module imported by @file{www_post.py}) -- add footer and
tweak links in HTML pages.
@end itemize
projects / lilypond.git / blobdiff