@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
-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
+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
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
-
-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
-
-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))
@}
see @@ref@{Controlling direction and placement@}.
Most tweaks should be added to LSR and not placed directly in the
-@file{@/.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 @file{@/.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 @file{@/.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.
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
script @command{texi-langutils.py} and the makefile target are updated.
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
+output are translated in a @file{.po} file -- just like LilyPond output
+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.
@seeCommittishesUpdate
-Texinfo skeleton files, i.e. @file{@/.itely} files not yet translated,
+Texinfo skeleton files, i.e. @file{.itely} files not yet translated,
containing only the first node of the original file in English can be
updated automatically: whenever @command{make check-translation} shows
that such files should be updated, run from @file{Documentation/}
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
+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
with a lot of care, i.e. run it on a clean Git working tree, and check
the changes it made with @command{git diff} before committing; if you
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 @file{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
-@file{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 @file{*.tely} files completely with
@command{make check-translation} -- you may want to redirect output
to a file because of overwhelming output, or call check-translation.py
on individual files, see @ref{Check state of translation}.
-@item In @file{@/.itelys}, match sections and .itely file names with those from
+@item In @file{.itelys}, match sections and .itely file names with those from
English docs, which possibly involves moving nodes contents in block
between files, without updating contents itself. In other words, the
game is catching where has gone each section. In Learning manual, and
@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,
-@item @file{texi@/-langutils@/.py} -- quickly and dirtily parse Texinfo files to
+@item @file{check_translation.py} -- show diff to update a translation,
+@item @file{texi-langutils.py} -- quickly and dirtily parse Texinfo files to
make message catalogs and Texinfo skeleton files,
-@item @file{texi@/-skeleton@/-update@/.py} -- update Texinfo skeleton files,
-@item @file{update@/-snippets@/.py} -- synchronize ly snippets with those
+@item @file{texi-skeleton-update.py} -- update Texinfo skeleton files,
+@item @file{update-snippets.py} -- synchronize ly snippets with those
from English docs,
-@item @file{translations@/-status@/.py} -- update translations status pages and word
+@item @file{translations-status.py} -- update translations status pages and word
counts in the file you are reading,
-@item @file{tely@/-gettext@/.py} -- gettext node names, section titles and references
+@item @file{tely-gettext.py} -- gettext node names, section titles and references
in the sources; WARNING only use this script once for each file, when support for
"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
+@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
+@item @file{manuals_definitions.py} -- define manual names and name of
cross-reference Texinfo macros,
-@item @file{buildlib@/.py} -- common functions (read piped output
+@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
And finally
@itemize
-@item @file{python/@/langdefs@/.py} -- language definitions module
+@item @file{python/langdefs.py} -- language definitions module
@end itemize
projects / lilypond.git / blobdiff