X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fcontributor%2Fdoc-work.itexi;h=39bd1e1df06087e61b5b0b2a2d1c3baf02b66a4a;hb=d9d6f6296ec64971c613964c49acf91fe16e2b1e;hp=0162670763dd2f895811de0bfab6675e17d96083;hpb=580faff1d6167b1500228dc5c5ae073dca0ead40;p=lilypond.git diff --git a/Documentation/contributor/doc-work.itexi b/Documentation/contributor/doc-work.itexi index 0162670763..39bd1e1df0 100644 --- a/Documentation/contributor/doc-work.itexi +++ b/Documentation/contributor/doc-work.itexi @@ -84,11 +84,17 @@ Please write exact changes to the text. @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 @@ -193,18 +199,18 @@ to do anything fancy, discuss it on @code{lilypond-devel} first.} 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 @@ -249,6 +255,13 @@ but instead: @@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: @@ -283,6 +296,90 @@ construct. These are easily constructed with automatic tools; see @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,quote,ragged-right,texidoc,doctitle] +@{filename.ly@} +@end example + @item Use two spaces for indentation in lilypond examples (no tabs). @@ -326,52 +423,6 @@ but instead: \override TextScript #'padding = #3 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. @@ -441,7 +492,7 @@ Beam, slur and tie marks should begin immediately after the first 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 @@ -452,8 +503,6 @@ easier/faster processing), use this header: \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)) @} @@ -988,7 +1037,7 @@ write: DYNAMICS may be manually placed above or below the staff, 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 @@ -1058,6 +1107,9 @@ Notation Reference: Application Usage: @@rprogram@{blah@}. +Essay on automated music engraving: +@@ressay@{yadda@}. + Extending LilyPond: @@rextend@{frob@}. @@ -1101,7 +1153,7 @@ manual. @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 @@ -1288,7 +1340,7 @@ concern. Check for potential additions. @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? @@ -1317,7 +1369,7 @@ harder than it looks. 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. @@ -1364,24 +1416,7 @@ In order to save build time, a script is available to build only one section of the documentation in English with a default html appearance. -The script is available as: - -@example -scripts/auxiliar/doc-section.sh -@end example - -This script will require customization for your site if your -LilyPond git repository is anyplace but @code{$HOME/lilypond}. - -Assuming that no customization is required, you can setup the -single section build with: - -@example -mkdir $HOME/lilypond/tempdocs -cp $HOME/lilypond/Documentation/out/version.itexi $HOME/lilypond/tempdocs -@end example - -You can then build a section of the documentation with: +You can build a section of the documentation with: @example scripts/auxiliar/doc-section.sh MANUAL SECTION @@ -1397,6 +1432,25 @@ Notation Reference, use the command: scripts/auxiliar/doc-section.sh notation pitches @end example +You can then see the generated document for the section at + +@example +tempdocs/pitches/out/pitches.html +@end example + +According to +@uref{http://code.google.com/p/lilypond/issues/detail?id=1236,Lilypond issue 1236}, +the location of the lilypond git tree is taken from @code{$LILYPOND_GIT} +if specified, otherwise it is auto-detected. + +It is assumed that compilation takes place in the @file{build/} +subdirectory, but this can be overridden by setting the environment +variable @code{LILYPOND_BUILD_DIR}. + +Similarly, output defaults to @file{build/tempdocs/} but this can be +overridden by setting the environment variable +@code{LILYPOND_TEMPDOCS}. + This script will not work for building sections of the Contributors' guide. For building sections of the Contributors' Guide, use: @@ -1414,8 +1468,8 @@ use: scripts/auxiliar/cg-section.sh doc-work @end example -Like @code{doc-section.sh}, @code{cg-section.sh} may need to be customized -for your installation. +@code{cg-section.sh} uses the same environment variables and +corresponding default values as @code{doc-section.sh}. @subheading Stripping whitespace and generating menus @@ -1453,7 +1507,7 @@ features. If you notice that it hasn't been done, complain to 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 @@ -1576,7 +1630,7 @@ make ISOLANG=@var{MY-LANGUAGE} new-lang 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 @@ -1694,19 +1748,19 @@ 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 +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 @@ -1732,15 +1786,15 @@ When you encounter @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 @@ -1752,7 +1806,7 @@ Spanish translation blah @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 @@ -1867,7 +1921,7 @@ to make your translation up to date. @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/} @@ -1875,7 +1929,7 @@ Translations status page. To update that page, do from 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. @@ -1917,8 +1971,8 @@ 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 @@ -1939,8 +1993,8 @@ make ISOLANG=@var{MY_LANGUAGE} snippet-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 @@ -1950,8 +2004,8 @@ don't do so, some @code{@@lilypond} snippets might be broken or make 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 @@ -1989,12 +2043,12 @@ git rev-list HEAD |head -1 @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 . 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 ; finally, commit these updated files. Not doing so would result in changes made both to your updates and original snippets to @@ -2045,9 +2099,9 @@ The following tasks are listed in decreasing priority order. @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 @@ -2116,7 +2170,9 @@ useful) and paste with @key{C-y} or @key{C-v}. @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 @@ -2211,7 +2267,7 @@ without updating translations}. 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, @@ -2227,21 +2283,21 @@ in the sources; WARNING only use this script once for each file, when support fo "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