X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fdevel%2Fdoc-work.itexi;h=2e447deb4c60aca5f15a989258c22181122cd889;hb=b97565a9af1c13369ac7e7e9ea80c2638dbc0e51;hp=6a571ec1c9d7e62fc85a2f9fb8d65e366dcb3b99;hpb=5e1a3da03041f2a1eb43fb5d392a8b14a5ff8b9e;p=lilypond.git diff --git a/Documentation/devel/doc-work.itexi b/Documentation/devel/doc-work.itexi index 6a571ec1c9..2e447deb4c 100644 --- a/Documentation/devel/doc-work.itexi +++ b/Documentation/devel/doc-work.itexi @@ -3,12 +3,13 @@ @chapter Documentation work @menu -* Introduction to documentation work:: -* Texinfo introduction and usage policy:: -* Documentation policy:: -* Tips for writing docs:: -* Updating docs with convert-ly:: -* Translating the documentation:: +* Introduction to documentation work:: +* Documentation suggestions:: +* Texinfo introduction and usage policy:: +* Documentation policy:: +* Tips for writing docs:: +* Updating docs with convert-ly:: +* Translating the documentation:: @end menu @@ -51,18 +52,107 @@ they also stem from attempting to find the most effective use of limited documentation help. +@node Documentation suggestions +@section Documentation suggestions + +@subheading Small additions + +For additions to the documentation, + +@enumerate + +@item +Tell us where the addition should be placed. Please include both +the section number and title (i.e. "LM 2.13 Printing lyrics"). + +@item +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: + +@verbatim +To: lilypond-devel@gnu.org +From: helpful-user@example.net +Subject: doc addition + +In LM 2.13 (printing lyrics), above the last line ("More options, +like..."), please add: + +---- +To add lyrics to a divided part, use blah blah blah. For example, + +\score { + \notes {blah <> } + \lyrics {blah <> } + blah blah blah +} +---- + +In addition, the second sentence of the first paragraph is +confusing. Please delete that sentence (it begins "Users +often...") and replace it with this: +---- +To align lyrics with something, do this thing. +---- + +Have a nice day, +Helpful User +@end verbatim + +@end enumerate + + +@subheading Larger contributions + +To replace large sections of the documentation, the guidelines are +stricter. We cannot remove parts of the current documentation +unless we are certain that the new version is an improvement. + +@enumerate + +@item +Ask on the lilypond-devel maillist if such a rewrite is necessary; +somebody else might already be working on this issue! + +@item +Split your work into small sections; this makes it much easier to +compare the new and old documentation. + +@item +Please prepare a formal git patch. + +@end enumerate + +Once you have followed these guidelines, please send a message to +lilypond-devel with your documentation submissions. Unfortunately +there is a strict “no top-posting” check on the mailist; to avoid +this, add: + +> I'm not top posting. + +(you must include the > ) to the top of your documentation +addition. + +We may edit your suggestion for spelling, grammar, or style, and +we may not place the material exactly where you suggested, but if +you give us some material to work with, we can improve the manual +much faster. Thanks for your interest! + @node Texinfo introduction and usage policy @section Texinfo introduction and usage policy @menu -* Texinfo introduction:: -* Documentation files:: -* Sectioning commands:: -* LilyPond formatting:: -* Text formatting:: -* Syntax survey:: -* Other text concerns:: +* Texinfo introduction:: +* Documentation files:: +* Sectioning commands:: +* LilyPond formatting:: +* Text formatting:: +* Syntax survey:: +* Other text concerns:: @end menu @@ -458,9 +548,27 @@ B ... @@end itemize - for bulleted lists. @item @@bs - Generates a backslash inside @@warning. - Any `\' used inside @@warning (and @@q or @@qq) must be written as `@@bs@{@}' + Any `\' used inside @@warning (and @@q or @@qq) must be written as `@@bs@{@}' (texinfo would also allow \\, but this breaks with PDF output). +@item +@@ref@{@} - normal references (type the exact node name inside the +@{@}). +@item +@@ruser@{@} - link to the NR. +@item +@@rlearning@{@} - link to the LM. +@item +@@rglos@{@} - link to the MG. +@item +@@rprogram@{@} - link to the AU. +@item +@@rlsr@{@} - link to a Snippet section. +@item +@@rinternals@{@} - link to the IR. +@item +@@uref@{@} - link to an external url. + @end itemize @@ -524,11 +632,11 @@ that all such characters appear in all output formats. @section Documentation policy @menu -* Books:: -* Section organization:: -* Checking cross-references:: -* General writing:: -* Technical writing style:: +* Books:: +* Section organization:: +* Checking cross-references:: +* General writing:: +* Technical writing style:: @end menu @node Books @@ -870,7 +978,7 @@ lilypond examples. Making easily-understandable examples is much harder than it looks. -@subsubheading TWEAKS +@subsubheading Tweaks In general, any \set or \override commands should go in the @qq{select snippets} section, which means that they should go in @@ -908,6 +1016,10 @@ or upgrading tweaks is creating tweaks to deal with known issues. It would be ideal if every significant known issue had a workaround to avoid the difficulty. +@seealso + +@ref{Adding and editing snippets}. + @node Updating docs with convert-ly @section Updating doc with @command{convert-ly} @@ -927,11 +1039,12 @@ This also updates translated documentation. @section Translating the documentation @menu -* Getting started with documentation translation:: -* Documentation translation details:: -* Documentation translation maintenance:: -* Translations management policies:: -* Technical background:: +* Getting started with documentation translation:: +* Documentation translation details:: +* Documentation translation maintenance:: +* Translations management policies:: +* Technical background:: +* Translation status:: @end menu @node Getting started with documentation translation @@ -941,9 +1054,9 @@ First, get the sources from the Git repository, see @ref{Documentation translations source code}. @menu -* Translation requirements:: -* Which documentation can be translated:: -* Starting translation in a new language:: +* Translation requirements:: +* Which documentation can be translated:: +* Starting translation in a new language:: @end menu @node Translation requirements @@ -1040,10 +1153,10 @@ Please follow all the instructions with care to ensure quality work. All files should be encoded in UTF-8. @menu -* Files to be translated:: -* Translating the Learning Manual and other Texinfo documentation:: -* Translating the Notation Reference and Application Usage:: -* Translating the Documentation index index.html.in:: +* Files to be translated:: +* Translating the Learning Manual and other Texinfo documentation:: +* Translating the Notation Reference and Application Usage:: +* Translating the Documentation index index.html.in:: @end menu @node Files to be translated @@ -1181,8 +1294,8 @@ easier. These helper scripts make use of the power of Git, the version control system used for LilyPond development. @menu -* Check state of translation:: -* Updating documentation translation:: +* Check state of translation:: +* Updating documentation translation:: @end menu @node Check state of translation @@ -1323,8 +1436,8 @@ be managed, they aim at helping translators, developers and coordinators work efficiently. @menu -* Maintaining without updating translations:: -* Managing documentation translation with Git:: +* Maintaining without updating translations:: +* Managing documentation translation with Git:: @end menu @node Maintaining without updating translations @@ -1432,7 +1545,7 @@ make ISOLANG=@var{YOUR-LANGUAGE} fix-xrefs @noindent This step requires a sucessful documentation build (with @command{make -web}). Some cross-references are broken because they point to a node +doc}). Some cross-references are broken because they point to a node that exists in the documentation in English, which has not been added to the translation; in this case, do not fix the cross-reference but keep it "broken", so that the resulting HTML link will point to an @@ -1488,13 +1601,13 @@ its documentation, and in this case they should be pushed to @code{stable/X.Y} are preferably made on @code{lilypond/X.Ytranslation}. -@item @code{lilypond/translation} Git branch may be merged into master only if -LilyPond (@command{make all}) and documentation (@command{make web}) compile -succesfully. +@item @code{lilypond/translation} Git branch may be merged into +master only if LilyPond (@command{make all}) and documentation +(@command{make doc}) compile succesfully. @item @code{master} Git branch may be merged into @code{lilypond/translation} whenever @command{make} and @command{make -web} are succesful (in order to ease documentation compilation by +doc} are succesful (in order to ease documentation compilation by translators), or when significant changes had been made in documentation in English in master branch. @@ -1555,3 +1668,9 @@ And finally @itemize @item @file{python/langdefs.py} -- language definitions module @end itemize + + +@node Translation status +@subsection Translation status + +