X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fcontributor%2Fdoc-work.itexi;h=f74d1417b22712c969727ac0ee7fb23df7ccd596;hb=208ca566e216f6d734501d3dad2a880643578f81;hp=abd8c1654ffcbe378a062dc7d037cbbde3bb5dd2;hpb=a82dc4a0cca57f285e818f6c227c8428a3c02a71;p=lilypond.git diff --git a/Documentation/contributor/doc-work.itexi b/Documentation/contributor/doc-work.itexi index abd8c1654f..f74d1417b2 100644 --- a/Documentation/contributor/doc-work.itexi +++ b/Documentation/contributor/doc-work.itexi @@ -193,18 +193,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 @@ -340,6 +340,14 @@ or @@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 @@ -604,17 +612,20 @@ external url. Use within an @code{@@example ... @@end example}. @item @code{@@code@{@dots{}@}}, @code{@@samp@{@dots{}@}} --- -Use the @code{@@code@{@dots{}@}} command for individual -language-specific tokens (keywords, commands, engravers, scheme -symbols, etc.). Ideally, a single @code{@@code@{@dots{}@}} block -should fit within one line in the PDF output. Use the -@code{@@samp@{@dots{}@}} command when you have a short example of -user input, unless it constitutes an entire @code{@@item} by -itself, in which case @code{@@code@{@dots{}@}} is preferable. -Otherwise, both should only be used when part of a larger sentence -within a paragraph or @code{@@item}. Never use a -@code{@@code@{@dots{}@}} or @code{@@samp@{@dots{}@}} block as a -free-standing paragraph; use @code{@@example} instead. +Use the @code{@@code@{@dots{}@}} command when referring to +individual language-specific tokens (keywords, commands, +engravers, scheme symbols, etc.) in the text. Ideally, a single +@code{@@code@{@dots{}@}} block should fit within one line in the +PDF output. + +Use the @code{@@samp@{@dots{}@}} command when you have a short +example of user input, unless it constitutes an entire +@code{@@item} by itself, in which case @code{@@code@{@dots{}@}} is +preferable. Otherwise, both should only be used when part of a +larger sentence within a paragraph or @code{@@item}. Do not use +@code{@@code@{@dots{}@}} or @code{@@samp@{@dots{}@}} inside an +@code{@@example} block, and do not use either as a free-standing +paragraph; use @code{@@example} instead. A single unindented line in the PDF has space for about 79 fixed-width characters (76 if indented). Within an @code{@@item} @@ -660,8 +671,9 @@ so the example above would be coded as @q{@code{@@q@{@@w@{@@code@{@@bs@{@}relative c''@}@}@}}}. @item -@code{@@command@{@dots{}@}} --- Use for command-line commands (eg. -@samp{@@command@{lilypond-book@}}). +@code{@@command@{@dots{}@}} --- Use when referring to command-line +commands within the text (eg. @samp{@@command@{convert-ly@}}). Do +not use inside an @code{@@example} block. @item @code{@@example} --- Use for examples of program code. Do not add @@ -700,11 +712,14 @@ running into the PDF margin. Each additional level of @code{@@smallexample} line by about 5 columns. @item -@code{@@file@{@dots{}@}} --- Use for filenames and directories. +@code{@@file@{@dots{}@}} --- Use when referring to filenames and +directories in the text. Do not use inside an @code{@@example} +block. @item -@code{@@option@{@dots{}@}} --- Use for options to command-line -commands (eg. @samp{@@option@{--format@}}). +@code{@@option@{@dots{}@}} --- Use when referring to command-line +options in the text (eg. @samp{@@option@{--format@}}). Do not use +inside an @code{@@example} block. @item @code{@@verbatim} --- Prints the block exactly as it appears in @@ -741,16 +756,33 @@ Don't capitalize the first word. @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 @@ -814,7 +846,17 @@ Only use once per subsection per term. backslash (\), you must use @samp{@@bs@{@}}. @item -@code{@@var@{@dots{}@}} --- Use for variables. +@code{@@var@{@dots{}@}} --- Use for metasyntactic variables (such +as @code{@var{foo}}, @code{@var{bar}}, @code{@var{arg1}}, etc.). +In most cases, when the @code{@@var@{@dots{}@}} command appears in +the text (and not in an @code{@@example} block) it should be +wrapped with an appropriate texinfo code-highlighting command +(such as @code{@@code}, @code{@@samp}, @code{@@file}, +@code{@@command}, etc.). For example: +@samp{@@code@{@@var@{foo@}@}}, +@samp{@@file@{@@var@{myfile.ly@}@}}, +@w{@samp{@@samp@{git checkout @@var@{branch@}@}}}, etc. This +improves readability in the PDF and HTML output. @item @code{@@version@{@}} --- Return the current LilyPond version @@ -946,7 +988,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 @@ -1059,7 +1101,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 @@ -1067,6 +1109,14 @@ Pitches). A first-level section may have introductory material, but other than that all material goes into third-level sections (i.e. 1.1.1 Writing Pitches). +@item +The @@knownissues should not discuss any issues that are in the +tracker, unless the issue is Priority-Postponed. The goal is to +discuss any overall architecture or syntax decisions which may be +interpreted as bugs. Normal bugs should not be discussed here, +because we have so many bugs that it would be a huge task to keep +the @@knownissues current and accurate all the time. + @end itemize @@ -1114,23 +1164,24 @@ Enter commands with @@funindex, i.e. @end example @noindent -do not bother with the @@code@{@} (they are added automatically). +Do not bother with the @@code@{@} (they are added automatically). These items are added to both the command index and the unified -index. - -Both index commands should go in front of the actual material. +index. Both index commands should go in front of the actual material. -@@cindex entries should not be capitalized, ie +@item +@@cindex entries should not be capitalized, i.e. @example @@cindex time signature @end example @noindent -is preferred instead of @qq{Time signature}, Only use capital -letters for musical terms which demand them, like D.S. al Fine. +is preferred instead of @qq{Time signature}. Only use capital +letters for musical terms which demand them, e.g. +@qq{D.S. al Fine}. -For scheme functions, only include the final part, i.e., +@item +For scheme function index entries, only include the final part, i.e. @example @@funindex modern-voice-cautionary @@ -1139,28 +1190,41 @@ For scheme functions, only include the final part, i.e., @end example @item -Preferred terms: +Use American spelling. LilyPond's internal property +names use this convention. + +@item +Here is a list of preferred terms to be used: @itemize +@item +@emph{Simultaneous} NOT concurrent. @item -In general, use the American spellings. The internal lilypond -property names use this spelling. +@emph{Measure}: the unit of music. @item -List of specific terms: +@emph{Bar line}: the symbol delimiting a measure NOT barline. -@example -canceled -simultaneous NOT concurrent -measure: the unit of music -bar line: the symbol delimiting a measure NOT barline -note head NOT notehead -chord construct NOT chord (when referring to <>) -@end example +@item +@emph{Note head} NOT notehead. + +@item +@emph{Chord construct} NOT just chord (when referring to < ... >) + +@item +@emph{Staff} NOT stave. + +@item +@emph{Staves} NOT Staffs: +Phrases such as +@q{multiple @@internalsref@{Staff@}s} +should be rephrased to +@q{multiple @@internalsref@{Staff@} contexts}. @end itemize + @end itemize @@ -1224,7 +1288,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? @@ -1253,7 +1317,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. @@ -1325,7 +1389,7 @@ scripts/auxiliar/doc-section.sh MANUAL SECTION @noindent where @code{SECTION} is the name of the file containing the section -to be build, and @code{MANUAL} isc replaced by the name of the directory +to be built, and @code{MANUAL} is replaced by the name of the directory containing the section. So, for example, to build section 1.1 of the Notation Reference, use the command: @@ -1379,15 +1443,9 @@ scripts/auxiliar/strip-whitespace.py Documentation/FILENAME @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 @@ -1395,7 +1453,7 @@ This also updates translated documentation. 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 @@ -1518,7 +1576,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 @@ -1636,19 +1694,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 @@ -1674,15 +1732,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 @@ -1694,7 +1752,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 @@ -1809,7 +1867,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/} @@ -1817,7 +1875,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. @@ -1859,8 +1917,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 @@ -1881,8 +1939,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 @@ -1892,8 +1950,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 @@ -1931,12 +1989,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 @@ -1987,9 +2045,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 @@ -2153,7 +2211,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, @@ -2169,21 +2227,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