@c -*- coding: utf-8; mode: texinfo; documentlanguage: ja -*-
@ignore
- Translation of GIT committish: fabcd22c8f88ea9a87241597f1e48c0a9adbfc6e
+ Translation of GIT committish: 5fb3f8cf17ce7b57d22584429d736f188e4827d7
When revising a translation, copy the HEAD committish of the
version that you are working on. For details, see the Contributors'
@c \version "2.16.0"
-@c Translators: Yoshiki Sawada
+@c Translators: Tomohiro Tatejima, Yoshiki Sawada
@c Translation status: post-GDP
@cindex Updating a LilyPond file (LilyPond ファイルを更新する)
@cindex convert-ly
-LilyPond の入力構文は、さまざまな方法で単純化または改善するために、@c
-定期的に変更されます。@c
-その副作用として、LilyPond のインタプリタは@c
-しばしば古い入力ファイルと互換性を持たなくなります。@c
-これを救済するために、プログラム @command{convert-ly} を用いることで、@c
-たいていの LilyPond のバージョン間での構文変更を処理することができます。
+LilyPond が改善していくにつれ、いくつかのコマンドや関数の構文 (入力言語) は@c
+変わることがあります。このことによって、昔のバージョンの LilyPond で作られた@c
+入力ファイルを新しいバージョンで使う時に、予期しないエラーや警告、あるいは@c
+誤った出力を引き起こす可能性があります。
+これに対処するため、このような昔の入力ファイルを新しい構文に更新する
+@command{convert-ly} コマンドを使うことができます。
@menu
* 何故構文は変更されるのか？::
* convert-ly のコマンド ライン オプション::
* convert-ly の問題点::
* 手動変換::
+* 複数のバージョンに対応するコードを書く::
@end menu
@node 何故構文は変更されるのか？
@cindex convert-ly
@cindex updating old input files (古い入力ファイルを更新する)
-LilyPond の入力構文はしばしば変更されます。@c
-LilyPond 自体が改良されるため、構文 (入力言語) もそれに合わせて変更されます。@c
-変更の目的は、入力ファイルを読みやすく、書きやすくするためであったり、@c
-LilyPond に新しい機能を持たせるためであったりします。
+入力ファイルを読みやすく、書きやすくするために、しばしば構文は変更されますが、@c
+時により既存の関数が、新しい機能や改善に合わせて変更されることがあります。
-例えば、@code{\paper} と @code{\layout} のプロパティ名は
+これが実際にあった例です:
+
+@code{\paper} と @code{\layout} のプロパティ名は全て、@c
@code{first-second-third} という形式で記述することになっています。@c
しかしながら、バージョン 2.11.60 で @code{printallheaders} プロパティが@c
この規則に従っていないことが判明しました。@c
(新しいユーザはつじつまの合わない入力形式で混乱するでしょう。)
それとも、変更すべきでしょうか？
(既存の楽譜を持つユーザには煩わしいことです。)
+
このケースでは、プロパティ名を @code{print-all-headers} に変更することを@c
-決断しました。@c
-幸運なことに、@c
-この変更は @command{convert-ly} ツールで自動的に変換することができます。
+決断しました。そして、昔のユーザは @command{convert-ly} コマンドによって@c
+既にある入力ファイルを自動的にアップデートすることができました。
-不幸なことに、@c
+しかし、@c
@command{convert-ly} はすべての変更を処理できるわけではありません。@c
-例えば、バージョン 2.4 以前の LilyPond では、@c
-ã\82¢ã\82¯ã\82»ã\83³ã\83\88æ\96\87å\97ã\81¨é\9d\9eè\8b±èª\9eæ\96\87å\97ã\82\92 LaTeX ã\82\92ç\94¨ã\81\84ã\81¦å\85¥å\8a\9bã\81\97ã\81¦ã\81\84ã\81¾ã\81\97ã\81\9f
--- Christmas のフランス語は @code{No\"el} のように入力されていました。@c
+例えば、バージョン 2.4.2 以前の LilyPond では、@c
+ã\82¢ã\82¯ã\82»ã\83³ã\83\88æ\96\87å\97ã\81¨é\9d\9eè\8b±èª\9eæ\96\87å\97ã\82\92 LaTeX ã\81®è¨\98æ³\95ã\82\92ç\94¨ã\81\84ã\81¦å\85¥å\8a\9bã\81\97ã\81¦ã\81\84ã\81¾ã\81\97ã\81\9fã\80\82
+例えば Christmas のフランス語は @code{No\"el} のように入力されていました。@c
しかしながら、バージョン 2.6 以降の LilyPond では、@c
-ç\89¹æ®\8aæ\96\87å\97 @code{Ã\83«} ã\82\92 UTF-8 æ\96\87å\97ã\81¨ã\81\97ã\81¦ç\9b´æ\8e¥ LilyPond ã\83\95ã\82¡ã\82¤ã\83«ã\81«@c
-å\85¥å\8a\9bã\81\99ã\82\8bã\81\93ã\81¨ã\81«なりました。@c
+特殊文字 @code{ë} を UTF-8 文字として直接 LilyPond ファイルに@c
+å\85¥å\8a\9bã\81\97ã\81ªã\81\91ã\82\8cã\81°ã\81ªã\82\89ã\81ªã\81\8fなりました。@c
@command{convert-ly} はすべての LaTeX の特殊文字を UTF-8 文字に変換する@c
ことはできません。@c
手動で古い LilyPond 入力ファイルを更新する必要があります。
+@command{convert-ly} コマンドの変換ルールは、テキストのパターンマッチングと@c
+置換によって動作しています (つまり、与えられた入力ファイルの中で何が@c
+変更されたかの文脈を@q{理解}してはいないということです)。
+これはいくつかの結果をもたらします:
+
+@itemize @bullet
+@item
+変換の信頼性は、それぞれの適用されるルールセットの品質と、@c
+対応する変更の複雑さ次第です。変換が、追加・手動の修正を要求することが@c
+あります。ですから万が一のために、変換前の入力ファイルは比較のために@c
+残しておくべきです。
+
+@item
+より新しいバージョンへの構文の変更のみが可能です: LilyPond の昔のバージョンへ@c
+変換するルールセットは存在しません。そのため、入力ファイルを更新@c
+するのは、昔のバージョンの LilyPond がもうメンテナンスされていない時に限る@c
+べきです。繰り返しますが、万が一のために変換前の入力ファイルは残しておくべき@c
+です。Git のようなバージョン管理システムを使うと、複数のバージョンの@c
+入力ファイルを管理するのに役立つかもしれません。
+
+@item
+LilyPond は処理の際、余計に配置された、あるいは省略された空白に@c
+左右されません。しかし、@command{convert-ly} で用いられるルールはコードの@c
+スタイルにいくらかの仮定を置く場合があります。ですから、正常な変換を@c
+行うために、LilyPond のマニュアルで用いられるスタイルに従うことを推奨します。@c
+特にマニュアル自体、すべての例が @command{convert-ly} コマンドで@c
+更新されています。
+@end itemize
+
@node convert-ly を呼び出す
@section @command{convert-ly} を呼び出す
@translationof Invoking convert-ly
-@command{convert-ly} ã\81¯å\8f¤ã\81\84ã\83\90ã\83¼ã\82¸ã\83§ã\83³ç\95ªå\8f·を検出するために@c
-入力ファイルの @code{version} ステートメントを使用します。@c
+@command{convert-ly} ã\82³ã\83\9eã\83³ã\83\89ã\81¯å\8f¤ã\81\84ã\83\90ã\83¼ã\82¸ã\83§ã\83³を検出するために@c
+入力ファイルの @code{version} 番号を使用します。@c
たいていの場合、あなたの入力ファイルを更新するには、@c
-そのファイルを保持しているディレクトリで以下を実行することで十分です:
+その入力ファイルを保持しているディレクトリで以下を実行するだけで十分です:
@example
convert-ly -e myfile.ly
@end example
@noindent
-これにより、@code{myfile.ly} は更新され、@c
-オリジナル ファイルは @code{myfile.ly~} に保存されます。
+これにより、@code{myfile.ly} はその場で更新され、@c
+オリジナル ファイルは @code{myfile.ly~} に名前が変更されて保存されます。@c
+更新された入力ファイルの @code{\version} 番号も、必要な構文の更新に合わせて@c
+変更されます。
-@warning{@command{convert-ly} のバージョンは、@c
-それが扱う最新の構文変更に合わせて変更されます。@c
-このため、入力ファイルの @code{\version} 番号はたいてい@c
-@command{convert-ly} のバージョンよりも低いことになります。}
+@command{convert-ly} コマンドが実行される時、変換が行われるバージョンの番号を@c
+出力します。バージョン番号が出力されなかった場合、そのファイルは既に@c
+更新されており、最新の LilyPond 構文を使用しています。
-ディレクトリの中にある入力ファイルをすべて変換するには、@c
-以下のようにします:
+@warning{LilyPond の新しいバージョンごとに、新しい @command{convert-ly}
+コマンドが作られます。しかし、全てのバージョンがその前のバージョンの@c
+入力ファイルから構文の変更を必要とするわけではありません。つまり
+@command{convert-ly} コマンドは、入力ファイルをその時点の最新の構文にまで@c
+しか変換しないということであり、逆に言えば、変換されたファイルの
+@code{\version} 番号が @command{convert-ly} コマンド自体のバージョンより@c
+前のバージョンになる場合もあるということです。}
+
+単一のディレクトリにある全ての入力ファイルを変換するには、以下のようにします:
@example
convert-ly -e *.ly
@end example
-オリジナル ファイルをそのまま残しておき、
-更新されたファイルに新しいファイル名を指定するには以下のようにします:
+Linux や MacOS@tie{}X のユーザーは、適当なターミナルからこのコマンドを@c
+実行できますが、MacOS@tie{}X のユーザーは、メニューの
+@code{Compile > Update syntax} からも直接コマンドを実行できます。
+
+Windows ユーザーがコマンド ラインを用いる場合はこのようになります:
@example
-convert-ly myfile.ly > mynewfile.ly
+convert-ly.py -e *.ly
+@end example
+
+@noindent
+これを、@code{コマンド プロンプト}から実行します。@c
+@code{コマンド プロンプト}は通常、@c
+@code{スタート > アクセサリ > コマンド プロンプト}にありますが、@c
+Windows 8 ユーザーであるなら、検索ウィンドウに@q{コマンド プロンプト}と@c
+入力することでも実行できます。
+
+複数のサブディレクトリ内にある全ての入力ファイルを変換するには、@c
+以下のようにします:
+
+@example
+find . -name '*.ly' -exec convert-ly -e '@{@}' \;
@end example
-このプログラムは変換元のバージョン番号をリストアップします。
-バージョン番号がリストアップされない場合、@c
-そのファイルは最新であるということになります。
+この例は、現在のディレクトリとその下にある全てのディレクトリに存在する@c
+入力ファイルを、再帰的に見つけ出し変換します。変換されたファイルは@c
+リネームされた元のファイルと同じディレクトリに配置されます。これは
+MacOS@tie{}X でも動作するはずです (ターミナルからの実行のみとなりますが)。
+
+Windows ユーザーは以下のようにします:
+
+@example
+forfiles /s /M *.ly /c "cmd /c convert-ly.py -e @@file"
+@end example
+
+代わりに、@code{/p} オプションを使って、入力ファイルを含む全てのサブフォルダを@c
+保持したトップレベルのフォルダを指定することができます:
+
+@example
+forfiles /s /p C:\Documents\MyScores /M *.ly /c "cmd /c convert-ly.py -e @@file"
+@end example
-MacOS@tie{}X ユーザはこのコマンドをメニュー エントリ
-(@code{Compile > Update syntax}) 下で実行することになるかもしれません。
+トップレベルのフォルダへのパスにスペースが含まれる場合には、パス全体を@c
+ダブルクォートで括る必要があります:
-Windows ユーザはこれらのコマンドを @q{コマンド プロンプト} ウィンドウから@c
-実行する必要があります。@c
-コマンド プロンプトは通常、@code{スタート > アクセサリ > コマンド プロンプト}
-で見つかります。
+@example
+forfiles /s /p "C:\Documents\My Scores" /M *.ly /c "cmd /c convert-ly.py -e @@file"
+@end example
@node convert-ly のコマンド ライン オプション
@table @code
@item -d, --diff-version-update
-@code{\version} を最新に更新します。最新バージョンよりも大きい場合は@c
-何もしません。
+ファイルが実際に変更された場合にのみ @code{\version} を更新します。
+これを指定した場合のバージョン番号は、最後に実際に変換が行われた後の@c
+バージョンに対応します。不安定版のバージョン番号は、ターゲットの@c
+バージョン番号を超えない限り、次の安定版のバージョン番号に上げられます。@c
+このオプションを指定しないと、最後の変換を@emph{行おうとした}バージョンに更新@c
+されます。
@item -e, --edit
-入力ファイルに直接変換を適用して、それをその場で変更します。
+入力ファイルをその場で直接変換します。@c
+変換元のファイルは @file{myfile.ly~} のように名前が変更されます。@c
+このバックアップファイルは、オペレーティングシステムによっては@c
+隠しファイルとして扱われているかもしれません。@c
+古い入力ファイルに @code{~} を付加する @code{-e} を使わずに、@c
+更新されたファイルの名前を別に指定したい場合は、代わりに@c
+出力をリダイレクトすることができます:
+
+@example
+convert-ly myfile.ly > mynewfile.ly
+@end example
+
+Windows ユーザーは:
+
+@example
+convert-ly.py myfile.ly > mynewfile.ly
+@end example
+
+@item -b, --backup-numbered
+@samp{-e} オプションと同時に用いた場合、前のバージョンのファイルが上書き@c
+されないように、バックアップファイルの名前に番号が付きます。@c
+バックアップファイルは、オペレーティングシステムによっては@c
+隠されているかもしれません。
@item -f, --from=@var{from-patchlevel}
変換元のバージョンをセットします。@c
@item -t, --to=@var{to-patchlevel}
変換先のバージョンを明示してセットします。@c
-明示されない場合は、デフォルトで最新バージョンにセットします。
+明示されない場合は、デフォルトで最新バージョンにセットします。@c
+変換元のバージョンよりも高くなっている必要があります。
@example
convert-ly --to=2.14.1 myfile.ly
以下を使用してください:
@example
-convert-ly --from=... --to=... --no-version *.itely
+convert-ly --from=@dots{} --to=@dots{} --no-version *.itely
@end example
2 つのバージョン間での LilyPond 構文の変更を調べるには、@c
以下を使用してください:
@example
-convert-ly --from=... --to=... -s
+convert-ly --from=@dots{} --to=@dots{} -s
@end example
\score{} must now begin with a music expression. Anything else
(particularly \header{}) must come after the music.
@end verbatim
+
+
+@node 複数のバージョンに対応するコードを書く
+@section 複数のバージョンに対応するコードを書く
+@translationof Writing code to support multiple versions
+
+いくつかの場面で、特に@emph{ライブラリの}コードを書く場合、破壊的な構文変更を@c
+含んだ複数の LilyPond バージョンをサポートすることは望ましいでしょう。@c
+これは、バージョンによって変更が必要な部分を、現在実行されている
+LilyPond のバージョンで分岐する条件文で囲むことで実現できます。@c
+Scheme 関数 @code{ly:version?} は比較演算子 @var{op} と、比較の対象となる@c
+バージョンを 3 つまでの整数のリストで表現した @var{ver} を引数に取ります。
+整数の数が足りない場合は無視されます。例えば、@code{'(2 20)} は@c
+@emph{全ての} 2.20 の系列のバージョンと等しくなります。@c
+このような表記が可能です:
+
+@verbatim
+#(cond
+ ((ly:version? > '(2 20))
+ (ly:message "This is code to run for LilyPond after 2.20"))
+ ((ly:version? = '(2 19 57))
+ (ly:message "This will only be executed with LilyPond 2.19.57"))
+ (else (ly:message "This will be executed in any other version")))
+@end verbatim
+
+通常、これは (訳注: バージョンによって) 別の構文が使えるようにするために@c
+ライブラリ関数に組み込まれますが、以下の例のように、比較を直接音楽の中に@c
+用いることもできます:
+
+@verbatim
+{
+ c' d' e' f'
+ #(if (ly:version? = '(2 21))
+ #{ \override NoteHead.color = #red #}
+ #{ \override NoteHead.color = #blue #})
+ g' a' b' c''
+}
+@end verbatim
+
+@strong{注意:} この関数は LilyPond 2.19.57 で導入されました。@c
+そのため、それより古いバージョンと比較することはできません。
projects / lilypond.git / blobdiff