@c -*- coding: utf-8; mode: texinfo; documentlanguage: ja -*-

@ignore
    Translation of GIT committish: f11513f36c131dab18338d6a3a729e24a927150d

    When revising a translation, copy the HEAD committish of the
    version that you are working on.  For details, see the Contributors'
    Guide, node Updating translation committishes..
@end ignore

@c \version "2.23.8"

@c Translators: Tomohiro Tatejima, Yoshiki Sawada, Hiroshi Fukuhara
@c Translation status: post-GDP

@node デフォルトを変更する
@chapter デフォルトを変更する
@translationof Changing defaults

LilyPond はデフォルトで最高品質の出力を提供できるよう設計されています。@c
それにもかかわらず、@c
デフォルトのレイアウトを変更する必要が発生する場合もあります。@c
レイアウトは、@q{プロパティ} と呼ばれる多数の @q{つまみとスイッチ} によって@c
制御されています。@c
これらのプロパティにアクセスし、変更するための手引は学習マニュアルの中にあります
-- @rlearning{出力を調整する} を参照してください。@c
まずはこれを読むべきです。@c
本章は同様の内容をカバーしていますが、@c
よりリファレンス マニュアルに適したスタイルで提供します。

@cindex Internals Reference (内部リファレンス)

調整のために利用できる制御の定義についての説明は、@c
別のドキュメントの中にあります: @rinternalsnamed{Top,内部リファレンス} です。@c
このマニュアルは利用可能なすべての変数、関数、それにオプションを@c
リストアップしています。@c
これは HTML ドキュメントとして記述されていて、@c
@uref{https://lilypond.org/doc/stable/Documentation/internals/,オンライン}
で入手可能であり、@c
LilyPond ドキュメント パッケージにも含まれています。

内部的には、LilyPond は Scheme (LISP 派生語) を用いて機能を提供しています。@c
レイアウトについての決定をオーバライドすることは、@c
プログラムの内部にアクセスすることであり、@c
Scheme 入力が必要になります。@c
Scheme の要素は、@code{.ly} の中で、@c
ハッシュ記号 @code{#} を付けて記述します。@footnote{@rextend{Scheme tutorial}
の中に、Scheme 形式で数、リスト、文字列、それに記号を入力するための@c
簡単な手引きがあります。}


@menu
* コンテキストを理解する::
* 内部リファレンスの説明::
* プロパティを変更する::
* 役に立つコンセプトとプロパティ::
* 高度な調整::
* 音楽関数を使用する::
@end menu


@node コンテキストを理解する
@section コンテキストを理解する
@translationof Interpretation contexts

このセクションでは、コンテキストとは何なのか、@c
それをどのように変更するのかについて説明します。

@menu
* コンテキストの説明::
* コンテキストを作成して参照する::
* コンテキストを残しておく::
* コンテキストのプラグインを変更する::
* コンテキストのデフォルト設定を変更する::
* 新しいコンテキストを定義する::
* コンテキストの配置順序::
@end menu

@morerefs
学習マニュアル:
@rlearning{コンテキストとエングラーバ}

インストールされているファイル:
@file{ly/engraver-init.ly},
@file{ly/performer-init.ly}

コード断片集:
@rlsr{Contexts and engravers}

内部リファレンス:
@rinternals{Contexts},
@rinternals{Engravers and Performers}


@node コンテキストの説明
@subsection コンテキストの説明
@translationof Contexts explained

@ignore
@c TODO Rethink and rewrite

>> > > - list of contexts: my *danger unmaintainable*
>> > > alarm just went off.  I'm

I knew it would... And leaving out some of them is perfectly fine
with me.
I do think that a list like this, with the main contexts and a
brief
description of  what they do (perhaps also with a note about what
default
behavior is associated with each of them, but this may be
unmanageable),
should be there, and then we could simply list the remaining ones
without
further explanation and with links to the IR.
@end ignore

@c TODO Improve layout, order and consistency of wording -td

@c TODO Add introduction which explains contexts in generality  -td

@c TODO Describe propagation of property values -td

コンテキストは階層的に配置されます:

@menu
* 出力定義 - コンテキストの青写真::
* Score - すべてのコンテキストのマスタ::
* 上位コンテキスト - 譜コンテナ::
* 中位コンテキスト - 譜::
* 下位コンテキスト - ボイス::
@end menu

@node 出力定義 - コンテキストの青写真
@unnumberedsubsubsec 出力定義 - コンテキストの青写真
@translationof Output definitions - blueprints for contexts

このセクションでは、コンテキストを扱う際の出力定義との関連について説明します。@c
実際の出力定義の例については、後で提示します
(@ref{Changing all contexts of the same type} を参照してください)。

@cindex output definition (出力定義)
@funindex \layout

ファイルに記述される音楽は、コンテキストの種類や名前を参照しますが、@c
コンテキストが作成されるのは、音楽が実際に解釈される時です。LilyPond は@c
@q{出力定義}に基づいて音楽を解釈し、異なる出力定義は異なる出力をもたらします。@c
楽譜の見た目の出力に関係する出力定義は @code{\layout} で指定します。

@funindex \midi
MIDI 出力を作り出すのに使われる出力定義はもっと単純で、@code{\midi} によって@c
指定されます。他の出力定義も LilyPond では内部的に使用されます。例えば@c
パートを結合する出力定義 (@ref{Automatic part combining}) や音楽の引用を@c
作り出す出力定義 (@ref{Quoting other voices}) などです。

出力定義は、各コンテキストのデフォルトの設定だけでなく、@c
コンテキスト同士の関係も定義します。多くの変更は通常 @code{\layout} ブロックで@c
行われますが、MIDI に関係した設定は @code{\midi} ブロックで変更された場合に@c
のみ効果があります。

@funindex autoBeaming
いくつかの設定は複数の出力に効果があります: 例えば、@code{autoBeaming} が@c
あるコンテキストでオフになった場合、@ref{Automatic syllable durations}
で説明しているように、連桁は歌詞を音楽に合わせるためのメリスマとして@c
扱われます。この位置合わせは見た目の出力だけでなく MIDI 出力でも行われます。@c
@code{autoBeaming} が @code{\layout} ブロックの出力定義内で変更されており、@c
しかし対応する @code{\midi} ブロックでは変更されていない場合、MIDI では@c
歌詞と音楽が一致しなくなります。

@morerefs
インストールされているファイル:
@file{ly/engraver-init.ly},
@file{ly/performer-init.ly}

@node Score - すべてのコンテキストのマスタ
@unnumberedsubsubsec Score - すべてのコンテキストのマスタ
@translationof Score - the master of all contexts

これは最上位の記譜コンテキストです。@c
他のコンテキストが Score コンテキストを保持することはできません。@c
デフォルトでは、Score コンテキストが拍子記号の管理を扱い、@c
音部記号、拍子記号、調号などのアイテムが譜間で揃っていることを保証します。

Score コンテキストは、@code{\score @{@dots{}@}}
ブロックが処理されたときに暗黙的にインスタンス化されます。@c

@node 上位コンテキスト - 譜コンテナ
@unnumberedsubsubsec 上位コンテキスト - 譜コンテナ
@translationof Top-level contexts - staff containers

@strong{@emph{StaffGroup}}

譜をグループ化して、左端に角括弧を付けます。@c
このコンテキストに保持されている譜の小節線は垂直につながります。@c
@code{StaffGroup} は譜のコレクション、@c
それに左端の角括弧と延長された小節線だけを保持します。

@strong{@emph{ChoirStaff}}

保持されている譜の小節線が垂直につながらないことを除けば、@c
@code{StaffGroup} と同じです。

@strong{@emph{GrandStaff}}

譜をグループ化して、左端に波括弧を付けます。@c
このコンテキストに保持されている譜の小節線は垂直につながります。@c

@strong{@emph{PianoStaff}}

@code{GrandStaff} と似ていますが、@c
各システムの左端に楽器名を付けることができます。


@node 中位コンテキスト - 譜
@unnumberedsubsubsec 中位コンテキスト - 譜
@translationof Intermediate-level contexts - staves

@strong{@emph{Staff}}

音部記号、小節線、調、臨時記号を扱います。@c
このコンテキストは @code{Voice} コンテキストを保持することができます。

@strong{@emph{RhythmicStaff}}

@code{Staff} と似ていますが、リズムを表示するためのものです。@c
ピッチは譜刻には無視され、音符は線として表示されます。MIDI 出力では@c
ピッチは変更されません。

@strong{@emph{TabStaff}}

タブ譜を生成するためのコンテキストです。@c
デフォルトでは、音楽表記を 6 線のギター タブ譜として配置します。

@strong{@emph{DrumStaff}}

打楽器の譜刻を扱います。@c
@code{DrumVoice} を保持することができます。

@strong{@emph{VaticanaStaff}}

@code{Staff} と同じですが、@c
グレゴリオ聖歌形式の楽曲を譜刻するためにデザインされている点が異なります。

@strong{@emph{MensuralStaff}}

@code{Staff} と同じですが、@c
計量形式の楽曲を譜刻するためにデザインされている点が異なります。

@node 下位コンテキスト - ボイス
@unnumberedsubsubsec 下位コンテキスト - ボイス
@translationof Bottom-level contexts - voices

Voice レベルのコンテキストはある特定のプロパティを初期化し、@c
適切なエングラーバを開始させます。@c
下位コンテキストは @code{defaultchild} を持たないコンテキストです。@c
中にコンテキストを受け入れたり保持することはできますが、@c
明示的に作成され入力される必要があります。

@strong{@emph{Voice}}

譜の上にあるボイスに相当します。@c
このコンテキストは、強弱記号、符幹、連桁、上付き/下付き文字、タイ、@c
それに休符の変換を扱います。@c
1 つの譜に複数のボイスを配置する必要がある場合、@c
ボイスを明示的にインスタンス化する必要があります。

@strong{@emph{VaticanaVoice}}

@code{Voice} と同じですが、@c
グレゴリオ聖歌形式の楽曲を譜刻するためにデザインされている点が異なります。

@strong{@emph{MensuralVoice}}

@code{Voice} と同じですが、@c
定量形式の楽曲を譜刻するためにデザインされている点が異なります。

@strong{@emph{Lyrics}}

歌詞を保持するボイスに相当します。単一行の歌詞の表示を扱います。

@strong{@emph{DrumVoice}}

打楽器譜で使用されるボイス コンテキストです。

@strong{@emph{FiguredBass}}

このコンテキストの中で、@c
@code{\figuremode} モードで記述された入力から
@code{BassFigure} オブジェクトが作成されます。

@strong{@emph{TabVoice}}

@code{TabStaff} コンテキスト内部で使用されるボイス コンテキストです。@c
通常、暗黙的に作成されます。

@strong{@emph{CueVoice}}

小さなサイズの音符を描画するために使用されるボイス コンテキストです。@c
主に合図音符を譜に付け加えることを目的としています。@c
@ref{合図音符をフォーマットする} を参照してください。@c
通常、暗黙的に作成されます。

@strong{@emph{ChordNames}}

コード ネームを譜刻します。

@ignore
TODO

Then the following, which I don't know what to do with:

    * GregorianTranscriptionVoice
    * GregorianTranscriptionStaff

    * FretBoards
        Engraves fretboards from chords. Not easy... Not
documented.
        There is now some documentation on FretBoards in the NR, under
         instrument-specific notation -- cds.

    * NoteNames

    * Global
        Hard coded entry point for LilyPond. Cannot be tuned.
    * Devnull
        Silently discards all musical information given to this
context.

@end ignore


@node コンテキストを作成して参照する
@subsection コンテキストを作成して参照する
@translationof Creating and referencing contexts

@funindex \new
@funindex \context
@cindex new context (新しいコンテキスト)
@cindex referencing context (コンテキストを参照する)
@cindex context, creating and referencing (コンテキストを作成して参照する)

LilyPond は、適切なコンテキストが存在しないうちに音楽表記に遭遇すると、@c
自動的に下位コンテキストを作成します。@c
しかしながら、通常これは、シンプルな楽譜やドキュメントの中の楽譜断片@c
のような単純な場合にしかうまくいきません。@c
もっと複雑な楽譜の場合、すべてのコンテキストを @code{\new} コマンドや
@code{\context} コマンドを用いて明示的に指定することをお勧めします。@c
これら 2 つのコマンドの構文はほとんど同じです:

@example
[\new | \context] @var{Context} [ = @var{name}] [@var{music-expression}]
@end example

@noindent
ここで、@code{\new} と @code{\context} のどちらかを使用します。@c
@var{Context} は作成するコンテキストのタイプであり、@var{name} は@c
作成されるコンテキストにオプションで付けることができる名前であり、@c
@var{music-expression} はこのコンテキストのエングラーバとパフォーマに@c
よって処理される単一の音楽表記です。

コンテキスト名を持たない @code{\new} コマンドは一般的に複数の譜を持つ
score を作成するのに用いられます:

@c KEEP LY
@lilypond[quote,verbatim]
<<
  \new Staff \relative {
    % 暗黙的に Voice コンテキストが作成されます
    c''4 c
  }
  \new Staff \relative {
    d''4 d
  }
>>
@end lilypond

@noindent
そして、1 つの譜に複数のボイスが配置されます:

@lilypond[quote,verbatim]
\new Staff <<
  \new Voice \relative {
    \voiceOne
    c''8 c c4 c c
  }
  \new Voice \relative {
    \voiceTwo
    g'4 g g g
  }
>>
@end lilypond

@noindent

無名のコンテキストは常に @code{\new} で指定する必要があります。

@code{\new} と @code{\context} は動作が異なります:

@itemize
@item
@code{\new} はコンテキスト名を持っているか、いないかにかかわらず、@c
例え同じ名前を持つコンテキストが存在していたとしても、常に全く新たな@c
コンテキストを作成します:

@lilypond[quote,verbatim]
\new Staff <<
  \new Voice = "A" \relative {
    \voiceOne
    c''8 c c4 c c
  }
  \new Voice = "A" \relative {
    \voiceTwo
    g'4 g g g
  }
>>
@end lilypond

@item
コンテキスト名を持つ @code{\context} は、階層、名前、それにタイプが@c
同じコンテキストが存在しない場合にのみ、新たなコンテキスを作成します。@c
存在する場合、@code{\context} はすでに作成されているコンテキストへの@c
参照となり、音楽表記はそのコンテキストに渡されて処理されます。

名前を持つコンテキストの用途の 1 つとして、楽譜レイアウトと音楽コンテンツ@c
を分離させることができます。@c
以下の 2 つの形式はどちらも有効です:

@c KEEP LY
@lilypond[quote,verbatim]
\score {
  <<
    % 楽譜レイアウト
    \new Staff <<
      \new Voice = "one" {
        \voiceOne
      }
      \new Voice = "two" {
        \voiceTwo
      }
    >>

    % 音楽コンテンツ
    \context Voice = "one" {
      \relative {
        c''4 c c c
      }
    }
    \context Voice = "two" {
      \relative {
        g'8 g g4 g g
      }
    }
  >>
}
@end lilypond

@c KEEP LY
@lilypond[quote,verbatim]
\score {
  <<
    % 楽譜レイアウト
    \new Staff <<
      \context Voice = "one" {
        \voiceOne
      }
      \context Voice = "two" {
        \voiceTwo
      }
    >>

    % 音楽コンテンツ
    \context Voice = "one" {
      \relative {
        c''4 c c c
      }
    }
    \context Voice = "two" {
      \relative {
        g'8 g g4 g g
      }
    }
  >>
}
@end lilypond

名前付きコンテキストの他の使用例として、2 つの音楽表記をつなげて
1 つのコンテキストにすることができます。@c
以下の例では、アーティキュレーションと音符は別々に入力されています:
@noindent
変数を用いても同じことができます。@c
@rlearning{Organizing pieces with variables} を参照してください。

@item
@funindex \applyContext
コンテキスト名を持たない @code{\context} は、階層とタイプが一致する@c
コンテキストのうち最初に作成されたものに適用され
(例えそのコンテキストが名前を持っていたとしても適用されます)、@c
音楽表記はそのコンテキストに渡されて処理されます。@c
この形式が有用なことは稀です。@c
しかしながら、コンテキスト名と音楽表記を持たない @code{\context}
は、コンテキスト内で @code{\applyContext} で記述した Scheme
プロシージャを実行させるのに用いられます:

@example
\new Staff \relative @{
  c'1
  \context Timing
  \applyContext #(lambda (ctx)
                   (newline)
                   (display (ly:context-current-moment ctx)))
  c1
@}
@end example

@end itemize

後で参照するコンテキストには名前を付ける必要があります。@c
例えば、歌詞を音楽に関連付けるような場合です:

@example
\new Voice = "tenor" @var{music}
@dots{}
\new Lyrics \lyricsto "tenor" @var{lyrics}
@end example

@noindent
歌詞を音楽に関連付ける方法についての詳細は
@ref{Automatic syllable durations} を参照してください。

ある特定のタイプのすべてのコンテキストのプロパティを @code{\layout}
ブロックで変更することができます (構文は異なります)
-- @ref{Changing all contexts of the same type} を参照してください。@c
この構造でもレイアウトを音楽コンテンツから分離させることができます。@c
単一のコンテキストを変更するのであれば、@code{\with} ブロックを用いる@c
必要があります -- @ref{Changing just one specific context} を参照@c
してください。

@morerefs

学習マニュアル:
@rlearning{Organizing pieces with variables}

記譜法リファレンス:
@ref{Changing just one specific context},
@ref{Automatic syllable durations}


@node コンテキストを残しておく
@subsection コンテキストを残しておく
@translationof Keeping contexts alive

@cindex context, keeping alive (コンテキストを残しておく)
@cindex context, lifetime (コンテキストのライフタイム)

通常、コンテキストは何もすることが無くなった最初の音楽的タイミングで@c
消滅させられます。@c
そのため、@code{Voice} コンテキストはすべてのイベントを終えるとすぐに消滅し、@c
@code{Staff} コンテキストは保持しているすべての @code{Voice} コンテキストの@c
イベントが終了するとすぐに消滅する、などとなっています。@c
このことは、早い段階にすでに消滅したコンテキストを参照する必要がある場合に、@c
障害となります。@c
例えば、@code{\change} コマンドで譜を変更する場合、@c
@code{\lyricsto} コマンドで歌詞をボイスに結び付ける場合、@c
あるいは、早い段階で登場したコンテキストに音楽イベントを追加する場合に@c
障害となります。

@ignore
以下2段落、翻訳に自信無し。
恐らくではあるが、以下のような挙動のことを示したいのだろう:
https://gist.github.com/suitougreentea/09e8c656d3d089e07ed79b6ded888bcc

原文:
There is an exception to this general rule: inside of an
@code{@{@dots{}@}} construct (sequential music), the construct's
notion of the ``current context'' will descend whenever an element
of the sequence ends in a subcontext of the previous current
context.  This avoids spurious creation of implicit contexts in a
number of situations but means that the first context descended
into will be kept alive until the end of the expression.

In contrast, the contexts of a @code{<<@dots{}>>} construct's
(simultaneous music) expression are not carried forth, so
enclosing a context creating command in an extra pair of
@code{<<@dots{}>>} will keep the context from persisting through
all of the enclosing @code{@{@dots{}@}} sequence.
@end ignore

この一般的な規則には 1 つ例外があります:
@code{@{@dots{}@}} 構文 (シーケンシャルな音楽) の中で、@c
構文が対象にする「現在のコンテキスト」は、@c
その中の要素が更に下位のコンテキストを扱う場合、@c
要素が終了した後もその下位のコンテキストを指し続けます。@c
これはいくつかの場合において、暗黙的なコンテキストが誤って作成されることを@c
防ぎますが、最初の下位コンテキストは、表記が終わるまで@c
残り続けるということを意味しています。

一方、@code{<<@dots{}>>} 構造 (同時に起こる音楽) の表記は@c
持続しません。そのため、コンテキストを作成するコマンドを、@c
余分な @code{<<@dots{}>>} で囲むことによって、新たなコンテキストが、@c
囲まれた @code{@{@dots{}@}} 表記全体にわたって残り続けることを@c
阻止することができます。

いかなる音楽タイミングでも何かすることがあるようにすることで、@c
任意のコンテキストを残しておくことができます。@c
@code{Staff} コンテキストを残しておくには、それに含まれるボイスの 1 つが@c
維持されることを保証する必要があります。@c
ボイスを残しておく方法の 1 つに、ボイスに含まれる実際の音楽と並列に、@c
空白休符をそのボイスに付け加えるという方法があります。@c
残しておく必要があるすべての @code{Voice} コンテキストに対して、@c
空白休符を付け加える必要があります。@c
ところどころで使用されるボイスがある場合、@c
前述の例外によって必要なボイスを残そうとするよりは、@c
それらのボイスすべてを残しておく方が安全です。

以下の例では、空白休符の追加を用いる方法で、@c
ボイス A とボイス B の両方が楽曲全体を通して維持されます:

@c KEEP LY
@lilypond[quote,verbatim]
musicA = \relative { d''4 d d d }
musicB = \relative { g'4 g g g }
keepVoicesAlive = {
  <<
    \new Voice = "A" { s1*5 }  % Voice "A" を 5 小節の間、維持する
    \new Voice = "B" { s1*5 }  % Voice "B" を 5 小節の間、維持する
  >>
}

music = {
  \context Voice = "A" {
    \voiceOneStyle
    \musicA
  }
  \context Voice = "B" {
    \voiceTwoStyle
    \musicB
  }
  \context Voice = "A" { \musicA }
  \context Voice = "B" { \musicB }
  \context Voice = "A" { \musicA }
}

\score {
  \new Staff <<
    \keepVoicesAlive
    \music
  >>
}
@end lilypond

@cindex lyrics, aligning with sporadic melody (途切れ途切れのメロディに歌詞を揃える)

以下の例は、空白休符を用いる方法で、@c
途切れ途切れのメロディに歌詞を持たせる方法を示しています。@c
もちろん、実際に楽譜を書く場合は、@c
メロディや伴奏は複数のセクションによって構成されることになります。

@c KEEP LY
@lilypond[quote,verbatim]
melody = \relative { a'4 a a a }
accompaniment = \relative { d'4 d d d }
words = \lyricmode { These words fol -- low the mel -- o -- dy }
\score {
  <<
    \new Staff = "music" {
      <<
        \new Voice = "melody" {
          \voiceOne
          s1*4  % Voice "melody" を 4 小節の間、残します
        }
        {
          \new Voice = "accompaniment" {
            \voiceTwo
            \accompaniment
          }
          <<
            \context Voice = "melody" { \melody }
            \context Voice = "accompaniment" { \accompaniment }
          >>
          \context Voice = "accompaniment" { \accompaniment }
          <<
            \context Voice = "melody" { \melody }
            \context Voice = "accompaniment" { \accompaniment }
          >>
        }
      >>
    }
    \new Lyrics \with { alignAboveContext = "music" }
    \lyricsto "melody" { \words }
  >>
}
@end lilypond

これに代わる方法として、メロディに直接空白休符を付け加えて、@c
メロディが伴奏と揃うようにする方法があります
-- 多くの場合、こちらの方法の方が良いかもしれません:

@c KEEP LY
@lilypond[quote,verbatim]
melody = \relative {
  s1  % 1 小節スキップします
  a'4 a a a
  s1  % 1 小節スキップします
  a4 a a a
}
accompaniment = \relative {
  d'4 d d d
  d4 d d d
  d4 d d d
  d4 d d d
}
words = \lyricmode { These words fol -- low the mel -- o -- dy }

\score {
  <<
    \new Staff = "music" {
      <<
        \new Voice = "melody" {
          \voiceOne
          \melody
        }
        \new Voice = "accompaniment" {
          \voiceTwo
          \accompaniment
        }
      >>
    }
    \new Lyrics \with { alignAboveContext = "music" }
    \lyricsto "melody" { \words }
  >>
}
@end lilypond


@node コンテキストのプラグインを変更する
@subsection コンテキストのプラグインを変更する
@translationof Modifying context plug-ins

@c TODO Should this be Modifying engravers or Modifying contexts?

記譜コンテキスト (@code{Score} や @code{Staff} のような) は@c
プロパティを保存するだけなく、@c
@q{エングラーバ} と呼ばれる記譜要素を作成するプラグインを保持します。@c
例えば、@code{Voice} コンテキストは @code{Note_head_engraver} を保持し、@c
@code{Staff} コンテキストは @code{Key_engraver} を保持します。

各プラグインについての説明は、
@ifhtml
@rinternals{Engravers and Performers}.
@end ifhtml
@ifnothtml
Internals Reference @expansion{} Translation @expansion{} Engravers.
@end ifnothtml
を参照してください。@c
@ifhtml
@rinternals{Contexts}
@end ifhtml
@ifnothtml
Internals Reference @expansion{} Translation @expansion{} Context.
@end ifnothtml
の中にある各コンテキストについての説明では、@c
そのコンテキストで使用されるエングラーバがリストアップされています。

これらのプラグインを入れ換えると有用な場合があります。@c
プラグインを入れ換えるには、新たに作成するコンテキストを
@code{\new} あるいは @code{\context} で開始し、@c
そのコンテキストを以下のように変更します:

@funindex \with
@funindex \consists
@funindex \remove

@example
\new @var{context} \with @{
  \consists @dots{}
  \consists @dots{}
  \remove @dots{}
  \remove @dots{}
  @emph{etc.}
@}
@{
  @emph{@dots{}music@dots{}}
@}
@end example

@noindent
ここで、@dots{} はエングラーバの名前になります。@c
ここで、@code{Staff} コンテキストから @code{Time_signature_engraver} と
@code{Clef_engraver} を削除する簡単な例を示します:

@lilypond[quote,verbatim]
<<
  \new Staff \relative {
    f'2 g
  }
  \new Staff \with {
     \remove Time_signature_engraver
     \remove Clef_engraver
  } \relative {
    f'2 g2
  }
>>
@end lilypond

2 番目の譜には、拍子記号と音部記号がありません。@c
この方法は、オブジェクトを不可視にするよりも乱暴な方法です。@c
なぜなら、譜全体に影響を与えるからです。@c
さらに、望む望まないに係わらず、この方法はスペースにも影響を与えます。@c
オブジェクトを消すもっと洗練された方法については、@c
@rlearning{オブジェクトの可視性と色} を参照してください。

次の例は、ある実用的な応用です。@c
通常、小節線と拍子記号は楽譜全体で同期されます。@c
これは @code{Timing_translator} と @code{Default_bar_line_engraver}
によって行われます。@c
このプラグインは拍子記号の管理や、小節内の配置の管理などを行います。@c
これらのエングラーバを @code{Score} コンテキストから
@code{Staff} コンテキストへ異動させることにより、@c
楽譜の各譜に独自の拍子記号を持たせることが可能になります。

@cindex polymetric score (多拍子の楽譜)
@cindex time signature, multiple (複数の拍子記号)

@lilypond[quote,verbatim]
\score {
  <<
    \new Staff \with {
      \consists Timing_translator
    }
    \relative {
        \time 3/4
        c''4 c c c c c
    }
  \new Staff \with {
    \consists Timing_translator
  }
  \relative {
      \time 2/4
      c''4 c c c c c
  }
>>
\layout {
  \context {
    \Score
    \remove Timing_translator
    }
  }
}
@end lilypond

@knownissues

エングラーバを指定する順序は、エングラーバが処理を行う順序です。@c
通常、エングラーバが指定される順序は問題にはなりません。@c
しかしながら、いくつかの特殊なケースでは、この順序が重要になります。@c
例えば、あるエングラーバがプロパティを記述して、@c
それを他のエングラーバが読む場合、あるいは、@c
あるエングラーバがグラフィカル オブジェクトを作成し、@c
それを他のエングラーバが処理しなければならない場合です。@c

以下の順序は重要です:

@itemize
@item
通常、@code{Bar_engraver} を最初にする必要があります。

@item
@code{New_fingering_engraver} を @code{Script_column_engraver} の前に@c
配置する必要があります。

@item
@code{Timing_translator} を @code{Bar_number_engraver} の前に配置する@c
必要があります。

@end itemize

@morerefs
インストールされているファイル:
@file{ly/engraver-init.ly}


@node コンテキストのデフォルト設定を変更する
@subsection コンテキストのデフォルト設定を変更する
@translationof Changing context default settings

@cindex default context property, changing (デフォルトのコンテキスト プロパティを変更する)
@cindex context property, changing default (デフォルトのコンテキスト プロパティを変更する)

@ref{Modifying properties} で説明したように、コンテキストとグラフィカル
オブジェクトのプロパティを @code{\set} コマンドや @code{\override}
コマンドで変更することができます。@c
これらのコマンドは音楽イベントを生成して、楽譜処理中にコマンドが出現する@c
ポイントで変更に効果を発揮させます。

対照的に、このセクションではコンテキストが作成された時点でコンテキストと@c
グラフィカル オブジェクトのプロパティの @emph{デフォルト} 値を変更する@c
方法を説明します。@c
これを行う方法は 2 つあります。@c
1 つはある特定のタイプの全コンテキストのデフォルト値を変更する方法で、@c
もう 1 つはただ 1 つのコンテキストのインスタンスのデフォルト値を変更する@c
方法です。

@menu
* 同じタイプの全コンテキストを変更する::
* 指定したコンテキストだけを変更する::
* 適用順序::
@end menu

@node 同じタイプの全コンテキストを変更する
@unnumberedsubsubsec 同じタイプの全コンテキストを変更する
@translationof Changing all contexts of the same type

@cindex @code{\context} in @code{\layout} block (@code{\layout} ブロックの中の @code{\context})
@funindex \context
@funindex \layout

@code{Score}, @code{Staff}, @code{Voice}, その他のコンテキストにおいて@c
デフォルトで使用される譜刻のためのコンテキスト設定は、@c
@code{\layout} ブロックの中の@c
@code{\context} ブロックで指定することができます。@c
@code{\layout} ブロックは、それを適用する @code{\score} ブロックの中で、@c
かつ、音楽表記の後に配置する必要があります。

譜刻ではなく MIDI 出力に関する設定をする場合は、@code{\midi} ブロックに別々に@c
指定する必要があります (@ref{Output definitions - blueprints for contexts}を@c
参照してください)。

@example
\layout @{
  \context @{
    \Voice
    [すべての Voice コンテキストのコンテキスト設定]
  @}
  \context @{
    \Staff
    [context settings for all Staff contexts]
  @}
@}
@end example

以下のタイプの設定を指定することができます:

@itemize
@item
@code{\override} コマンド -- コンテキスト名を省略します

@lilypond[quote,verbatim]
\score {
  \relative {
    a'4^"Thicker stems" a a a
    a4 a a\ff a
  }
  \layout {
    \context {
      \Staff
      \override Stem.thickness = #4.0
    }
  }
}
@end lilypond

@item
コンテキスト プロパティを直接設定します

@lilypond[quote,verbatim]
\score {
  \relative {
    a'4^"Smaller font" a a a
    a4 a a\ff a
  }
  \layout {
    \context {
      \Staff
      fontSize = #-4
    }
  }
}
@end lilypond

@item
@code{\dynamicUp} や @code{\accidentalStyle dodecaphonic} のような音楽@c
表記等、あらかじめ定義されているコマンド

@lilypond[quote,verbatim]
\score {
  \relative {
    a'4^"Dynamics above" a a a
    a4 a a\ff a
  }
  \layout {
    \context {
      \Voice
      \dynamicUp
    }
    \context {
      \Staff
      \accidentalStyle dodecaphonic
    }
  }
}
@end lilypond

@item
@code{\with} ブロックを有するユーザ定義変数 -- @code{\with} ブロックの@c
詳細は @ref{Changing just one specific context} を参照してください。

@lilypond[quote,verbatim]
StaffDefaults = \with {
  fontSize = #-4
}

\score {
  \new Staff {
    \relative {
      a'4^"Smaller font" a a a
      a4 a a a
    }
  }
  \layout {
    \context {
      \Staff
      \StaffDefaults
    }
  }
}
@end lilypond

@end itemize

プロパティ設定コマンドは、@code{\context} ブロックで囲まずに、@c
@code{\layout} ブロックの中に配置することができます。@c
そのような設定は、指定されたタイプの任意のコンテキストの開始時に@c
プロパティ設定コマンドをインクルードするのと等価です。@c
コンテキストを指定しない場合、@emph{すべての} 下位コンテキストに影響を@c
与えます -- @ref{Bottom-level contexts - voices} を参照してください。@c
@code{\layout} ブロックの中でのプロパティ設定コマンドの構文は、@c
音楽ストリームの中で同じコマンドを記述するのと同じです。

@lilypond[quote,verbatim]
\score {
  \new Staff {
    \relative {
      a'4^"Smaller font" a a a
      a4 a a a
    }
  }
  \layout {
    \accidentalStyle dodecaphonic
    \set fontSize = #-4
    \override Voice.Stem.thickness = #4.0
  }
}
@end lilypond


@node 指定したコンテキストだけを変更する
@unnumberedsubsubsec 指定したコンテキストだけを変更する
@translationof Changing just one specific context

@funindex \with

@code{\with} ブロックで指定したコンテキスト インスタンスのコンテキスト
プロパティだけを変更することができます。@c
他の全ての同じタイプのコンテキスト インスタンスは、LilyPond に組み込まれて@c
スコープ内の @code{\layout} ブロックによって変更されたデフォルト設定の@c
ままです。@c
@code{\with} ブロックは @code{\new} @var{context-type} コマンドの直後に@c
配置する必要があります:

@example
\new Staff \with @{ [このコンテキスト インスタンスだけに適用されるコンテキスト設定] @}
@{
  @dots{}
@}
@end example

あるいは、もし入力モードを指定するような簡略記法のコマンド (例えば
@code{\chordmode} の代わりに @code{\chords} を使うなど) を用いて音楽を入力@c
する場合、@code{\with} をそのようなコマンドのすぐ後に配置する必要があります:

@example
\chords \with @{ [この (暗黙的) コンテキスト インスタンスだけに適用されるコンテキスト設定] @}
@{
  @dots{}
@}
@end example

@noindent
このような記法によって作られる暗黙的なコンテキストが変更されます。
これは、同様な入力モードを指定する簡略記法のコマンドにも当てはまります
(@code{\drums}, @code{\figures})。@ref{Input modes} を参照してください。

@code{\with} ブロックで行われるコンテキストの変更は音楽の内部にあるため、@c
出力定義内での変更とは異なり、@c
@emph{全ての} 出力 (楽譜と MIDI の@emph{両方}) に影響が及びます。

以下のタイプの設定を指定することができます:

@itemize
@item
@code{\override} コマンド -- コンテキスト名を省略します

@lilypond[quote,verbatim]
\score {
  \new Staff {
    \new Voice
    \with {
      \override Stem.thickness = #4.0
    }
    {
      \relative {
        a'4^"Thick stems" a a a
        a4 a a a
      }
    }
  }
}
@end lilypond

@item
コンテキスト プロパティを直接設定します

@lilypond[quote,verbatim]
\score {
  <<
    \new Staff {
      \relative {
        a'4^"Default font" a a a
        a4 a a a
      }
    }
    \new Staff
    \with { fontSize = #-4 }
    {
      \relative {
        a'4^"Smaller font" a a a
        a4 a a a
      }
    }
  >>
}
@end lilypond

@item
@code{\dynamicUp} 等のあらかじめ定義されているコマンド

@lilypond[quote,verbatim]
\score {
  <<
    \new Staff {
      \new Voice {
        \relative {
          a'4^"Dynamics below" a a a
          a4 a a\ff a
        }
      }
    }
    \new Staff \with { \accidentalStyle dodecaphonic }
    {
      \new Voice \with { \dynamicUp }
      {
        \relative {
          a'4^"Dynamics above" a a a
          a4 a a\ff a
        }
      }
    }
  >>
}
@end lilypond

@end itemize

@morerefs
記譜法リファレンス:
@ref{Input modes}

@node 適用順序
@unnumberedsubsubsec 適用順序
@translationof Order of precedence

ある特定のタイミングで適用されるプロパティの値は以下のように決定されます:

@itemize
@item
入力ストリームの中の @code{\override} コマンドや @code{\set} コマンドが
ある場合、その値が用いられます。

@item
さもなければ、コンテキスト初期宣言の @code{\with} から取得したデフォルト値@c
が用いられます。

@item
さもなければ、@code{\layout} ブロックや @code{\midi} ブロックの中にある@c
直近で適切な @code{\context} ブロックから取得したデフォルト値が用いられます。

@item
さもなければ、LilyPond の組み込みデフォルト値が用いられます。
@end itemize

@morerefs
学習マニュアル:
@rlearning{Modifying context properties}

記譜法リファレンス:
@ref{Contexts explained},
@ref{Bottom-level contexts - voices},
@ref{The set command},
@ref{The override command},
@ref{layout ブロック}


@node 新しいコンテキストを定義する
@subsection 新しいコンテキストを定義する
@translationof Defining new contexts

@cindex context, defining new (新しいコンテキストを定義する)
@cindex engraver, including in context (エングラーバをコンテキストに含める)

@funindex \alias
@funindex \name
@funindex \type
@funindex \consists
@funindex \accepts
@funindex \denies

@code{Staff} や @code{Voice} のようなコンテキストは、@c
簡単なブロックの組み合わせで構成されています。
エングラーバ プラグインの組み合わせを変えることで、@c
新しいタイプのコンテキスを作成することができます。

次の例は、ゼロからタイプの異なる @code{Voice} コンテキストを作り上げる方法を@c
示しています。@c
このコンテキストは @code{Voice} コンテキストに似ていますが、@c
音符の代わりにスラッシュを譜の中央に譜刻します。@c
これはジャズで即興を表すのに使うことができます。

@lilypond[quote,ragged-right]
\layout { \context {
  \name ImproVoice
  \type Engraver_group
  \consists Note_heads_engraver
  \consists Rhythmic_column_engraver
  \consists Text_engraver
  \consists Pitch_squash_engraver
  squashedPosition = #0
  \override NoteHead.style = #'slash
  \hide Stem
  \alias Voice
}
\context { \Staff
  \accepts ImproVoice
}}

\relative {
  a'4 d8 bes8 \new ImproVoice { c4^"ad lib" c
   c4 c^"undress" c_"while playing :)" c }
  a1
}
@end lilypond


これらの設定は @code{\layout} ブロック内部の @code{\context} ブロック@c
の中で定義します:

@example
\layout @{
  \context @{
    @dots{}
  @}
@}
@end example

以下では、上記の例の @dots{} に入るべき入力について議論します。

最初に、新しいコンテキストの名前を定義する必要があります:

@example
\name ImproVoice
@end example

このコンテキストは @code{Voice} コンテキストに似せる必要があるため、@c
(既存の) @code{Voice} コンテキストで動作するコマンドを同じように動作させる@c
必要があります。@c
これは、新しいコンテキストに @code{Voice} のエイリアスを@c
与えることで実現できます。

@example
\alias Voice
@end example

このコンテキストは音符と指示テキストを譜刻しますので、@c
それらの機能を提供するエングラーバや、さらに同じタイミングで発生する@c
音符・符幹・休符を列としてグループ化するエングラーバを付加する必要があります:

@example
\consists Note_heads_engraver
\consists Text_engraver
\consists Rhythmic_column_engraver
@end example

符頭のスラッシュは譜の中央線上に配置される必要があります:

@example
\consists Pitch_squash_engraver
squashedPosition = #0
@end example

@code{Pitch_squash_engraver} は
(@code{Note_heads_engraver} によって作成される) 符頭を変更し、@c
符頭の垂直位置を @code{squashedPosition} にセットします
-- 今回は @code{0}、つまり中央線上です。

音符はスラッシュで、符幹を持ちません:

@example
\override NoteHead.style = #'slash
\hide Stem
@end example

これらのプラグインすべてがコンテキストの下で協調する必要があります。@c
コンテキストが協調するために用いるメカニズムは、コンテキストの @code{\type} を@c
宣言することで確立することができます。@code{\layout} ブロックの中では、@c
ほとんどのコンテキストは @code{Engraver_group} のタイプに属しています。@c
いくつかの特殊なコンテキストや、@code{\midi} ブロックの中では別のコンテキスト
タイプに属していることがあります。既存のコンテキスト定義をコピーし改変する@c
場合には、タイプについても継承されます。この例では定義を 1 から@c
作っているため、タイプを明示的に指定する必要があります:

@example
\type Engraver_group
@end example

まとめると、以下のようになります:

@example
\context @{
  \name ImproVoice
  \type Engraver_group
  \consists Note_heads_engraver
  \consists Text_engraver
  \consists Rhythmic_column_engraver
  \consists Pitch_squash_engraver
  squashedPosition = #0
  \override NoteHead.style = #'slash
  \hide Stem
  \alias Voice
@}
@end example

@funindex \accepts
コンテキストは階層を構成します。@c
通常の @code{Voice} コンテキストと同様に、@c
@code{ImproVoice} コンテキストを @code{Staff} コンテキストの中に@c
置く必要があります。@c
それゆえ、@code{Staff} の定義を @code{\accepts} コマンドで変更します:

@example
\context @{
  \Staff
  \accepts ImproVoice
@}
@end example

@funindex \inherit-acceptability
既存のコンテキスト定義を使い回す場合があるかもしれません。@c
その際、結果としてできるコンテキストは、元のコンテキストが使用できる@c
場所であればどこでも使用できると有用です。

@example
\layout @{
  @dots{}
  \inherit-acceptability @var{to} @var{from}
@}
@end example

@noindent
このようにすることで、@c
@var{from} を含めることのできるすべてのコンテキストが、@c
@var{to} のコンテキストも含めることができるようになります。例えば:

@example
\layout @{
  @dots{}
  \inherit-acceptability "ImproVoice" "Voice"
@}
@end example

@noindent
これは、@code{\accepts ImproVoice} を、@code{Staff} と @code{RhythmicStaff} の@c
定義に追加するのと同様の効果を示します。

@funindex \denies
@code{\accepts} の反対は @code{\denies} です。@c
これは既存のコンテキスト定義を再利用する場合に必要となります。

必要なパーツを @code{\layout} ブロックの中に置きます:

@example
\layout @{
  \context @{
    \name ImproVoice
    @dots{}
  @}
  \inherit-acceptability "ImproVoice" "Voice"
@}
@end example

それから、このサブセクションの最初にあった出力を入力します:

@example
\relative @{
  a'4 d8 bes8
  \new ImproVoice @{
    c4^"ad lib" c
    c4 c^"undress"
    c c_"while playing :)"
  @}
  a1
@}
@end example

この例を完成させるには、コンテキストの階層に影響する変更が @code{\midi} 
ブロックでも同様に記述される必要があります。そうすることで、MIDI 出力に@c
おいてもコンテキスト間の関係が同様に定義されます。

@morerefs

内部リファレンス:
@rinternals{Note_heads_engraver},
@rinternals{Text_engraver},
@rinternals{Rhythmic_column_engraver},
@rinternals{Pitch_squash_engraver}


@node コンテキストの配置順序
@subsection コンテキストの配置順序
@translationof Context layout order

@cindex context, layout order (コンテキストの配置順序)
@funindex \accepts
@funindex \denies

通常、コンテキストは入力ファイルの中で記述した順に楽譜の段の上から下に@c
配置されます。@c
コンテキストがネストされている場合、外側のコンテキストは入力ファイルの@c
中で指定されたコンテキストを内側に保持して、内側のコンテキストは外側の@c
コンテキストの @qq{accepts} リストに含まれます。@c
ネストされたコンテキストのうち外側のコンテキストの @qq{accepts} リスト@c
に含まれないものは、ネストされずに外側のコンテキストの下に再配置されます。

コンテキストの @qq{accepts} リストを @code{\accepts} コマンドや
@code{\denies} コマンドで変更することができます。@c
@code{\accepts} はコンテキストを @qq{accepts} リストに追加して、@c
@code{\denies} は @qq{accepts} リストからコンテキストを削除します。@c

例えば、角括弧でグループ化された譜表は通常、波括弧でグループ化され小節線が@c
繋げられる譜表グループの中にあることは通常見られず、デフォルトで 
@code{GrandStaff} は内部に @code{StaffGroup} を含めることができません。

@lilypond[verbatim,quote]
\score {
  \new GrandStaff <<
    \new StaffGroup <<
      \new Staff { c'1 }
      \new Staff { d'1 }
    >>
    \new Staff { \set Staff.instrumentName = bottom f'1 }
  >>
}
@end lilypond

しかし、@code{\accepts} コマンドを使うことで、@code{StaffGroup} を@c
@code{GrandStaff} コンテキストの中に含めることができます:

@lilypond[verbatim,quote]
\score {
  \new GrandStaff <<
    \new StaffGroup <<
      \new Staff { c'1 }
      \new Staff { d'1 }
    >>
    \new Staff { \set Staff.instrumentName = bottom f'1 }
  >>
  \layout {
    \context {
      \GrandStaff
      \accepts StaffGroup
    }
  }
}
@end lilypond


@code{\denies} は主に、他のコンテキストをベースに新しいコンテキストを@c
作成した時に、中にネストするコンテキストを変更するために用いられます。@c
例えば、@code{VaticanaStaff} コンテキストは @code{Staff} コンテキストを@c
ベースにしていますが、@qq{accepts} リストでは @code{Voice} コンテキスト@c
の代わりに @code{VaticanaVoice} コンテキストを保持しています。

@cindex context, implicit (暗黙的なコンテキスト)
@cindex implicit context (暗黙的なコンテキスト)
@funindex \defaultchild

コンテキストに保持されるべきコマンドが出現して、それを保持するための@c
適切なコンテキストが存在しない場合、コンテキストが暗黙的に作成される@c
ということに注意してください。@c

コンテキスト定義の中で、暗黙的に作り出されるサブコンテキストの種類は
@code{\defaultchild} により指定されます。@c
多くの音楽イベントは最下位 (@samp{Bottom}) のコンテキストが必要です。@c
そのようなイベントが現れた場合、@samp{defaultchild} 設定を持たない@c
コンテキストに到達するまで、再帰的にサブコンテキストが作られます。

暗黙的にコンテキストが生成されることによって、@c
予期しない譜や楽譜が生み出される可能性があります。@code{\new} で明示的に@c
コンテキストを作ることでこれらの問題を回避できます。

@funindex alignAboveContext
@funindex alignBelowContext

短い期間、あるコンテキストを存在させる必要がある場合があります。@c
オッシアの譜コンテキストが良い例です。@c
通常、これは主音楽の対応するセクションと並列に、適切な場所でコンテキスト@c
定義を行うことで実現します。@c
デフォルトでは、一時コンテキストは既存のすべてのコンテキストの下に配置@c
されます。@c
@qq{main} というコンテキストの上に配置し直すには以下のようにします:

@example
\new Staff \with @{ alignAboveContext = "main" @}
@end example

@code{ChoirStaff} のような複数の譜のレイアウトで一時的な歌詞を配置する場合
-- 例えば、繰り返しセクションに 2 番目の歌詞を追加する場合 --
にも同様な状況が発生します。@c
デフォルトでは、一時的な歌詞は下段の譜の下に配置されます。@c
一時的な歌詞コンテキストを @code{alignBelowContext} で定義することにより、@c
1 番目の歌詞を保持する (名前付きの) 歌詞コンテキストの下に配置することが@c
できます。

一時コンテキストを再配置する例は他にもあります
-- @rlearning{Nesting music expressions}、+@ref{Modifying single staves}、@c
それに @ref{Techniques specific to lyrics} を参照してください。

@morerefs
学習マニュアル:
@rlearning{Nesting music expressions}

記譜法リファレンス:
@ref{Modifying single staves},
@ref{Techniques specific to lyrics}

アプリケーション使用方法:
@rprogram{An extra staff appears}

インストールされているファイル:
@file{ly/engraver-init.ly}


@node 内部リファレンスの説明
@section 内部リファレンスの説明
@translationof Explaining the Internals Reference


@menu
* 内部リファレンスを使いこなす::
* レイアウト インターフェイス::
* グラフィカル オブジェクト プロパティを決定する::
* 命名規約::
@end menu

@node 内部リファレンスを使いこなす
@subsection 内部リファレンスを使いこなす
@translationof Navigating the program reference

@c TODO remove this (it's in the LM)
@c Replace with more factual directions

以下の譜面の運指記号を移動させたいとします:

@lilypond[quote,fragment,verbatim]
c''-2
@end lilypond

運指指示のドキュメント (@ref{運指の指示}) を見ると、@c
以下のようなセクションがあることに気付くはずです:

@quotation
@strong{参照}

内部リファレンス: @rinternals{Fingering}

@end quotation


@c  outdated info; probably will delete.
@ignore
This fragment points to two parts of the program reference: a page
on @code{FingeringEvent} and one on @code{Fingering}.

The page on @code{FingeringEvent} describes the properties of the music
expression for the input @w{@code{-2}}.  The page contains many links
forward.  For example, it says

@quotation
Accepted by: @rinternals{Fingering_engraver},
@end quotation

@noindent
That link brings us to the documentation for the Engraver, the
plug-in, which says

@quotation
This engraver creates the following layout objects: @rinternals{Fingering}.
@end quotation

In other words, once the @code{FingeringEvent}s are interpreted, the
@code{Fingering_engraver} plug-in will process them.
@end ignore

@ignore
@c  I can't figure out what this is supposed to mean.  -gp

The @code{Fingering_engraver} is also listed to create
@rinternals{Fingering} objects,

@c  old info?  it doesn't make any sense to me with our current docs.
This is also the
second bit of information listed under @b{See also} in the Notation
manual.
@end ignore

@ifnothtml
内部リファレンスは HTML ドキュメント形式で入手可能です。@c
内部リファレンスは、オンラインか HTML ドキュメントをダウンロードするかして、@c
HTML 形式で読むことを強く推奨します。@c
PDF マニュアルを使用していると、@c
このセクションを理解するのはずっと困難になります。@c
(訳者: 日本語では PDF 形式での提供はありません。)
@end ifnothtml

@rinternals{Fingering} へのリンクを辿ってください。@c
ページの先頭に、以下のような記述があります:

@quotation
Fingering objects are created by: @rinternals{Fingering_engraver} and
@rinternals{New_fingering_engraver}.
@end quotation

内部リファレンスの中にある関連リンクを辿っていくことで、@c
プログラム内部の情報フローを追っていくことができます:

@itemize

@item @rinternals{Fingering}:
@rinternals{Fingering} objects are created by:
@rinternals{Fingering_engraver}

(@rinternals{Fingering}:
@rinternals{Fingering} オブジェクトを作成するのは:
@rinternals{Fingering_engraver})


@item @rinternals{Fingering_engraver}:
Music types accepted:
@rinternals{fingering-event}

(@rinternals{Fingering_engraver}:
受け取る音楽タイプは: @rinternals{fingering-event})

@item @rinternals{fingering-event}:
Music event type @code{fingering-event} is in
Music expressions named @rinternals{FingeringEvent}

(@rinternals{fingering-event}:
音楽イベント タイプ @code{fingering-event} は
@rinternals{FingeringEvent} という名前の音楽表記の中にあります)
@end itemize

このパスは、プログラム内部での情報フローとは逆向きです:
出力からスタートして、入力イベントで終わっています。@c
入力イベントからスタートして、情報フローを読み進め、@c
最後は出力オブジェクトに辿り着くこともできます。

内部リファレンスを通常のドキュメントのように読むこともできます。@c
内部リファレンスに含まれる章は、
@ifhtml
@rinternals{Music definitions},
@end ifhtml
@ifnothtml
@code{Music definitions},
@end ifnothtml
@rinternals{Translation}, それに @rinternals{Backend} です。
各章は、使用されているすべての定義と調整可能なすべてのプロパティを@c
リストアップしています。


@node レイアウト インターフェイス
@subsection レイアウト インターフェイス
@translationof Layout interfaces

@cindex interface, layout (レイアウト インターフェイス)
@cindex layout interface (レイアウト インターフェイス)
@cindex grob (グラフィカル オブジェクト)

前のセクションで見た HTML ページには、@c
@rinternals{Fingering} と呼ばれるレイアウト オブジェクトについての@c
記述がありました。@c
そのようなオブジェクトは楽譜で記号となります。@c
レイアウト オブジェクトは (太さや向きのような) 数値を保持する@c
プロパティを持っていますが、@c
関連オブジェクトへのポインタも持っています。@c
レイアウト オブジェクトは @emph{Grob}
-- これはグラフィカル オブジェクトを縮めたものです --
とも呼ばれます。@c
Grob についての詳細は、@rinternals{grob-interface} を参照してください。

@code{Fingering} のページは、@c
@code{Fingering} オブジェクトの定義をリストアップしています。@c
例えば、このページには以下のような記述があります:

@quotation
@code{padding} (dimension, in staff space):

@code{0.5}
@end quotation

@noindent
これは、この運指記号は少なくとも符頭の 0.5 倍の距離を保つということを意味します。


各レイアウト オブジェクトは、記譜要素あるいは写植要素としての機能を@c
いくつか持つ場合があります。@c
例えば、@code{Fingering} オブジェクトは以下の側面を持っています:

@itemize
@item
Its size is independent of the horizontal spacing, unlike slurs or beams.

(このオブジェクトのサイズは、スラーや連桁と異なり、@c
水平方向のスペースとは無関係です)

@item
It is a piece of text.  Granted, it is usually a very short text.

(このオブジェクトはテキストです。通常、これは非常に短いテキストです。)

@item
That piece of text is typeset with a font, unlike slurs or beams.

(このテキストは、スラーや連桁と異なり、フォントで写植されます。)

@item
Horizontally, the center of the symbol should be aligned to the
center of the note head.

(水平方向では、この記号の中心は符頭の中心に揃えられます。)

@item
Vertically, the symbol is placed next to the note and the staff.

(垂直方向では、この記号は音符や譜の近く配置されます。)

@item
The vertical position is also coordinated with other superscript
and subscript symbols.

(また、垂直方向の位置は、他の上付き記号や下付き記号との調整によって決まります。)
@end itemize

これらの側面はそれぞれ、いわゆる @emph{インターフェイス}
として捉えられます。@c
それらは、@rinternals{Fingering} ページの最下部でリストアップされています。

@quotation
This object supports the following interfaces:

(このオブジェクトは以下のインターフェイスをサポートします:)

@rinternals{item-interface},
@rinternals{self-alignment-interface},
@rinternals{side-position-interface}, @rinternals{text-interface},
@rinternals{text-script-interface}, @rinternals{font-interface},
@rinternals{finger-interface}, and @rinternals{grob-interface}.
@end quotation

リンクのいずれかをクリックすると、@c
それぞれのオブジェクト インターフェイスのページに行くことができます。@c
各インターフェイスはいくつかのプロパティを持ちます。@c
それらプロパティの中には、ユーザにとって役に立たないもの
(@q{内部プロパティ}) もありますが、それ以外は変更可能です。

これまで @code{Fingering} オブジェクトについて話してきましたが、@c
これは実際にはそれほど多くのことをしているわけではありません。@c
初期化ファイル (@rlearning{その他の情報源} を参照してください)
@file{scm/define-grobs.scm} がこの @q{オブジェクト} の本質を示しています:

@example
(Fingering
  . ((padding . 0.5)
     (avoid-slur . around)
     (slur-padding . 0.2)
     (staff-padding . 0.5)
     (self-alignment-X . 0)
     (self-alignment-Y . 0)
     (script-priority . 100)
     (stencil . ,ly:text-interface::print)
     (direction . ,ly:script-interface::calc-direction)
     (font-encoding . fetaText)
     (font-size . -5) 		; don't overlap when next to heads.
     (meta . ((class . Item)
     (interfaces . (finger-interface
                    font-interface
                    text-script-interface
                    text-interface
                    side-position-interface
                    self-alignment-interface
                    item-interface))))))
@end example

@noindent
見て取ることができるように、@c
@code{Fingering} オブジェクトは変数設定の塊に過ぎず、@c
内部リファレンスの中にある Web ページは、@c
この定義から直接生成されたに過ぎません。


@node グラフィカル オブジェクト プロパティを決定する
@subsection グラフィカル オブジェクト プロパティを決定する
@translationof Determining the grob property

@c TODO remove this (it's in the LM)
@c Replace with more factual directions

以下の @b{2} の位置を変更しようとしていたことを思い出してください:

@lilypond[quote,fragment,verbatim]
c''-2
@end lilypond

垂直方向で見て、@b{2} は元の音符の隣に配置されるのですから、@c
この配置に関連するインターフェイスに干渉する必要があります。@c
これは @code{side-position-interface} を用いて行います。@c
このインターフェイスについてのページには、以下のように記述されています:

@quotation
@code{side-position-interface}

Position a victim object (this one) next to other objects (the
support).  The property @code{direction} signifies where to put the
victim object relative to the support (left or right, up or down?)

(対象オブジェクトを他のオブジェクト (サポート オブジェクト)
の隣に配置します。@c
このプロパティ @code{direction} は、@c
対象オブジェクトをどこに配置するかを@c
サポート オブジェクトからの相対位置で示します
(左あるいは右、上あるいは下？))
@end quotation

@cindex padding
@noindent
この記述の下に、以下のような変数 @code{padding} についての記述があります:

@quotation
@table @code
@item padding
(dimension, in staff space)
(譜スペースを単位とする距離)

Add this much extra space between objects that are next to each other.
(隣り合うオブジェクトの間にスペースを付け加えます)
@end table
@end quotation

@code{padding} の値を増やすことで、@c
運指記号を符頭から離すことができます。@c
以下のコマンドは、音符と運指記号の間に @qq{3 譜スペース}分の距離を加えます:

@example
\once \override Voice.Fingering.padding = #3
@end example

パディングを運指記号オブジェクトが作成される前に挿入すると、@c
以下のようになります:

@lilypond[quote,fragment,verbatim]
\once \override Voice.Fingering.padding = #3
c''-2
@end lilypond

このケースでは、調整されるコンテキストは @code{Voice} です。@c
@rinternals{Fingering_engraver} プラグインを参照してください。@c
以下のように説明されています:

@quotation
Fingering_engraver is part of contexts: @dots{} @rinternals{Voice}

(Fingering_engraver は次のコンテキストの一部です: @dots{} @rinternals{Voice})
@end quotation


@node 命名規約
@subsection 命名規約
@translationof Naming conventions

内部リファレンスについて他に説明しておくべき事柄として、@c
さまざまな命名規約についての概要があります:

@itemize
@item Scheme 関数: 小文字の単語をハイフンでつなぎます
(1 単語の名前も含みます) -- 例: lowercase-with-hyphens
@item LilyPond 独自の Scheme 関数: Scheme スタイルの先頭に @code{ly:} を付けます
-- 例: ly:plus-scheme-style
@item 音楽イベント、音楽クラス、それに音楽プロパティ: Scheme 関数と同じスタイルです
-- 例: as-scheme-functions
@item グラフィカル オブジェクト インターフェイス: Scheme 関数と同じスタイルです
-- 例: scheme-style
@item バックエンド プロパティ: Scheme 関数と同じスタイルです (が、X と Y があります！)
@item コンテキスト (それに、音楽表記とグラフィカル オブジェクト):
大文字で始まる単語、あるいはそれらをつなげます
-- 例: Capitalized, CamelCase
@item コンテキスト プロパティ:
小文字で始まる単語に、大文字で始まる単語をつなげます
-- 例: lowercaseFollowedByCamelCase
@item エングラーバ:
大文字で始まる単語に、小文字で始まる単語をアンダスコアでつなげます
-- 例: Capitalized_followed_by_lowercase_and_with_underscores
@end itemize

このような疑問があります:
@itemize
@item 命名規約のうち、慣習なのはどれで、規則なのはどれか？
@item 命名規約のうち、どれが基本言語の規則で、どれが LilyPond 特有の規則なのか？
@end itemize


@node プロパティを変更する
@section プロパティを変更する
@translationof Modifying properties

@c TODO change the menu and subsection node names to use
@c backslash once the new macro to handle the refs
@c is available.  Need to find and change all refs at
@c the same time. -td

@menu
* プロパティ変更の概要::
* set コマンド::
* override コマンド::
* tweak コマンド::
* set 対 override::
* offset コマンド::
* 連想配列を変更する::
@end menu


@node プロパティ変更の概要
@subsection プロパティ変更の概要
@translationof Overview of modifying properties

各コンテキストは、ある特定のタイプのグラフィカル オブジェクトを作成することに@c
ついて責任を持ちます。@c
それらのオブジェクトを表示するために使用される設定も、@c
コンテキストによって保存されます。@c
それらの設定を変更することにより、オブジェクトの見た目を変えることができます。

コンテキストに保存されるプロパティには 2 種類あります:
コンテキスト プロパティとグラフィカル オブジェクト プロパティです。@c
コンテキスト プロパティは、コンテキスト全体に適用され、@c
コンテキスト自体をどのように表示するかを制御します。@c
対照的に、グラフィカル オブジェクト プロパティは、コンテキストの中に表示される@c
ある特定のタイプのグラフィカル オブジェクトに適用されます。

@code{\set} コマンドと @code{\unset} コマンドは、@c
コンテキスト プロパティの値を変更するために使用されます。@c
@code{\override} コマンドと @code{\revert} コマンドは、@c
グラフィカル オブジェクト プロパティの値を変更するために使用されます。

@ignore
The syntax for this is

@example
\override @var{context}.@var{name} #'@var{property} = #@var{value}
@end example

Here @var{name} is the name of a graphical object, like
@code{Stem} or @code{NoteHead}, and @var{property} is an internal
variable of the formatting system (@q{grob property} or @q{layout
property}).  The latter is a symbol, so it must be quoted.  The
subsection @ref{Modifying properties}, explains what to fill in
for @var{name}, @var{property}, and @var{value}.  Here we only
discuss the functionality of this command.

The command

@verbatim
\override Staff.Stem.thickness = #4.0
@end verbatim

@noindent
makes stems thicker (the default is 1.3, with staff line thickness as a
unit).  Since the command specifies @code{Staff} as context, it only
applies to the current staff.  Other staves will keep their normal
appearance.  Here we see the command in action:

@lilypond[quote,fragment,verbatim]
c''4
\override Staff.Stem.thickness = #4.0
c''4
c''4
c''4
@end lilypond

The @code{\override} command changes the definition of the @code{Stem}
within the current @code{Staff}.  After the command is interpreted
all stems are thickened.

Analogous to @code{\set}, the @var{context} argument may be left out,
causing the default context @code{Voice} to be used.  Adding
@code{\once} applies the change during one timestep only.

@lilypond[quote,fragment,verbatim]
c''4
\once \override Stem.thickness = #4.0
c''4
c''4
@end lilypond

The @code{\override} must be done before the object is
started.  Therefore, when altering @emph{Spanner} objects such as slurs
or beams, the @code{\override} command must be executed at the moment
when the object is created.  In this example,

@lilypond[quote,fragment,verbatim]
\override Slur.thickness = #3.0
c''8[( c''
\override Beam.beam-thickness = #0.6
c''8 c''])
@end lilypond

@noindent
the slur is fatter but the beam is not.  This is because the command for
@code{Beam} comes after the Beam is started, so it has no effect.

Analogous to @code{\unset}, the @code{\revert} command for a context
undoes an @code{\override} command; like with @code{\unset}, it only
affects settings that were made in the same context.  In other words, the
@code{\revert} in the next example does not do anything.

@example
\override Voice.Stem.thickness = #4.0
\revert Staff.Stem.thickness
@end example

Some tweakable options are called @q{subproperties} and reside inside
properties.  To tweak those, use commands of the form

@c leave this as a long long
@example
\override @var{context}.@var{name} #'@var{property} #'@var{subproperty} = #@var{value}
@end example

@noindent
such as

@example
\override Stem.details.beamed-lengths = #'(4 4 3)
@end example

@end ignore

@morerefs
内部リファレンス:
@rinternals{Backend},
@rinternals{All layout objects},
@rinternals{OverrideProperty},
@rinternals{RevertProperty},
@rinternals{PropertySet}


@knownissues

バックエンドはオブジェクト プロパティのタイプ チェックを@c
それほど厳密には行いません。@c
Scheme 値の循環参照は、ハング アップまたはクラッシュ、@c
あるいは両方を引き起こす可能性があります。



@node set コマンド
@subsection @code{\set} コマンド
@translationof The set command

@cindex property (プロパティ)
@funindex \set
@cindex changing property (プロパティを変更する)

各コンテキストは @emph{プロパティ} の集合を持ちます。@c
プロパティとは、コンテキストの中に保持されている変数です。@c
コンテキスト プロパティは、@code{\set} コマンドによって変更されます。@c
@code{\set} コマンドは以下のような構文を持ちます:

@example
\set @var{context}.@var{property} = #@var{value}
@end example

@var{value} は Scheme オブジェクトですので、@c
@code{#} 文字を前に置く必要があります。

通常、コンテキスト プロパティの名前は、@c
小文字で始まる単語に大文字で始まる単語をつなげたものです。@c
これらはたいてい音楽から記譜への翻訳を制御します
-- 例えば、@code{localAlterations} (臨時記号を表示するかどうかを決定します)
や、@code{measurePosition} (小節線を表示するタイミングを決定します) です。@c
コンテキスト プロパティは、楽曲の解釈をしている間、@c
ずっと値を変更しておくことができます。@c
@code{measurePosition} がその良い例です。@c
コンテキスト プロパティは @code{\set} で変更されます。

例えば、コンテキスト プロパティ @code{skipBars} が
@code{#t} にセットされていれば、@c
複小節休符は 1 つの小節に統合されます
(@ref{Compressing empty measures} で説明されています):

@lilypond[quote,fragment,verbatim]
R1*2
\set Score.skipBars = ##t
R1*2
@end lilypond

@var{context} 引数が省略されている場合、@c
プロパティはカレントの最下位のコンテキストにセットされます
(一般に、@code{ChordNames}, @code{Voice}, @code{TabVoice},
あるいは @code{Lyrics} です)。

@lilypond[quote,fragment,verbatim]
\set Score.autoBeaming = ##f
\relative {
  e''8 e e e
  \set autoBeaming = ##t
  e8 e e e
} \\
\relative {
  c''8 c c c c8 c c c
}
@end lilypond

変更は @q{オンザフライ} (その場、その時々) で適用されるため、@c
設定 @code{\set autoBeaming = ##t} は 2 番目の 8 分音符グループだけに@c
効果を持ちます。

最下位コンテキストが常に変更しようとしているプロパティを持っているとは@c
限らないということに注意してください
-- 例えば、@code{skipBars} プロパティをデフォルトの最下位コンテキスト
(この場合は、@code{Voice} です) にセットしようと試みても、効果はありません。@c
なぜなら、@code{skipBars} は @code{Score} コンテキストのプロパティだからです。

@lilypond[quote,fragment,verbatim]
R1*2
\set skipBars = ##t
R1*2
@end lilypond

コンテキストは階層構造をとるため、音楽表記を囲っているコンテキスト
-- 例えば、@code{Staff} -- が指定された場合、@c
変更は現在の @code{Staff} の中にあるすべての @code{Voice} に適用されます。

@funindex \unset

@code{\unset} コマンド:

@example
\unset @var{context}.@var{property}
@end example

@noindent
は、@var{context} から @var{property} の定義を削除するために使用されます。@c
このコマンドは、@var{context} の中にセットされた場合にのみ、定義を削除します。@c
音楽表記を囲っているコンテキストにセットされたプロパティは、@c
囲まれているコンテキストの中にある @code{\unset} では変更されません:

@lilypond[quote,fragment,verbatim]
\set Score.autoBeaming = ##t
\relative {
  \unset autoBeaming
  e''8 e e e
  \unset Score.autoBeaming
  e8 e e e
} \\
\relative {
  c''8 c c c c8 c c c
}
@end lilypond

@code{\set} と同様に、
最下位コンテキストに対しては @var{context} 引数を指定する必要はありません。@c
ですから、以下の 2 つの記述:

@example
\set Voice.autoBeaming = ##t
\set autoBeaming = ##t
@end example

@noindent
は、カレントの最下位コンテキストが @code{Voice} であれば、等価です。


@funindex \once
@code{\set} や @code{\unset} の前に @code{\once} を置くと、@c
その設定は単一の時間ステップにだけ適用されます:

@lilypond[quote,fragment,verbatim]
c''4
\once \set fontSize = #4.7
c''4
c''4
@end lilypond

利用可能なすべてのコンテキスト プロパティについての完全な記述は、@c
内部リファレンスにあります。@c
以下を参照してください:
@ifhtml
@rinternals{Tunable context properties}.
@end ifhtml
@ifnothtml
Translation @expansion{} Tunable context properties.
@end ifnothtml

@morerefs
内部リファレンス:
@rinternals{Tunable context properties}


@node override コマンド
@subsection @code{\override} コマンド
@translationof The override command

@cindex grob property (グラフィカル オブジェクト プロパティ)
@cindex property, grob (グラフィカル オブジェクト プロパティ)
@funindex \override

特殊なタイプのコンテキスト プロパティがあります:
グラフィカル オブジェクト記述です。@c
グラフィカル オブジェクト記述には @code{StudlyCaps} という名前
(大文字で始まります) が付けられています。@c
これらは、関連リストとして、ある特定の種類のグラフィカル オブジェクト用の
@q{デフォルト設定} を保持します。@c
各グラフィカル オブジェクト記述の設定を調べるには、@c
@file{scm/define-grobs.scm} を参照してください。@c
各グラフィカル オブジェクト記述は @code{\override} を用いて変更します。

@code{\override} コマンドの構文は以下の通りです:

@example
\override [@var{context}.]@var{GrobName}.@var{property} = #@var{value}
@end example

例えば、@code{Stem} オブジェクトの @code{thickness} プロパティを@c
オーバライドすることによって、符幹の太さを太くすることができます:

@lilypond[quote,fragment,verbatim]
c''4 c''
\override Voice.Stem.thickness = #3.0
c''4 c''
@end lilypond

@code{\override} でコンテキストが指定されていない場合、その下にある@c
コンテキストに適用されます:

@lilypond[quote,fragment,verbatim]
\override Staff.Stem.thickness = #3.0
<<
  \relative {
    e''4 e
    \override Stem.thickness = #0.5
    e4 e
  } \\
  \relative {
    c''4 c c c
  }
>>
@end lilypond

調整可能なオプションには @q{サブプロパティ} があり、これはプロパティの@c
内部に存在します。@c
これを調整するには、以下のような形式のコマンドを用います:

@example
\override Stem.details.beamed-lengths = #'(4 4 3)
@end example

また、スパナの端を変更するには、以下のようにします:

@example
\override TextSpanner.bound-details.left.text = "left text"
\override TextSpanner.bound-details.right.text = "right text"
@end example

@funindex \revert
@cindex reverting override (オーバライドを元に戻す)
@cindex override, reverting (オーバライドを元に戻す)

@code{\override} の効果は、@code{\revert} によって元に戻すことができます。

@code{\revert} の構文は以下の通りです:

@example
\revert [@var{context}.]@var{GrobName}.@var{property}
@end example

例を示します:

@lilypond[quote,verbatim]
\relative {
  c''4
  \override Voice.Stem.thickness = #3.0
  c4 c
  \revert Voice.Stem.thickness
  c4
}
@end lilypond

@code{\override} と @code{\revert} の効果は、@c
その時点から影響を受けるコンテキストの中にある@c
すべてのグラフィカル オブジェクトに適用されます:

@lilypond[quote,verbatim]
<<
  \relative {
    e''4
    \override Staff.Stem.thickness = #3.0
    e4 e e
  } \\
  \relative {
    c''4 c c
    \revert Staff.Stem.thickness
    c4
  }
>>
@end lilypond

@funindex \once
@cindex overriding for only one moment (一時的にオーバライドする)

@code{\once} を @code{\override} や @code{\revert} と共に用いることで、@c
カレントの時間ステップだけに効果を与えることができます:

@lilypond[quote,verbatim]
<<
  \relative c {
    \override Stem.thickness = #3.0
    e''4 e e e
  } \\
  \relative {
    c''4
    \once \override Stem.thickness = #3.0
    c4 c c
  }
>>
@end lilypond


@ignore
Commands which change output generally look like

@example
\override Voice.Stem.thickness = #3.0
@end example

@noindent
To construct this tweak we must determine these bits of information:

@itemize
@item the context: here @code{Voice}.
@item the layout object: here @code{Stem}.
@item the layout property: here @code{thickness}.
@item a sensible value: here @code{3.0}.
@end itemize

@cindex internal documentation
@cindex finding graphical object
@cindex graphical object description
@cindex tweaking
@funindex \override
@cindex internal documentation

For many properties, regardless of the data type of the property, setting the
property to false ( @code{##f} ) will result in turning it off, causing
LilyPond to ignore that property entirely.  This is particularly useful for
turning off grob properties which may otherwise be causing problems.

We demonstrate how to glean this information from the notation manual
and the program reference.
@end ignore

@morerefs
内部リファレンス:
@rinternals{Backend}


@node tweak コマンド
@subsection @code{\tweak} コマンド
@translationof The tweak command

@funindex \tweak
@cindex tweaking (調整)

@code{\tweak} を用いたグラフィカル オブジェクト プロパティの変更は、@c
コンテキストの中にあるすべてのグラフィカル オブジェクトに適用されます。@c
しかしながら、@c
影響を受けるコンテキストの中にあるすべてのグラフィカル オブジェクトではなく、@c
1 つのグラフィカル オブジェクトだけに変更を適用したい場合もあります。@c
そうするには、@code{\tweak} コマンドを用います。@c
@code{\tweak} コマンドは以下のような構文を持ちます:

@example
\tweak [@var{layout-object}.]@var{grob-property} @var{value}
@end example

@code{layout-object} の指定はオプションです。@c
@code{\tweak} コマンドは、音楽の流れの中で
@code{value} のすぐ後に現れる音楽オブジェクトに変更を適用します。

@ignore
In some cases, it is possible to take a short-cut for tuning
graphical objects.  For objects that are created directly from
an item in the input file, you can use the @code{\tweak} command.
For example:

@lilypond[verbatim,quote]
\relative {
  < c''
    \tweak color #red
    d
    g
    \tweak duration-log #1
    a
  > 4
  -\tweak padding #8
  -^
}
@end lilypond



The main use of the @code{\tweak} command is to modify just
one of a number of notation elements which start at the same musical
moment, like the notes of a chord, or tuplet brackets which start
at the same time.

The @code{\tweak} command sets a property in the following object
directly, without requiring the grob name or context to be
specified.  For this to work, it is necessary for the @code{\tweak}
command to remain immediately adjacent to the object to which it is
to apply after the input file has been converted to a music stream.
This is often not the case, as many additional elements are inserted
into the music stream implicitly.  For example, when a note which is
not part of a chord is processed, LilyPond implicitly inserts a
@code{ChordEvent} event before the note, so separating the tweak
from the note.  However, if chord symbols are placed round the
tweak and the note, the @code{\tweak} command comes after the
@code{ChordEvent} in the music stream, so remaining adjacent to the
note, and able to modify it.

So, this works:

@lilypond[verbatim,fragment,quote]
<\tweak color #red c''>4
@end lilypond

@noindent
but this does not:

@lilypond[verbatim,fragment,quote]
\tweak color #red c''4
@end lilypond

@end ignore

調整コマンドの構文と使用方法についての紹介は、@c
@rlearning{調整手段} を参照してください。

同じようなオブジェクトがいくつか、同じ音楽タイミングで配置されている場合、@c
@code{\override} コマンドでそれらの 1 つだけを変更することはできません
-- @code{\tweak} コマンドを用いる必要があります。@c
同じ音楽タイミングで複数出現する可能性があるオブジェクトには、@c
以下のようなものがあります:

@c TODO expand to include any further uses of \tweak
@itemize
@item 和音の中にある音符の符頭
@item 1 つの音符に付けられるアーティキュレーション記号
@item 和音の中にある音符の間に付けられるタイ
@item 同時に始まる連符の囲み
@end itemize

@c TODO add examples of these

@cindex chord, modifying one note in (和音の中にある音符の 1 つを変更する)

以下の例では、和音の中にある符頭の 1 つの色を変更し、@c
さらに他の符頭のタイプを変更しています:

@lilypond[verbatim,fragment,quote]
< c''
  \tweak color #red
  d''
  g''
  \tweak duration-log #1
  a''
> 4
@end lilypond

@code{\tweak} を用いて、スラーを変更することができます:

@lilypond[verbatim,quote]
\relative { c'-\tweak thickness #5 ( d e f) }
@end lilypond


@code{\tweak} コマンドが機能するためには、@c
入力ファイルが音楽の流れに変換されたときに、@c
@code{\tweak} コマンドのすぐ後に@c
変更が適用されるオブジェクトが配置されている必要があります。
和音全体に対する調整は何の効果もありません。@c
なぜなら、和音の音楽イベントはコンテナと機能するだけで、すべてのレイアウト
オブジェクトは @code{EventChord} の内部にあるイベントによって作成される@c
からです:

@lilypond[verbatim,fragment,quote]
\tweak color #red c''4
\tweak color #red <c'' e''>4
<\tweak color #red c'' e''>4
@end lilypond

単純な @code{\tweak} コマンドでは入力から直接作成されないオブジェクトを@c
変更することはできません。@c
特に、符幹、自動連桁、それに臨時記号には効果を持ちません。@c
なぜなら、それらは入力ストリームの中の音楽要素によって生成される@c
のではなく、後になって @code{NoteHead} レイアウト オブジェクトによって@c
生成されるからです。

そのような直接作成されないレイアウト オブジェクトは、グラフィカル
オブジェクト名を明示的に指定した @code{\tweak} コマンドを用いることで@c
調整することができます:

@lilypond[fragment,verbatim,quote]
\tweak Stem.color #red
\tweak Beam.color #green c''8 e''
<c'' e'' \tweak Accidental.font-size #-3 ges''>4
@end lilypond

@code{\tweak} コマンドで音部記号や拍子記号を変更することはできません。@c
なぜなら、コンテキストを指定するために必要とされる追加要素の自動挿入に@c
より、それらは前に配置された @code{\tweak} コマンドとは分離されるから@c
です。

記譜要素の前に複数の @code{\tweak} コマンドを配置することができます
-- それらはすべて効果を持ちます:

@lilypond[verbatim,fragment,quote]
c'
  -\tweak style #'dashed-line
  -\tweak dash-fraction #0.2
  -\tweak thickness #3
  -\tweak color #red
  \glissando
f''
@end lilypond

入力ファイルのあるセクションから生成される音楽の流れ
-- 自動的に挿入される要素も含めて --
が、検証されます。@c
@rextend{Displaying music expressions} を参照してください。@c
これは、@code{\tweak} コマンドによって変更されるオブジェクトを決定するとき、@c
あるいは、@c
@code{\tweak} の適用で入力を調整する方法を決定するときに役に立つかもしれません。

@morerefs
学習マニュアル:
@rlearning{調整手段}

拡張:
@rextend{Displaying music expressions}

@cindex tweaking control point (制御点を調整する)
@cindex control point, tweaking (制御点を調整する)

@knownissues
@code{\tweak} コマンドで和音の中にある複数のタイのうち 1 つだけの位置を@c
変更することはできません。@c
入力ファイルの中で最初に遭遇したタイの位置を変更してしまいます。

@node set 対 override
@subsection @code{\set} 対 @code{\override}
@translationof set versus override

@c TODO Should't a bunch of that be explained earlier?

@funindex \set
@funindex \override

@code{\set} と @code{\override} コマンドは、コンテキストと結びついた@c
プロパティを操作するものです。どちらの場合も、プロパティは@c
@emph{コンテキストの階層}に従います。そのコンテキスト自身で@c
値がセットされていないプロパティは、@c
対応する親コンテキストのプロパティの値を用いることになります。

コンテキスト プロパティの値や、その有効期間は動的なものであり、@c
音楽が解釈 (つまり、@q{イテレート}) されている最中にのみ有効なものです。@c
コンテキストが生成される時、プロパティはそのコンテキストの定義に従って
(変更が加えられる場合もあります) 初期化されます。続く変更は、音楽内にある@c
@q{プロパティを変更する}コマンドによって行われます。

グラフィカル オブジェクト (あるいは @qq{grob}) の定義は、コンテキスト
プロパティの中でも@emph{特別な}カテゴリに属しており、構造や使用方法が@c
通常のコンテキスト プロパティとは異なります。Grob の@c
定義は、Grob プロパティに細分化されます。

また、通常のコンテキスト プロパティと異なる点がもう一つあり、Grob 定義は@c
それぞれの Grob プロパティやサブプロパティを追跡するために用いる@c
内部@q{記録}を持っています。そのため、@c
これらのプロパティを異なるコンテキストに定義していても、@c
Grob が生成される時には@c
現在のコンテキストとその親の間で保持しているプロパティを@c
受け継ぐことで、@c
全ての Grob 定義を保持している状態になります。

Grob は音楽表記を解釈する際にエングラーバによって作成され、エングラーバが@c
属するコンテキストの現在の Grob 定義から初期プロパティを受け取ります。 @c
その後、エングラーバ (あるいは LilyPond の@q{バックエンド}の部分) は
Grob の初期プロパティを変更 (または追加) することができます。しかし、@c
これはコンテキスト自身の Grob 定義には影響しません。

LilyPond が、@q{ユーザ レベル}での調整において用いる
@emph{Grob プロパティ}という言葉は、実は@emph{コンテキスト}自身の持つ
Grob 定義のプロパティを指しています。

Grob 定義は @code{\override} と @code{\revert} という、@c
異なるコマンド セットでアクセスあるいは操作され、大文字で始まる名前を持ちます
(例えば @samp{NodeHead})。一方、通常のコンテキスト プロパティは
@code{\set} と @code{\unset} というコマンドで操作され、小文字で始まる@c
名前を持ちます。

@cindex @code{tweak}, relation to @code{\override} (@code{\override} に関連した@code{\tweak})
@funindex \tweak
@funindex \overrideProperty

@code{\tweak} や @code{\overrideProperty} は、全てのコンテキスト プロパティを@c
完全に無視して対象の Grob プロパティを変更します。この際、Grob が生成される@c
タイミングで取得され、@code{\tweak} では音楽イベントに関連する
Grob のプロパティが変更されます。@code{\overrideProperty} は特定の@c
オーバライドに対して使用します。


@node offset コマンド
@subsection @code{\offset} コマンド
@translationof The offset command

@funindex \offset
@cindex offsetting (オフセット)
@cindex default, offsetting (デフォルトのオフセット)

@code{\override}, @code{\tweak}, @code{\overrideProperty} コマンドによって
Grob プロパティを新たな値にセットすることができますが、そのようなプロパティを@c
デフォルトの値との相対関係で変更できると便利な場合があります。@code{\offset}
コマンドはこのような目的のために使用することができます。

@code{\offset} の記法は:

@example
[-]\offset @var{property} @var{offsets} @var{item}
@end example

このコマンドは、@var{item} によって指定される Grob の @var{property}
プロパティのデフォルト値に、@var{offsets} の内容を加算します。

コマンドの記法によって、@code{\offset} は @code{\tweak} のように作用するか
@code{\override} のように作用します。この使用法の差は @code{\offset} と@c
用いられる Grob プロパティについてもう少し説明した後に示します。

@subsubsubheading{オフセットできるプロパティ}

全てではないですが、多くの Grob プロパティをオフセットすることができます。@c
@var{property} がオフセットできない場合、オブジェクトは変更されず、警告が@c
出力されます。このような場合には、代わりに @code{\override} や @code{\tweak}
を用いてオブジェクトを変更する必要があります。

トライアンドエラーで、警告を手がかりにしてオフセットできるものと@c
できないものを判別することができます。しかし、より系統的なアプローチも@c
存在します。

次の基準は、プロパティが @code{\offset} で変更できるかどうかの目安になります:

@itemize

@item
Grob の説明に@q{デフォルト設定}が記述されているプロパティ。このような@c
プロパティは @rinternals{All layout objects} に Grob 毎にリストアップ@c
されています。(これらは @file{scm/define-grobs.scm} からも確認することが@c
できます。)

@item
数値を取るプロパティ。具体的には @code{number}、@code{number} のリスト、@c
@code{number-pair}、@code{number-pair-list} を取るものを指します。@c
@rinternals{All layout objects} のページは、それぞれのプロパティが取る@c
データの型をリストアップしています。これはデフォルト設定が関数であっても@c
問題ありません。

@item
@q{サブ プロパティ}ではないプロパティ。サブ プロパティとは、他のプロパティの@c
中にあるプロパティを指します。

@item
無限大にセットされていないプロパティ。正や負の無限大をオフセットする@c
良い方法はありません。
@end itemize

次の例では、いくつかの Grob プロパティのオフセット可能性を、上の基準に基づいて@c
判断します。

@itemize

@item オフセットできるプロパティ

@table @asis

@item @code{Hairpin.height}

このプロパティはサブ プロパティではなく、@rinternals{Hairpin} にリストアップ@c
されています。値については、@q{dimension, in staff space} を取り、デフォルト値は
@code{0.6666} です---無限大ではない @code{number} となっています。

@item @code{Arpeggio.positions}

@rinternals{Arpeggio} のページには、@code{positions} プロパティが
@q{pair of numbers} を取ると記述されています。デフォルト値は
@code{ly:arpeggio::positions} となっています---これは、タイプセットの時に@c
評価され、各 @code{Arpeggio} オブジェクトについて @code{number} のペアを返す@c
コールバック関数です。

@end table

@item オフセットできないプロパティ

@table @asis

@item @code{Hairpin.color}

@rinternals{Hairpin} には、@code{color} がリストアップされていません。

@item @code{Hairpin.circled-tip}

@rinternals{Hairpin} の @code{Hairpin.circled-tip} には、@code{boolean} の@c
値を取るという記述があります。@code{boolean} は数値ではありません。

@item @code{Stem.details.lengths}

@rinternals{Stem} の中にリストアップされており、デフォルト値が
@code{number} のリストになっていますが、これは@q{サブ プロパティ}です。@c
@q{ネストされたプロパティ}のオフセットには対応していません。

@end table

@end itemize

@subsubsubheading{\offset を override として使う}

@var{item} が Grob の名前 (例えば @code{Arpeggio} や @code{Staff.OttavaBracket})
である場合、@code{\offset} の結果は指定された Grob の @code{\override}
となります。

@example
\offset @var{property} @var{offsets} [@var{context}.]@var{GrobName}
@end example

@q{override} の形では、先頭のハイフンは@emph{必ず}使われません。@code{\override}
コマンドにハイフンが使われないのと同様です。

次の例では、最初の小節にあるデフォルト設定のアルペジオを、@q{override} 形で@c
より和音全体に広がるようにオフセットします。アルペジオは上下に譜スペースの@c
半分ずつ広がります。また、最初の和音について通常の方法で @code{positions}
プロパティをオーバライドする例も示しています。この方法では端点を@c
相対座標ではなく絶対座標で指定しなければならないため、@q{譜スペースの半分だけ@c
広げる}という目的を全く表現できていません。また、他の和音についてはまた@c
サイズや位置が異なるため、それぞれに別の @code{\override} が必要です。

@lilypond[quote,verbatim]
arpeggioMusic = {
  <c' e' g'>\arpeggio <a' c'' e''>\arpeggio
  <d' f' a' c''>\arpeggio <c' e' g' b' d'' f'' a''>\arpeggio
}

{
  \arpeggioMusic
  \bar "||"
  \offset positions #'(-0.5 . 0.5) Arpeggio
  \arpeggioMusic
  \bar "||"
  \once \override Arpeggio.positions = #'(-3.5 . -0.5)
  <c' e' g'>1\arpeggio
  \bar "||"
}
@end lilypond

@funindex \once
@funindex \temporary

@q{override} の形では、@code{\offset} の前に @code{\once} や @code{\temporary}
を置くことができ、@code{\revert} で元に戻すことができます
(@rextend{Intermediate substitution functions} を参照してください)。つまり、@c
@code{\offset} は実際には @var{property} の @code{\override} を作成している@c
ことになります。

@lilypond[quote,verbatim]
music = { c'8\< d' e' f'\! }

{
  \music
  \offset height 1 Hairpin
  \music
  \music
  \revert Hairpin.height
  \music
  \bar "||"
  \once \offset height 1 Hairpin
  \music \music
  \bar "||"
  \override Hairpin.height = 0.2
  \music
  \temporary \offset height 2 Hairpin
  \music
  \music
  \revert Hairpin.height
  \music
  \bar "||"
}
@end lilypond

@funindex \single
@funindex \undo

また、@code{\override} と同様に、@code{\offset} の @q{override} 形は
@code{\undo} や @code{\single} と使用することもできます:

@lilypond[quote,verbatim]
longStem = \offset length 6 Stem

{
 \longStem c'4 c''' c' c''
 \bar "||"
 \undo \longStem c'4 c''' c' c''
 \bar "||"
 \single \longStem c'4 c''' c' c''
 \bar "||"
}
@end lilypond

@subsubsubheading{\offset を tweak として使う}

@var{item} が音楽表記 (@code{(} や @code{\arpeggio} など) である場合、@c
@q{tweak} が適用された音楽表記が出力されます。

@example
[-]\offset [@var{GrobName}.]@var{property} @var{offsets} @var{music-expression}
@end example

@q{tweak} 形の @code{\offset} の記法は、@code{\tweak} コマンドそのものに@c
似ています。引数の順番や、前に付くハイフンはそれと同様です。

次の例は、@code{BreathingSign} オブジェクトの縦位置を調整するために
@q{tweak} 形を用いています。これと、通常の @code{\tweak} コマンドによる@c
例を見比べてください。記法は同一ですが、@code{\tweak} の出力はあまり直感的@c
ではありません。なぜなら、@code{BreathingSign.Y-offset} が譜線の中央を@c
原点として計算されるためです。@code{\offset} を使えば、@code{Y-offset} が@c
どのように計算されているかを知る必要はありません。

@lilypond[quote,verbatim]
{
  c''4
  \breathe
  c''4
  \offset Y-offset 2 \breathe
  c''2
  \tweak Y-offset 3 \breathe
}
@end lilypond

前の例では、@q{tweak} されたオブジェクトはユーザの入力から直接作られています:
@code{\breathe} コマンドは @code{BreathingSign} オブジェクトを明示的に@c
作り出すためです。コマンドが対象にするオブジェクトが曖昧ではないため、@c
オブジェクトの名前を指定する必要はありませんでした。しかし、@c
オブジェクトが@emph{間接的に}作られる場合には、Grob の名前を含める必要が@c
あります。これは @code{\tweak} コマンドと同様です。

次の例では、@code{Beam} オブジェクトの @code{positions} プロパティを
@code{\offset} することで、連桁を 2 譜スペース分下にずらしています。

最初の @code{\offset} では、連桁を明示的に作り出すものが存在しないため、
Grob の名前が必要となります。次の @code{\offset} では、連桁が音楽表記
@code{[} によって手動で作り出されるため、Grob の名前は必要ではありません。@c
(また、後者では @code{number-pair} の両方をオフセットするために、@c
単一の @code{number} を用いる省略記法も示しています。)

@lilypond[quote,verbatim]
{
  c''8 g'' e'' d''
  \offset Beam.positions #'(-2 . -2)
  c''8 g'' e'' d''
  c''8 g'' e'' d''
  c''8-\offset positions #-2 [ g'' e'' d'']
}
@end lilypond

@subsubsubheading{改行するスパナを \offset する}

改行や改ページにまたがるスパナの一部分を個別に変更することもできます。@c
このような場合、@var{offsets} はプロパティが要求する型のリストを取ります。

このように用いられる @code{\offset} コマンドは @code{\alterBroken} コマンドと@c
類似しています。(@ref{Modifying broken spanners} を参照してください。)
ただし、@code{\alterBroken} とは異なり、@code{\offset} に与えられる値は@c
絶対値ではなく相対値となります。

次の例は、@q{改行する} @code{OttavaBracket} オブジェクトを、@code{staff-padding}
プロパティにより移動します。プロパティは元々 @code{number} を取るため、@c
@var{offsets} は @code{number} のリストを取り、改行によって分けられる 2 つの@c
部分に対応します。1 行目のブラケットは、@code{staff-padding} のデフォルト値に
@code{0} が加算されることになるため実質変更されません。2 行目のブラケットは@c
デフォルトの高さから 3 譜スペースだけ上に移動します。高さのデフォルト値
(絶対値) は @code{2} ですが、位置をオフセットするためにこの値を知る必要は@c
ありません。

@lilypond[quote,verbatim]
{
  \offset staff-padding #'(0 3) Staff.OttavaBracket
  \ottava #1
  c'''2 c'''
  \break
  c'''2 c'''
}
@end lilypond

次の例は、@code{Slur} オブジェクトの @code{control-points} プロパティを@c
オフセットすることで @code{\shape} コマンドを模倣しています。@c
ここでは、@var{offsets} は @code{number-pair-list} のリストとなり、@c
それぞれの要素がスラーの一つの部分に対応します。この例では、@c
@ref{Modifying shapes} に示した例と全く同じ結果を出力します。

@lilypond[quote,verbatim]
{
  c'4-\offset control-points #'(
               ((0 . 0) (0 . 0) (0 . 0) (0 . 1))
               ((0.5 . 1.5) (1 . 0) (0 . 0) (0 . -1.5))
              ) ( f'4 g' c''
  \break
  d'4 c'' f' c')
}
@end lilypond


@node 連想配列を変更する
@subsection 連想配列を変更する
@translationof Modifying alists

ユーザが変更可能なプロパティの中には、@c
内部的には @emph{連想配列} として存在しているものがあります
-- 連想配列は @emph{キー} と @emph{値} のペアの配列を保持します。@c
連想配列の構造は下記のとおりです:

@example
'((@var{キー1} . @var{値1})
  (@var{キー2} . @var{値2})
  (@var{キー3} . @var{値3})
  @dots{})
@end example

ある連想配列がグラフィカル オブジェクト プロパティまたは
@code{\paper} 変数である場合、@c
その連想配列の個々のキーを、他のキーに影響を与えることなく、@c
変更することができます。

例えば、譜グループの中にある隣り合う譜間のスペースを減らすには、@c
@code{StaffGrouper} グラフィカル オブジェクトの
@code{staff-staff-spacing} プロパティを使用します。@c
このプロパティは 4 つのキー
-- @code{basic-distance}, @code{minimum-distance},
@code{padding}, それに @code{stretchability} --
を持つ連想配列です。@c
このプロパティの標準設定は、@c
内部リファレンスの @qq{Backend} セクションでリストアップされています
(@rinternals{StaffGrouper} を参照してください):

@example
'((basic-distance . 9)
  (minimum-distance . 7)
  (padding . 1)
  (stretchability . 5))
@end example

譜間のスペースを小さくする方法の 1 つは、@c
@code{basic-distance} キーの値 (@code{9}) を
@code{minimum-distance} キーの値 (@code{7}) 近くまで減らすことです。@c
個々のキーを変更するには、@emph{ネストされた宣言} を使います:

@c KEEP LY
@lilypond[quote,verbatim]
% デフォルトの譜間スペース
\new PianoStaff <<
  \new Staff { \clef treble c''1 }
  \new Staff { \clef bass   c1   }
>>

% 譜間スペースを減らします
\new PianoStaff \with {
  % this is the nested declaration
  \override StaffGrouper.staff-staff-spacing.basic-distance = #7
} <<
  \new Staff { \clef treble c''1 }
  \new Staff { \clef bass   c1   }
>>
@end lilypond

ネストされた宣言は、プロパティの他のキーに変更を加えることなく、@c
指定されたキー (上の例では @code{basic-distance}) を更新します。

今度は、譜を重ならない範囲でできる限り近づけたいとします。@c
最も簡単な方法は、連想配列の 4 つのキーすべてを 0 にセットすることです。@c
しかしながら、4 つのネストされた宣言を記述する必要はありません。@c
1 つの宣言でプロパティを丸ごと再定義することができます:

@lilypond[quote,verbatim]
\new PianoStaff \with {
  \override StaffGrouper.staff-staff-spacing =
    #'((basic-distance . 0)
       (minimum-distance . 0)
       (padding . 0)
       (stretchability . 0))
} <<
  \new Staff { \clef treble c''1 }
  \new Staff { \clef bass   c1   }
>>
@end lilypond

連想配列の再定義でリストアップされなかったキーは、@c
@emph{セットされなかった場合のデフォルト値} にリセットされます。@c
@code{staff-staff-spacing} の場合、@c
セットされなかったキーは 0 にリセットされます
(@code{stretchability} は例外で、セットされなかった場合、@c
@code{basic-distance} にリセットされます)。@c
このため、以下の 2 つの宣言は等価です:

@example
\override StaffGrouper.staff-staff-spacing =
  #'((basic-distance . 7))

\override StaffGrouper.staff-staff-spacing =
  #'((basic-distance . 7)
     (minimum-distance . 0)
     (padding . 0)
     (stretchability . 7))
@end example

連想配列の再定義でリストアップされなかったキーがあることにより、@c
初期化ファイルでセットされたり、@c
入力ファイルがコンパイルされるときに読み込まれた@c
標準設定が (意図せずに) 削除される可能性があります。@c
上の例では、@code{padding} と @code{minimum-distance} の標準設定
(@file{scm/define-grobs.scm} で定義されます) は、@c
@emph{セットされなかった場合のデフォルト値} (両方とも 0) にリセットされます。@c
プロパティや (任意のサイズ) 連想配列を定義した場合、@c
セットされなかったキー値はすべて @emph{セットされなかった場合のデフォルト値}
にリセットされます。@c
そうすることを意図しているのでない限り、@c
ネストされた宣言を用いてキー値を個々に更新する方が安全です。

@warning{ネストされた宣言は、コンテキスト プロパティ連想配列
(@code{beamExceptions}, @code{keyAlterations}, @code{timeSignatureSettings} 等)
に対しては機能しません。@c
これらのプロパティを変更するには、@c
連想配列として丸ごと再定義するしかありません。}


@node 役に立つコンセプトとプロパティ
@section 役に立つコンセプトとプロパティ
@translationof Useful concepts and properties

@menu
* 入力モード::
* 向きと配置::
* 距離と距離の単位::
* 寸法::
* 譜記号プロパティ::
* スパナ::
* オブジェクトの可視性::
* ライン スタイル::
* オブジェクトを回転させる::
@end menu


@node 入力モード
@subsection 入力モード
@translationof Input modes

入力ファイルの中に保持されている記譜を解釈する方法は、@c
現在の入力モードによって決定されます。@c
一般的には、入力モードを指定する方法は 2 種類あります:
長い形 (例えば @code{\chordmode}) と短い形 (例えば @code{\chords}) です。@c
長い形は通常、入力を変数に格納する際や、明示的に作成されたコンテキストに@c 
直接音楽を入力する際に使用されます。短い形は、入力に対応したコンテキストを@c
暗黙的に作成し、そのコンテキストに直接入力を渡します。入力を受け取る@c
コンテキストを明示的に生成する必要がないような、シンプルな状況において有用です。

@subsubsubheading 和音モード

@funindex \chordmode
@funindex \chords

このモードは @code{\chordmode} コマンドで有効になり、@c
入力はコード記譜法の構文で解釈されるようになります。@c
@ref{Chord notation} を参照してください。@c
和音モードで入力された音楽は、@code{Staff} コンテキスト内では和音として、@c
@code{ChordNames} コンテキスト内ではコード ネームとして、@c
@code{FretBoards} コンテキスト内ではフレットボードとして表示されます。

和音モードは @code{\chords} コマンドでも有効になります。@c
このコマンドを用いると、@c
入力は暗黙的に作成された @code{ChordNames} コンテキストの中で@c
コード記譜法の構文で解釈され、コード ネームとして表示されます。@c
@ref{Printing chord names} を参照してください。

@subsubsubheading ドラム モード

@funindex \drummode
@funindex \drums

このモードは @code{\drummode} コマンドで有効になり、@c
入力はドラム記譜法の構文で解釈されるようになります。@c
@ref{Basic percussion notation} を参照してください。@c
ドラム モードで入力された音楽は、@code{DrumStaff} コンテキストの中で@c
打楽器の音符として表示されます。

また、ドラム モードは @code{\drums} コマンドでも有効になります。@c
このコマンドを用いると、@c
入力は暗黙的に作成された @code{DrumStaff} コンテキストの中で@c
ドラム記譜法の構文で解釈され、打楽器の音符として表示されます。@c
@ref{Basic percussion notation} を参照してください。

@subsubsubheading 通奏低音モード

@funindex \figuremode
@funindex \figures

このモードは @code{\figuremode} コマンドで有効になり、@c
入力は通奏低音の構文で解釈されるようになります。@c
@ref{Entering figured bass} を参照してください。@c
通奏低音モードで入力された音楽は、@code{FiguredBass} コンテキストか
@code{Staff} コンテキストの中で通奏低音として表示されます。

また、通奏低音モードは @code{\figures} コマンドでも有効になります。@c
このコマンドを用いると、@c
入力は暗黙的に作成された @code{FiguredBass} コンテキストの中で@c
通奏低音の構文で解釈され、通奏低音記号として表示されます。@c
@ref{Introduction to figured bass} を参照してください。

@subsubsubheading フレットとタブ モード

フレット記号とタブ記号を入力するための特別な入力モードはありません。

タブ図を作成するには、音符モードで音符や和音を入力して、@c
それらを @code{TabStaff} コンテキストの中に表示します。@c
@ref{Default tablatures} を参照してください。

譜の上にフレット図を作成するには、音符モードか和音モードのどちらかで@c
音符や和音を入力し、それらを @code{FretBoards} コンテキストの中に表示します。@c
@ref{Automatic fret diagrams} を参照してください。または、@c
フレット図は @code{\fret-diagram} コマンドを用いて、音符の上に@c
マークアップとして入力することもできます。@c
@ref{Fret diagram markups} を参照してください。

@subsubsubheading 歌詞モード

@funindex \lyricmode
@funindex \lyrics

このモードは @code{\lyricmode} コマンドで有効になり、@c
入力はオプションで演奏時間を持つ歌詞音節や、歌詞の修飾子として解釈されます。@c
@ref{Vocal music} を参照してください。@c
歌詞モードでの入力は、@code{Lyrics} コンテキストの中で@c
歌詞音節として表示されます。

また、歌詞モードは @code{\lyrics} コマンドでも有効になります。@c
このコマンドを用いると、@c
入力は暗黙的に作成された @code{Lyrics} コンテキストの中で@c
歌詞音節の構文で解釈され、歌詞音節として表示されます。

また、歌詞モードは @code{\addlyrics} コマンドでも有効になります。@c
このコマンドも同様に @code{Lyrics} コンテキストを暗黙的に作り出しますが、@c
前にある音楽に紐づくように @code{\lyricsto} コマンドも暗黙的に作り出します。@c
@ref{Automatic syllable durations} を参照してください。

@subsubsubheading マークアップ モード

@funindex \markup

このモードは @code{\markup} コマンドで有効になり、@c
入力はマークアップの構文で解釈されるようになります。@c
@ref{Text markup commands} を参照してください。

@subsubsubheading 音符モード

@funindex \notemode

このモードはデフォルトのモードであり、@c
@code{\notemode} コマンドで有効にすることもできます。@c
入力はピッチ、演奏時間、マークアップなどとして解釈され、@c
譜面上に音楽記譜として写植されます。

通常、音符モードを明示的に指定する必要はありません。@c
しかしながら、ある特定の状況
-- 例えば、歌詞モード、和音モード、あるいは他のモードを使っていて、@c
音符モードの構文でしか入力できないものを入力しようとしている場合 --
では、音符モードを明示的に指定することが有用な場合があります。


@node 向きと配置
@subsection 向きと配置
@translationof Direction and placement

楽譜を写植しているとき、多くの要素の向きと配置には選択の余地があります。@c
例えば、音符の符幹は上向きあるいは下向きにすることができ、@c
歌詞、強弱記号、他の表現記号は譜の上あるいは下に配置することができ、@c
テキストは左揃え、右揃え、あるいは中央揃えにすることができる、などです。@c
これらの選択のほとんどは LilyPond によって自動的に決定されますが、@c
強制的に向きや配置を指定することが望ましい場合もあります。

@menu
* アーティキュレーションの方向指示子::
* 方向プロパティ::
@end menu

@node アーティキュレーションの方向指示子
@unnumberedsubsubsec アーティキュレーションの方向指示子
@translationof Articulation direction indicators

デフォルトでは、アーティキュレーションのいくつかの向きは常に上または下に@c
なっています (例えば、強弱記号やフェルマータ)。@c
一方、他のアーティキュレーションは、符幹の向きによって、@c
向きが上下します (スラーやアクセントなど)。

@c TODO Add table showing these

アーティキュレーションの前に @emph{方向指示子} を置くことで、@c
デフォルトの向きをオーバライドすることができます。@c
3 つの方向指示子があります: @code{^} (@qq{上向き} を意味します)、@c
@code{_} (@qq{下向き} を意味します)、@c
それに @code{-} (@qq{デフォルトの向き} を意味します) です。@c
通常、方向指示子は省略することができ、その場合は @code{-} と見なされます。@c
しかしながら、以下のものの前には @strong{常に} 方向指示子を置く必要があります:

@itemize
@item @code{\tweak} コマンド
@item @code{\markup} コマンド
@item @code{\tag} コマンド
@item 文字列マークアップ。例えば、-"string"
@item 運指指示。例えば、@code{-1}
@item アーティキュレーションの短縮記法。例えば、@code{-.}, @code{->}, @code{--}
@end itemize

方向指示子は、その後にくる音符だけに効果を持ちます:

@lilypond[verbatim,quote]
\relative {
  c''2( c)
  c2_( c)
  c2( c)
  c2^( c)
}
@end lilypond

@node 方向プロパティ
@unnumberedsubsubsec 方向プロパティ
@translationof The direction property

多くのレイアウト オブジェクトの位置や向きは、@c
@code{direction} プロパティによって制御されます。

@code{direction} プロパティの値は、@c
@code{1} (@qq{上向き} あるいは @qq{上} を意味します)、@c
@code{-1} (@qq{下向き} あるいは @qq{下} を意味します)
にセットすることができます。@c
記号 @code{UP} と @code{DOWN} は、@c
それぞれ @code{1} と @code{-1} の代わりに用いることができます。@c
デフォルトの向きを指定するには、@c
@code{direction} を @code{0} あるいは @code{CENTER} にセットします。@c
このような方法を用いる代わりに、@c
多くの場合で、向きを指定するための前置コマンドが存在しています。@c
それらはすべて以下のような形式をとります:

@example
\@var{xxx}Up, \@var{xxx}Down, \@var{xxx}Neutral
@end example

@noindent
ここで、@code{\@var{xxx}Neutral} は @qq{デフォルトの向きを使用する}
ことを意味します。@c
@rlearning{譜内部オブジェクト} を参照してください。

いくつかのケースでは
-- 一般的な例としてはアルペジオしかありません --
@code{direction} プロパティの値は、@c
オブジェクトが親オブジェクトの左右どちらに配置されるかを指定します。
この場合、@code{-1} あるいは @code{LEFT} は @qq{左側} を意味し、@c
@code{1} あるいは @code{RIGHT} は @qq{右側} を意味します。@c
@code{0} あるいは @code{CENTER} は、前のケースと同様に、@c
@qq{デフォルトの向きを使用する} ことを意味します。

@ignore
These all have side-axis set to #X
Arpeggio - works
StanzaNumber - not tried
TrillPitchAccidental - not tried
TrillPitchGroup - not tried
@end ignore

これらの指示子は、キャンセルされるまで効果を持ちます。

@lilypond[verbatim,quote]
\relative {
  c''2( c)
  \slurDown
  c2( c)
  c2( c)
  \slurNeutral
  c2( c)
}
@end lilypond

多声の音楽では、一般的にオブジェクトの向きを変えるよりも明示的に
@code{voice} を指定した方が良いです。@c
更なる情報は、@ref{Multiple voices} を参照してください。

@morerefs
学習マニュアル:
@rlearning{Within-staff objects}

記譜法リファレンス:
@ref{Multiple voices}


@node 距離と距離の単位
@subsection 距離と距離の単位
@translationof Distances and measurements

@cindex distance, absolute (絶対距離)
@cindex distance, scaled (相対距離)

@funindex \mm
@funindex \cm
@funindex \in
@funindex \pt

LilyPond における距離には 2 つのタイプがあります: 絶対距離と相対距離です。

@funindex \staff-space

絶対距離は、マージン、インデント、それにその他の詳細なページ レイアウトを@c
指定するために使用され、デフォルトではミリメートルで指定されます。
距離は以下の単位で指定することもできます: @code{\mm}, @code{\cm},
@code{\inch} (インチ), それに @code{\pt} (ポイント。1/73.27 インチ) です。@c
また、ページ レイアウトにおける距離は、@c
値の後ろに @code{\staff-space} を付けることにより、
比率で指定することもできます (次の段落を参照してください)。@c
ページ レイアウトについての詳細は、@c
@ref{Page layout} に記述されています。

相対距離は常に譜スペースを単位として指定されます
 -- 稀に、半譜スペースが使用されます。@c
譜スペースは隣り合う 2 本の譜線間の距離です。@c
グローバル譜サイズを設定することにより、@c
デフォルト値をグローバルに変更することができます。@c
また、@code{StaffSymbol} の @code{staff-space} プロパティを@c
変更することにより、譜スペースをローカルにオーバライドすることもできます。@c
相対距離は、グローバル譜サイズや @code{StaffSymbol} の @code{staff-space}
プロパティのいずれかが変更されると、自動的に変更されます。@c
しかしながら、フォントの比率はグローバル譜サイズが変更された場合にのみ、@c
自動的に変更されます。@c
そのため、グローバル譜サイズは@c
容易に描画される楽譜全体のサイズを変更することができます。@c
グローバル譜サイズを設定するための手段については、@c
@ref{譜サイズを設定する} を参照してください。

@funindex magstep

楽譜のある部分だけの比率を変更したいのなら
-- 例えば、オッシア セクションや脚注で --
単純にグローバル譜サイズを変更するわけにはいきません。@c
なぜなら、グローバル譜サイズを変更すると、楽譜全体が影響を受けるからです。@c
そのような場合、@code{StaffSymbol} の @code{staff-space} プロパティと@c
フォントのサイズをオーバライドすることにより、サイズを変更します。@c
フォント サイズの変更を @code{staff-space} 単位の変更に変換するには、@c
Scheme 関数 @code{magstep} を使用することができます。@c
この関数の説明と使用例については、@c
@rlearning{オブジェクトの長さと太さ} を参照してください。

@morerefs
学習マニュアル:
@rlearning{オブジェクトの長さと太さ}

記譜法リファレンス:
@ref{Page layout},
@ref{譜サイズを設定する}


@node 寸法
@subsection 寸法
@translationof Dimensions

@cindex dimension (寸法)
@cindex bounding box (バウンディング ボックス)

グラフィカル オブジェクトの寸法 (大きさ) は、オブジェクトの@c
バウンディング ボックスの左右端の位置、上下端の位置を指定します。@c
これらはオブジェクトの参照ポイントからの距離で指定し、単位は譜スペースです。@c
これらの位置は通常 2 つの Scheme ペアで表現します。@c
例えば、テキスト マークアップ コマンド @code{\with-dimensions} は
3 つの引数を取り、最初の 2 つが左右端の位置と上下端の位置を示す
Scheme ペアです:

@example
\with-dimensions #'(-5 . 10) #'(-3 . 15) @var{arg}
@end example

これは @var{arg} のバウンディング ボックスの@c
左端を -5, 右端を 10, 下端を -3, 上端を 15 に指定しています。@c
全てオブジェクトの参照ポイントから、譜スペースの単位で計測されています。

@morerefs
記譜法リファレンス:
@ref{距離と距離の単位}


@node 譜記号プロパティ
@subsection 譜記号プロパティ
@translationof Staff symbol properties

@cindex adjusting staff symbol (譜記号を調節する)
@cindex drawing staff symbol (譜記号を描画する)
@cindex staff symbol, setting of (譜記号の設定)

@c TODO Extend or remove this section.  See also NR 1.6.2 Staff symbol
@c      Need to think of uses for these properties.  Eg 'line-positions
@c      is used in a snippet to thicken centre line.
@c      If retained, add @ref to here in 1.6.2  -td

譜線の垂直位置と譜線の本数を同時に定義することができます。@c
以下の例が示すように、音符の位置は譜線の位置には影響されません。

@warning{@code{'line-positions} プロパティは @code{'line-count} を@c
オーバライドします。@c
譜線の本数は、@code{'line-positions} の値リストの中にある要素数によって、@c
暗黙的に定義されます。}

@lilypond[verbatim,quote]
\new Staff \with {
  \override StaffSymbol.line-positions = #'(7 3 0 -4 -6 -7)
}
\relative { a4 e' f b | d1 }
@end lilypond

譜の幅を変更することができます。@c
単位は譜スペースです。@c
譜内部のオブジェクトのスペースは、この設定によって影響を受けません。

@lilypond[verbatim,quote]
\new Staff \with {
  \override StaffSymbol.width = #23
}
\relative { a4 e' f b | d1 }
@end lilypond


@node スパナ
@subsection スパナ
@translationof Spanners

多くの音楽記譜オブジェクトは、複数の音符あるいは複数の小節にまたがって、@c
広がりを持ちます。@c
例としては、スラー、連桁、連譜の囲み、volta 繰り返しの囲み、クレッシェンド、@c
トリル、それにグリッサンドがあります。@c
そのようなオブジェクトは総称して @qq{スパナ} と呼ばれ、@c
それらの見た目と振る舞いを制御するための特殊なプロパティを持ちます。@c
これらのプロパティのいくつかは、すべてのスパナに共通しています。@c
他のプロパティはスパナの部分集合に限定されています。

すべてのスパナは @code{spanner-interface} をサポートします。@c
いくつかのスパナ -- 2 つのオブジェクトの間に直線を描くもの -- は、さらに、@c
@code{line-spanner-interface} をサポートします。

@menu
* spanner-interface を使用する::
* line-spanner-interface を使用する::
@end menu

@node spanner-interface を使用する
@unnumberedsubsubsec @code{spanner-interface} を使用する
@translationof Using the spanner-interface

このインターフェイスは、@c
いくつかのスパナに適用される 2 つのプロパティを提供します。

@subsubsubheading The @code{minimum-length} プロパティ

スパナの最短の長さは、@code{minimum-length} プロパティによって指定されます。@c
通常、このプロパティを増加させると、@c
スパナの両端の間にある音符の間隔は増加します。@c
しかしながら、このオーバライドは多くのスパナで効果を持ちません。@c
なぜなら、それらの長さは他の要素によって決定されるからです。@c
以下に効果を持つ例を 2, 3 示します。

@ignore
Works for:
  Tie
  MultiMeasureRest
  Hairpin
  Slur
  PhrasingSlur

Works as long as callback is made:
  Glissando
  Beam

Works not at all for:
  LyricSpace
  LyricHyphen
  LyricExtender
  TextSpanner
  System

@end ignore

@c KEEP LY
@lilypond[verbatim,quote,fragment]
a'~ a'
a'
% タイの長さを増加させます
-\tweak minimum-length #5
~ a'
@end lilypond

@c KEEP LY
@lilypond[verbatim,quote]
\relative \compressMMRests {
  a'1
  R1*23
  % 休符バーの長さを増加させます
  \once \override MultiMeasureRest.minimum-length = #20
  R1*23
  a1
}
@end lilypond

@c KEEP LY
@lilypond[verbatim,quote]
\relative {
  a' \< a a a \!
  % ヘアピンの長さを増加させます
  \override Hairpin.minimum-length = #20
  a \< a a a \!
}
@end lilypond

さらに、このオーバライドはスラーとフレージング スラーの長さを@c
増加させるためにも使用されます:

@lilypond[verbatim,quote]
\relative {
  a'( g)
  a
  -\tweak minimum-length #5
  ( g)

  a\( g\)
  a
  -\tweak minimum-length #5
  \( g\)
}
@end lilypond

いくつかのレイアウト オブジェクトでは、@c
@code{minimum-length} プロパティは、@c
@code{set-spacing-rods} プロシージャが明示的に呼び出された場合にのみ@c
効果を持ちます。@c
このプロシージャを呼び出すには、@code{springs-and-rods} プロパティに@c
@code{ly:spanner::set-spacing-rods} をセットしておく必要があります。@c
例えば、グリッサンドの最短長は、@c
@code{springs-and-rods} プロパティが設定されていない限り、@c
効果を持ちません:

@c KEEP LY
@lilypond[verbatim,fragment,quote]
% デフォルト
e' \glissando c''

% 単独では効果を持ちません
\once \override Glissando.minimum-length = #20
e' \glissando c''

% 以下の両方のオーバライドが存在する場合にのみ、効果を持ちます
\once \override Glissando.minimum-length = #20
\once \override Glissando.springs-and-rods = #ly:spanner::set-spacing-rods
e' \glissando c''
@end lilypond

@code{Beam} オブジェクトでも同じことが言えます:

@c KEEP LY
@lilypond[verbatim,fragment,quote]
% 単独では効果を持ちません
\once \override Beam.minimum-length = #20
e'8 e' e' e'

% 以下の両方のオーバライドが存在する場合にのみ、効果を持ちます
\once \override Beam.minimum-length = #20
\once \override Beam.springs-and-rods = #ly:spanner::set-spacing-rods
e'8 e' e' e'
@end lilypond

@subsubsubheading The @code{to-barline} プロパティ

@code{spanner-interface} の 2 番目に有用なプロパティは
@code{to-barline} です。@c
デフォルトではこのプロパティは真であり、@c
小節の最初の音符のところで終了するヘアピンや他のスパナは@c
直前の小節線のところで終了させられます。@c
偽に設定すると、スパナは小節線を越えて、音符のところで終了します:

@lilypond[verbatim,quote]
\relative {
  a' \< a a a a \! a a a \break
  \override Hairpin.to-barline = ##f
  a \< a a a a \! a a a
}
@end lilypond

このプロパティはすべてのスパナに対して効果を持つわけではありません。@c
例えば、スラーやフレージング スラー、@c
あるいは小節線で終了させることに意味が無い他のスパナに対して、@c
このプロパティを @code{#t} に設定しても効果がありません。

@node line-spanner-interface を使用する
@unnumberedsubsubsec @code{line-spanner-interface} を使用する
@translationof Using the line-spanner-interface

@code{line-spanner-interface} をサポートするオブジェクトには@c
以下のものがあります:

@itemize
@item @code{DynamicTextSpanner}
@item @code{Glissando}
@item @code{TextSpanner}
@item @code{TrillSpanner}
@item @code{VoiceFollower}
@end itemize

これらのスパナのステンシルを描画する責任を持つルーチンは
@code{ly:line-spanner::print} です。@c
このルーチンはスパナの両端の位置を綿密に決定し、@c
求めに応じたスタイルでそれらの間に線を描きます@c
スパナの両端の位置はオンザフライ (その場、その時々) で算出されますが、@c
それらの Y 座標をオーバライドすることができます。@c
指定する必要のあるプロパティは、@c
プロパティ階層内で 2 階層下にネストされていますが、@c
この @code{\override} コマンドは非常にシンプルです:

@lilypond[quote,fragment,verbatim]
e''2 \glissando b'
\once \override Glissando.bound-details.left.Y = #3
\once \override Glissando.bound-details.right.Y = #-2
e''2 \glissando b'
@end lilypond

@code{Y} プロパティの単位は @code{staff-space} であり、@c
譜の中央線が 0 位置です。@c
グリッサンドでは、スパナの両端は各符頭の中心であり、@c
@code{Y} はそれらの点を上下させます。

@code{Y} が設定されていない場合、@c
値はスパナの両端の垂直位置から算出されます。

改行の場合、終点の @code{Y} の値は @code{bound-details} の@c
部分リスト @code{left-broken} や @code{right-broken} のによって指定されます。@c
例を示します:

@lilypond[ragged-right,fragment,verbatim,quote]
\override Glissando.breakable = ##t
\override Glissando.bound-details.right-broken.Y = #-3
c''1 \glissando \break
f''1
@end lilypond


@code{bound-details} プロパティの部分リスト @code{left} や @code{right} の@c
下位プロパティのいくつかは、@code{Y} と同じ方法で変更することができます:

@table @code
@item Y
終点の Y 座標を、@c
譜の中央線からの @code{staff-space} オフセットで、設定します。@c
デフォルトでは、終点オブジェクトの中心です。@c
ですから、グリッサンドは符頭の中心に向かって進みます。

水平方向に広がるスパナ -- テキスト スパナやトリル スパナなど --
では、この値は 0 に固定されています。

@item attach-dir
スパナのラインがオブジェクトの左右どちらから始まり、終わるのかを決定します。@c
@code{-1} (あるいは @code{LEFT}) であれば、@c
ラインは符頭の左側から開始あるいは終了します。

@item X
終点の絶対 X 座標です。@c
通常、オンザフライ (その場、その時々) で算出され、@c
これをオーバライドしてもあまり意味がありません。

@item stencil
ライン スパナは開始点や終了点で記号を持つ場合があり、@c
その記号はこのサブ プロパティに保持されています。@c
このサブ プロパティは内部で使用するためのものです。@c
このサブ プロパティの代わりに @code{text} を使用することを推奨します。

@item text
ステンシルを作成するために評価されるマークアップです。@c
水平スパナに @i{cresc.}, @i{tr} それに他のテキストを配置するために使用されます。

@lilypond[quote,ragged-right,fragment,verbatim]
\override TextSpanner.bound-details.left.text
   = \markup { \small \bold Slower }
\relative { c''2\startTextSpan b c a\stopTextSpan }
@end lilypond

@item stencil-align-dir-y
@item stencil-offset
これらの 1 つを設定しなければ、@c
ステンシルは、@code{X} と @code{Y} サブ プロパティで定義されたとおりに、@c
ラインに中央揃えで、終点に配置されます。@c
@code{stencil-align-dir-y} あるいは @code{stencil-offset} の@c
どちらかを設定すると、@c
記号が上下します:

@lilypond[quote,fragment,verbatim]
\override TextSpanner.bound-details.left.stencil-align-dir-y = #-2
\override TextSpanner.bound-details.right.stencil-align-dir-y = #UP

\override TextSpanner.bound-details.left.text = "ggg"
\override TextSpanner.bound-details.right.text = "hhh"

\relative { c'4^\startTextSpan c c c \stopTextSpan }
@end lilypond

予期される結果とは逆に、@c
負の値はテキストを @emph{上げる} ということに注意してください。@c
なぜなら、@code{-1} あるいは @code{DOWN} は@c
テキストの @emph{下端} をスパナ ラインに揃え、
@code{1} あるいは @code{UP} は@c
テキストの @emph{上端} をスパナ ラインに揃えるからです。

@item arrow
このサブ プロパティに @code{#t} をセットするとラインの終点に矢印が描かれます。

@item padding
このサブ プロパティはラインの終点と実際の終点の間のスペースを制御します。@c
パディングがなければ、グリッサンドは両端の符頭の中心から描かれます。

@end table

@funindex \endSpanners

音楽関数 @code{\endSpanners} は@c
直後の音符から始まるスパナをすぐに終了させます。@c
ちょうど 1 音符分でスパナを終了させますが、@c
@code{to-barline} が真で、かつ、次の音符の前に小節線がある場合は@c
その小節線のところでスパナを終了させます。

@lilypond[verbatim,quote,ragged-right]
\relative c'' {
  \endSpanners
  c2 \startTextSpan c2 c2
  \endSpanners
  c2 \< c2 c2
}
@end lilypond

@code{\endSpanners} を使用している場合、@c
@code{\startTextSpan} を @code{\endTextSpan} で閉じる必要はなく、@c
ヘアピンを @code{\!} で閉じる必要もありません。

@morerefs
内部リファレンス:
@rinternals{TextSpanner},
@rinternals{Glissando},
@rinternals{VoiceFollower},
@rinternals{TrillSpanner},
@rinternals{line-spanner-interface}


@node オブジェクトの可視性
@subsection オブジェクトの可視性
@translationof Visibility of objects

@cindex object, visibility of (オブジェクトの可視性)
@cindex grob, visibility of (グラフィカル オブジェクトの可視性)
@cindex visibility of object (オブジェクトの可視性)

レイアウト オブジェクトの可視性を制御する主な方法は 4 つあります:
オブジェクトのステンシルを削除する方法、オブジェクトを透明にする方法、@c
オブジェクトの色を白にする方法、あるいは、@c
オブジェクトの @code{break-visibility} プロパティをオーバライドする方法です。
最初の 3 つの方法はすべてのレイアウト オブジェクトに適用されますが、@c
最後の方法はいくつかの -- @emph{改行可能な} オブジェクト --
だけに適用されます。@c
学習マニュアルでは、これら 4 つのテクニックについて紹介しています。@c
@rlearning{オブジェクトの可視性と色} を参照してください。

さらに、特定のレイアウト オブジェクト特有のテクニックがいくつかあります。@c
それらについては、特別な考慮でカバーされています。

@menu
* ステンシルを削除する::
* オブジェクトを透明にする::
* オブジェクトを白で描く::
* break-visibility を用いる::
* 特別な考慮を必要とするもの::
@end menu


@node ステンシルを削除する
@unnumberedsubsubsec ステンシルを削除する
@translationof Removing the stencil

@cindex stencil, removing (ステンシルを削除する)
@funindex \omit

レウアウト オブジェクトはそれぞれステンシル プロパティを持ちます。@c
デフォルトでは、@c
このプロパティはそのオブジェクトを描画する特殊な関数にセットされています。@c
このプロパティが @code{#f} にオーバライドされた場合、@c
関数は呼び出されず、そのオブジェクトは描画されません。@c
@code{\revert} でデフォルトの動作に戻すことができます。

@lilypond[quote,fragment,verbatim]
a1 a
\override Score.BarLine.stencil = ##f
a a
\revert Score.BarLine.stencil
a a a
@end lilypond

これはよく使う操作であるため、@code{\omit} という短縮記法が存在します:

@lilypond[quote,fragment,verbatim]
a1 a
\omit Score.BarLine
a a
\undo \omit Score.BarLine
a a a
@end lilypond

@node オブジェクトを透明にする
@unnumberedsubsubsec オブジェクトを透明にする
@translationof Making objects transparent

@cindex transparent, making objects (オブジェクトを透明にする)
@funindex \hide

レイアウト オブジェクトはそれぞれ @code{transparent} プロパティを持っていて、@c
デフォルトでは @code{#f} にセットされています。@c
@code{#t} にセットされると、そのオブジェクトはスペースを占めたままですが、@c
不可視になります。

@lilypond[quote,fragment,verbatim]
a'4 a'
\once \override NoteHead.transparent = ##t
a' a'
@end lilypond

これにも @code{\hide} という短縮記法があります:

@lilypond[quote,fragment,verbatim]
a'4 a'
\once \hide NoteHead
a' a'
@end lilypond

@node オブジェクトを白で描く
@unnumberedsubsubsec オブジェクトを白で描く
@translationof Painting objects white

@cindex object, coloring (オブジェクトに色を付ける)
@cindex coloring object (オブジェクトに色を付ける)
@cindex layer (レイヤ)
@cindex printing order (描画の順番)
@cindex overwriting object (オブジェクトを上書きする)
@cindex object, overwriting (オブジェクトを上書きする)
@cindex grob, overwriting (グラフィカル オブジェクトを上書きする)

レイアウト オブジェクトはそれぞれ @code{color} プロパティを持っていて、@c
デフォルトでは @code{black} にセットされています。@c
このプロパティが @code{white} にセットされてると、@c
そのオブジェクトは白い背景と区別が付かなくなります。@c
しかしながら、そのオブジェクトが他のオブジェクトと交差している場合、@c
交差している場所の色はオブジェクトの描画順序によって決定されます。@c
これにより、以下に示すように、@c
白いオブジェクトの画像が幽霊のように浮かび上がることがあります:

@lilypond[quote,fragment,verbatim]
\override Staff.Clef.color = #white
a'1
@end lilypond

オブジェクトの描画順序を変更することにより、これを回避することができます。@c
すべてのレイアウト オブジェクトは @code{layer} プロパティを持っており、@c
このプロパティには整数がセットされています。@c
より小さな値の @code{layer} を持つオブジェクトが最初に描画され、@c
より大きな値の @code{layer} を持つオブジェクトが後になってから描画されます。@c
このため、@c
より大きな値を持つオブジェクトがより小さな値を持つオブジェクトを上書きします。@c
デフォルトでは、@c
たいていのオブジェクトの @code{layer} には @code{1} が代入されています。@c
しかしながら、いくつかのオブジェクト
-- @code{StaffSymbol} や @code{BarLine} など --
には @code{0} が代入されています。@c
同じ値の @code{layer} を持つオブジェクトを描画する順番は不確定です。

上記の例において、白い音部記号
(この @code{layer} のデフォルト値は @code{1} です)
は譜線 @c
(この @code{layer} のデフォルト値は @code{0} です)
の後に描画されます。@c
そのため、音部記号は譜線を上書きしています。@c
これを変更するには、@code{Clef} オブジェクトの @code{layer} に@c
より小さな値 -- 例えば、@code{-1} -- を与えて、@c
音部記号を先に描画させる必要があります:

@lilypond[quote,fragment,verbatim]
\override Staff.Clef.color = #white
\override Staff.Clef.layer = #-1
a'1
@end lilypond

@node break-visibility を用いる
@unnumberedsubsubsec break-visibility を用いる
@translationof Using break-visibility

@c TODO Add making other objects breakable

@funindex break-visibility

たいていのレイアウト オブジェクトは 1 回だけ描画されます。@c
しかしながら、小節線、音部記号、拍子記号、それに調号などのオブジェクトは、@c
改行が起こると 2 回描画する必要があります
-- 行の最後で 1 回、次の行の最初でもう 1 回。@c
そのようなオブジェクトは @emph{改行可能} と呼ばれ、@c
それらのオブジェクトが描画される可能性がある 3 つの場所
-- 行の先頭、行の途中 (それらが変更された場合)、@c
それに、行の最後 (そこで変更が行われた場合) --
における可視性を制御する @code{break-visibility} プロパティを持ちます。

例えば、デフォルトでは拍子記号は最初の行の先頭で描画されますが、@c
変更されない限り他の場所には描画されません。@c
変更された場合、拍子記号は変更が行われた場所に描画されます。@c
この変更が行の最後で行われた場合、新しい拍子記号は次の行の先頭に描画され、@c
その前の行の最後にも忠告の拍子記号が描画されます。

この振る舞いは @code{break-visibility} プロパティによって制御されます。@c
このプロパティについての説明は
@c Leave this ref on a newline - formats incorrectly otherwise -td
@rlearning{オブジェクトの可視性と色}
を参照してください。@c
このプロパティは 3 つのブール値からなるベクトルをとり、@c
順に、そのオブジェクトが行の最後で描画されるかどうか、@c
行の途中で描画されるかどうか、@c
そして、行の先頭で描画されるかどうかを決定します。@c
より正確には、改行の前、改行がない場合、改行の後です。

@code{break-visibility} プロパティによって制御する代わりに、@c
これら 8 通りの組み合わせを @file{scm/output-lib.scm} で定義されている@c
定義済み関数によって指定することもできます。@c
このファイルの中で、最後の 3 列がその列のヘッダで示される場所での@c
可視性を表しています:

@multitable {@code{begin-of-line-invisible}} {@code{#(#t #t #t)}} {改行前} {改行なし} {改行後}
@headitem 関数形式                   @tab ベクトル形式           @tab 改行前 @tab 改行なし @tab 改行後

@item @code{all-visible}             @tab @code{#(#t #t #t)}     @tab yes    @tab yes      @tab yes
@item @code{begin-of-line-visible}   @tab @code{#(#f #f #t)}     @tab no     @tab no       @tab yes
@item @code{center-visible}          @tab @code{#(#f #t #f)}     @tab no     @tab yes      @tab no
@item @code{end-of-line-visible}     @tab @code{#(#t #f #f)}     @tab yes    @tab no       @tab no
@item @code{begin-of-line-invisible} @tab @code{#(#t #t #f)}     @tab yes    @tab yes      @tab no
@item @code{center-invisible}        @tab @code{#(#t #f #t)}     @tab yes    @tab no       @tab yes
@item @code{end-of-line-invisible}   @tab @code{#(#f #t #t)}     @tab no     @tab yes      @tab yes
@item @code{all-invisible}           @tab @code{#(#f #f #f)}     @tab no     @tab no       @tab no
@end multitable

@code{break-visibility} のデフォルト設定は@c
レイアウト オブジェクトによって異なります。@c
以下の表は、@code{break-visibility} によって影響をうける@c
すべてのレイアウト オブジェクトと、そのプロパティのデフォルト設定を示しています:

@multitable @columnfractions .3 .3 .4

@headitem レイアウト オブジェクト   @tab 通常のコンテキスト  @tab デフォルト設定

@c omit Ambitus as it appears not to be affected by break-visibility -td
@c @item @code{Ambitus}          @tab as specified   @tab @code{begin-of-line-visible}
@item @code{BarLine}             @tab @code{Score}          @tab calculated
@item @code{BarNumber}           @tab @code{Score}          @tab @code{begin-of-line-visible}
@c omit the following item until it can be explained -td
@c @item @code{BreakAlignGroup}  @tab @code{Score}          @tab calculated
@item @code{BreathingSign}       @tab @code{Voice}          @tab @code{begin-of-line-invisible}
@item @code{Clef}                @tab @code{Staff}          @tab @code{begin-of-line-visible}
@item @code{Custos}              @tab @code{Staff}          @tab @code{end-of-line-visible}
@item @code{DoublePercentRepeat} @tab @code{Voice}          @tab @code{begin-of-line-invisible}
@item @code{KeyCancellation}     @tab @code{Staff}          @tab @code{begin-of-line-invisible}
@item @code{KeySignature}        @tab @code{Staff}          @tab @code{begin-of-line-visible}
@c omit LeftEdge until it can be explained -td
@c @item @code{LeftEdge}         @tab @code{Score}          @tab @code{center-invisible}
@item @code{ClefModifier}        @tab @code{Staff}          @tab @code{begin-of-line-visible}
@item @code{RehearsalMark}       @tab @code{Score}          @tab @code{end-of-line-invisible}
@item @code{TimeSignature}       @tab @code{Staff}          @tab @code{all-visible}

@end multitable

以下の例は、小節線の可視性を制御するベクトルの使用方法を示しています:

@c KEEP LY
@lilypond[quote,verbatim,ragged-right]
\relative {
  f'4 g a b
  f4 g a b
  % カレント行の最後で小節線を削除します
  \once \override Score.BarLine.break-visibility = ##(#f #t #t)
  \break
  f4 g a b
  f4 g a b
}
@end lilypond

@code{break-visibility} をオーバライドするために使用される@c
ベクトルの要素 3 つをすべて記述する必要がありますが、@c
それらすべてが各レイアウト オブジェクトに対して効果を持つわけではなく、@c
組み合わせによってはエラーになる場合もあります。@c
以下の制限があります:

@itemize @bullet
@item 小節線を行の先頭に描画することはできません。
@item 小節番号が @code{1} から始まるのでなければ、@c
@emph{最初の}行の先頭に描画することはできません。
@item 音部記号 -- 次のセクションを参照してください
@item 2 重線のパーセント繰り返しは@emph{すべて描画する}か、@c
@emph{すべて描画しない}かのどちらかです。@c
描画するには @code{begin-of-line-invisible} を用い、@c
描画しないのなら @code{all-invisible} を用います。
@item Key signature -- 次のセクションを参照してください
@item ClefModifier -- 次のセクションを参照してください
@end itemize

@node 特別な考慮を必要とするもの
@unnumberedsubsubsec 特別な考慮を必要とするもの
@translationof Special considerations

@subsubsubheading 明示的な変更の後の可視性

@cindex key signature, visibility following explicit change (明示的な変更の後の調号の可視性)
@funindex explicitKeySignatureVisibility
@cindex clef, visibility following explicit change (明示的な変更の後の音部記号の可視性)
@funindex explicitClefVisibility

@code{break-visibility} プロパティが調号の可視性と音部記号の変更を@c
制御するのは、行の先頭 -- つまり、改行の後 -- においてだけです。@c
行の途中や終わりでの明示的な調の変更や音部記号の変更の後に出現する@c
調号や音部記号の可視性には効果を持ちません。@c
以下の例では、@code{all-invisible} がセットされていますが、@c
B フラット メジャーへの明示的な変更の後に出現する調号は可視のままです。

@c KEEP LY
@lilypond[quote,verbatim,ragged-right]
\relative {
  \key g \major
  f'4 g a b
  % すべての調号を削除しようと試みます
  \override Staff.KeySignature.break-visibility = #all-invisible
  \key bes \major
  f4 g a b
  \break
  f4 g a b
  f4 g a b
}
@end lilypond

そのような明示的な調号や音部記号の変更の可視性は
@code{explicitKeySignatureVisibility} プロパティや
@code{explicitClefVisibility} プロパティによって制御されます。@c
これらは @code{break-visibility} プロパティと等価であり、@c
どちらも @code{break-visibility} と同様に 3 つのブール値からなるベクトルか@c
上でリストアップした定義済み関数をとります。@c
どちらも @code{Staff} コンテキストのプロパティであり、@c
レイアウト オブジェクト自体のプロパティではありません。@c
ですから、これらは @code{\set} コマンドでセットします。@c
どちらもデフォルトでは @code{all-visible} がセットされています。@c
これらのプロパティは明示的な変更の結果として生じる@c
調号と音部記号の可視性だけを制御し、@c
行の先頭での調号や音部記号には効果を持ちませんので、@c
オブジェクトを削除するには適切な @code{break-visibility}
をオーバライドする必要があります。

@lilypond[quote,verbatim,ragged-right]
\relative {
  \key g \major
  f'4 g a b
  \set Staff.explicitKeySignatureVisibility = #all-invisible
  \override Staff.KeySignature.break-visibility = #all-invisible
  \key bes \major
  f4 g a b \break
  f4 g a b
  f4 g a b
}
@end lilypond

@subsubsubheading 前の調をキャンセルする臨時記号の可視性

明示的な調の変更で描画される前の調をキャンセルする臨時記号を削除するには、@c
@code{Staff} コンテキスト プロパティ @code{printKeyCancellation} に
@code{#f} をセットします:

@lilypond[quote,verbatim,ragged-right]
\relative {
  \key g \major
  f'4 g a b
  \set Staff.explicitKeySignatureVisibility = #all-invisible
  \set Staff.printKeyCancellation = ##f
  \override Staff.KeySignature.break-visibility = #all-invisible
  \key bes \major
  f4 g a b \break
  f4 g a b
  f4 g a b
}
@end lilypond

このオーバライドによって、調の変更を示す臨時記号だけが残ります。

調を C@tie{}メジャーや A@tie{}マイナーに変更する時、前の調をキャンセル@c
する臨時記号は前の調のキャンセルしている @emph{だけ} であることに@c
注意してください。@c
そのようなケースでは、@code{printKeyCancellation} を @code{#f} に@c
設定しても効果はありません:

@lilypond[quote,verbatim,ragged-right]
\relative {
  \key g \major
  f'4 g a b
  \set Staff.explicitKeySignatureVisibility = #all-invisible
  \set Staff.printKeyCancellation = ##f
  \key c \major
  f4 g a b \break
  f4 g a b
  f4 g a b
}
@end lilypond

調を C@tie{}メジャーや A@tie{}マイナーに変更する場合に、@c
前の調をキャンセルする臨時記号を消すには、@code{KeyCancellation}
グラフィカル オブジェクトの可視性をオーバライドします:

@lilypond[quote,verbatim,ragged-right]
\relative {
  \key g \major
  f'4 g a b
  \set Staff.explicitKeySignatureVisibility = #all-invisible
  \override Staff.KeyCancellation.break-visibility = #all-invisible
  \key c \major
  f4 g a b \break
  f4 g a b
  f4 g a b
}
@end lilypond

@c TODO Add visibility of cautionary accidentals before notes

@subsubsubheading 自動小節線

@funindex automaticBars
@cindex bar line, suppressing (小節線を消す)

特殊なケースとして、@c
@code{Score} コンテキストの @code{automaticBars} プロパティを@c
設定することにより、小節線の描画を Off にすることもできます。@c
@code{#f} をセットされた場合、小節線は自動的には描画されなくなり、@c
@code{\bar} コマンドで明示的に作成しなければならなくなります。@c
定義済みコマンド @code{\cadenzaOn} とは異なり、小節数はカウントされ続けます。@c
後になってこのプロパティに @code{#t} がセットされると、@c
このカウントに従って小節線の生成が再開されます。@c
@code{#f} がセットされている場合、@c
改行が起こりえるのは明示的な @code{\bar} コマンドがある場所でだけになります。

@c TODO Add example

@subsubsubheading オクターブ移調付きの音部記号

@cindex transposed clef, visibility of (オクターブ移調付きの音部記号の可視性)
@cindex visibility of transposed clef (オクターブ移調付きの音部記号の可視性)
@cindex clef, visibility of transposition (オクターブ移調付きの音部記号の可視性)

オクターブ移調付きの音部記号上の小さな移調記号は
@code{ClefModifier} レイアウト オブジェクトによって作り出されます。@c
このオブジェクトの可視性は
@code{Clef} オブジェクトの可視性とは独立して制御されます。@c
そのため、各行の先頭においてそのような音部記号を完全に消そうとするなら、@c
@code{Clef} オブジェクトと @code{ClefModifier} オブジェクトの両方に対して@c
必要な @code{break-visibility} のオーバライドを行う必要があります。

明示的な音部記号の変更では、@c
@code{explicitClefVisibility} プロパティが@c
音部記号とそれに関連する移調記号の両方を制御します。

@morerefs
学習マニュアル:
@rlearning{オブジェクトの可視性と色}


@node ライン スタイル
@subsection ライン スタイル
@translationof Line styles

いくつかの演奏指示子
-- 例えば、@i{rallentando}, @i{accelerando} それに @i{trills} など --
はテキストとして記述され、@c
線で (点線や波線の場合もあります) でいくつもの小節にわたって広がります。

これらはすべてグリッサンドと同じルーチンを用いてテキストと線を描きます。@c
そのため、それらの振る舞いの調整も同じように行います。@c
これらはスパナによって実現され、スパナを描くルーチンは
@code{ly:line-spanner::print} です。@c
このルーチンは 2 つの @i{スパン ポイント} の位置を決定し、@c
要求されたスタイルに応じてそれら 2 点の間に線を描きます。

利用可能なライン スタイルと、それらをどのように調整するかを示す例を挙げます。

@lilypond[ragged-right,verbatim,quote]
\relative {
  d''2 \glissando d'2
  \once \override Glissando.style = #'dashed-line
  d,2 \glissando d'2
  \override Glissando.style = #'dotted-line
  d,2 \glissando d'2
  \override Glissando.style = #'zigzag
  d,2 \glissando d'2
  \override Glissando.style = #'trill
  d,2 \glissando d'2
}
@end lilypond

スパナの終点の位置は各グラフィック オブジェクトごとに@c
オンザフライ (その場、その時々) で計算されますが、@c
それらをオーバライドすることもできます:

@c TODO Complete
@lilypond[ragged-right,verbatim,quote]
\relative {
  e''2 \glissando f
  \once \override Glissando.bound-details.right.Y = #-2
  e2 \glissando f
}
@end lilypond

グリッサンドの終点の @code{Y} には @code{-2} がセットされています。@c
@code{right} の代わりに @code{left} を指定することにより、@c
始点も同じように調整することができます。

@code{Y} がセットされていない場合、@c
その値はスパナが取り付けられるポイントの垂直位置から算出されます。

スパナに他の調整を行うことも可能です。@c
詳細は @ref{スパナ} を参照してください。


@node オブジェクトを回転させる
@subsection オブジェクトを回転させる
@translationof Rotating objects

レイアウト オブジェクトとマークアップ テキストの要素はどちらも@c
任意のポイントを中心にして任意の角度で回転させることができます。@c
しかしながら、回転させる方法はまったく異なります。

@menu
* レイアウト オブジェクトを回転させる::
* マークアップを回転させる::
@end menu

@node レイアウト オブジェクトを回転させる
@unnumberedsubsubsec レイアウト オブジェクトを回転させる
@translationof Rotating layout objects

@cindex rotating object (オブジェクトを回転させる)
@cindex object, rotating (オブジェクトを回転させる)

@code{grob-interface} をサポートするすべてのレイアウト オブジェクトは、@c
それらのオブジェクトの @code{rotation} プロパティを設定することにより、@c
回転させることができます。@c
これは 3 要素のリストをとります: 反時計回りの回転の角度、@c
オブジェクトの参照ポイントからの相対座標 x と y
(この座標が回転の中心になります) です。@c
回転の角度は @q{°}で指定し、座標は譜スペースで指定します。

回転の角度と回転の中心座標は、トライ＆エラーで決定する必要があります。

@cindex hairpin, angled (回転したヘアピン)
@cindex angled hairpin (回転したヘアピン)

レイアウト オブジェクトを回転させることが有用な状況はあまりありません。@c
以下の例は、有用であるかもしれないシチュエーションの 1 つを示しています:

@lilypond[quote,fragment,verbatim]
g4\< e' d'' f''\!
\override Hairpin.rotation = #'(15 -1 0)
g4\< e' d'' f''\!
@end lilypond

@node マークアップを回転させる
@unnumberedsubsubsec マークアップを回転させる
@translationof Rotating markup

すべてのマークアップ テキストは、@code{\rotate} コマンドを前に置くことにより、@c
任意の角度に回転させることができます。@c
このコマンドは 2 つの引数をとります: 反時計回りの回転の角度 @q{°} と、@c
回転させられるテキストです。@c
テキストの領域は回転しません:
テキストの領域は回転させられるテキストの四隅になります。@c
以下の例では、自動衝突回避を不可にするために@c
テキストの @code{outside-staff-priority} プロパティに @code{#f} を@c
セットしています。@c
そうしなければテキストのいくつかは高く押し上げられてしまいます。

@lilypond[quote,fragment,verbatim]
\override TextScript.outside-staff-priority = ##f
g4^\markup { \rotate #30 "a G" }
b^\markup { \rotate #30 "a B" }
des'^\markup { \rotate #30 "a D-Flat" }
fis'^\markup { \rotate #30 "an F-Sharp" }
@end lilypond


@node 高度な調整
@section 高度な調整
@translationof Advanced tweaks

このセクションでは、@c
楽譜の見た目を細かく調節するためのさまざまなアプローチについて議論します。

@menu
* オブジェクトを揃える::
* グラフィカル オブジェクトを垂直方向にグループ化する::
* ステンシルを変更する::
* 形状を変更する::
* 改行するスパナを変更する::
* unpure-pure コンテナ::
@end menu

@morerefs
学習マニュアル:
@rlearning{出力を調整する},
@rlearning{その他の情報源}

記譜法リファレンス:
@ref{内部リファレンスの説明},
@ref{プロパティを変更する}

拡張:
@rextend{Interfaces for programmers}

インストールされているファイル:
@file{scm/define-grobs.scm}

コード断片集:
@rlsr{Tweaks and overrides}

内部リファレンス:
@rinternals{All layout objects}


@node オブジェクトを揃える
@subsection オブジェクトを揃える
@translationof Aligning objects

@code{self-alignment-interface} と/あるいは @code{side-position-interface} を@c
サポートするグラフィカル オブジェクトは、@c
さまざまな形式で配置済みのオブジェクトに揃えることができます。@c
そのようなオブジェクトのリストは、@rinternals{self-alignment-interface} と
@rinternals{side-position-interface} を参照してください。@c

すべてのグラフィカル オブジェクトは参照ポイント、水平方向の広がり、@c
それに垂直方向の広がりを持ちます。@c
水平方向の広がりは、@c
参照ポイントから左端と右端までの距離を意味する数値のペアであり、@c
左端は負値です。@c
垂直方向の広がりは、@c
参照ポイントから下端と上端までの距離を意味する数値のペアであり、@c
下端は負値です。@c

あるオブジェクトの譜面上の位置は、@code{X-offset} プロパティと
@code{Y-offset} プロパティの値によって与えられます。@c
@code{X-offset} の値は、親オブジェクトの参照ポイントの X 座標からの@c
距離を意味します。@c
@code{Y-offset} の値は、譜の中央線からの距離を意味します。@c
@code{X-offset} と @code{Y-offset} の値は直接設定されることもありますし、@c
いくつかの形式で親オブジェクトと揃えるために@c
プロシージャによって算出されることもあります。

@c positioning considerations: 配置のための考慮 -> 配置規則
@warning{多くのオブジェクトは特殊な配置規則を持っています。@c
そのため、そのオブジェクトが @code{self-alignment-interface} を@c
サポートしていたとしても、@c
@code{X-offset} あるいは @code{Y-offset} の設定は無視されたり、@c
変更されることがあります。}

例えば、臨時記号は @code{Y-offset} を設定することにより@c
垂直方向の位置を変更することができますが、@code{X-offset} は効果を持ちません。

リハーサル記号は、小節線、音部記号、拍子記号それに調号などの@c
改行可能なオブジェクトに揃えることができます。@c
リハーサル記号をそのようなオブジェクトに合わせて配置するために、@c
@code{break-aligned-interface} の中に特別なプロパティがあります。

@morerefs
記譜法リファレンス:
@ref{break-alignable-interface を使用する},

拡張:
@rextend{Callback functions}

@menu
* X-offset と Y-offset を直接設定する::
* side-position-interface を使用する::
* self-alignment-interface を使用する::
* break-alignable-interface を使用する::
@end menu

@node X-offset と Y-offset を直接設定する
@unnumberedsubsubsec @code{X-offset} と @code{Y-offset} を直接設定する
@translationof Setting X-offset and Y-offset directly

多くのオブジェクトの @code{X-offset} プロパティと @code{Y-offset} プロパティに@c
数値を与えることができます。@c
以下の例は、3 つの音符を示していて、1 つはデフォルト配置の運指記号を持ち、@c
他の 2 つの運指記号は @code{X-offset} と @code{Y-offset} が変更されています。

@lilypond[verbatim,fragment,quote]
a'-3
a'
-\tweak X-offset #0
-\tweak Y-offset #0
-3
a'
-\tweak X-offset #-1
-\tweak Y-offset #1
-3
@end lilypond

@c TODO write more

@node side-position-interface を使用する
@unnumberedsubsubsec @code{side-position-interface} を使用する
@translationof Using the @code{side-position-interface}

@code{side-position-interface} をサポートするオブジェクトは、@c
その親オブジェクトの隣に配置することができ、@c
それにより、@c
それら 2 つのオブジェクトの指定された端をくっつけることができます。@c
オブジェクトを親オブジェクトの上、下、右、あるいは左に配置することができます。@c
親オブジェクトを指定することはできません:
親オブジェクトは入力ストリームの中での要素の順序によって決定されます。@c
たいていのオブジェクトの親オブジェクトは、@c
そのオブジェクトに関連する符頭となります。

@code{side-axis} プロパティと @code{direction} プロパティの値は、@c
以下のように、オブジェクトが配置される場所を決定します:

@c TODO add an example of each to the table

@multitable @columnfractions .3 .3 .3
@headitem @code{side-axis}  @tab @code{direction}  @tab
@headitem property          @tab property          @tab Placement

@item     @code{0}          @tab @code{-1}         @tab 左
@item     @code{0}          @tab @code{1}          @tab 右
@item     @code{1}          @tab @code{-1}         @tab 下
@item     @code{1}          @tab @code{1}          @tab 上

@end multitable

@code{side-axis} が @code{0} である場合、@code{X-offset} には@c
プロシージャ @code{ly:side-position-interface::x-aligned-side} を@c
セットする必要があります。@c
このプロシージャは、@code{direction} の値に基づいて@c
親オブジェクトの左あるいは右にオブジェクトを配置するための適切な値を
@code{X-offset} に返します。

@code{side-axis} が @code{1} である場合、@code{Y-offset} には@c
プロシージャ @code{ly:side-position-interface::y-aligned-side} を@c
セットする必要があります。@c
このプロシージャは、@code{direction} の値に基づいて@c
親オブジェクトの上あるいは下にオブジェクトを配置するための適切な値を
@code{Y-offset} に返します。

@c TODO Add examples

@node self-alignment-interface を使用する
@unnumberedsubsubsec @code{self-alignment-interface} を使用する
@translationof Using the @code{self-alignment-interface}

@subsubsubheading オブジェクトを自動的に水平方向に揃える

@code{self-alignment-interface} をサポートするオブジェクトの水平方向の揃えは、@c
@code{self-alignment-X} プロパティの値によって制御され、@c
そのオブジェクトの @code{X-offset} プロパティには@c
@code{ly:self-alignment-interface::x-aligned-on-self} がセットされています。
@code{self-alignment-X} には@c
任意の実数値を与えることができますが、
与える値は、そのオブジェクトの X 方向の広がりの半分を単位とします。@c
負値はオブジェクトを右に移動させ、正値はオブジェクトを左に移動させます。@c
値が @code{0} であればそのオブジェクトは親オブジェクトの参照ポイントに@c
中央揃えされ、@c
値が @code{-1} であればそのオブジェクトの左端が親オブジェクトの参照ポイントに@c
揃えられ、@c
値が @code{1} であればそのオブジェクトの右端が親オブジェクトの参照ポイントに@c
揃えられます。@c
記号 @code{LEFT}, @code{CENTER}, それに @code{RIGHT} は@c
それぞれ @w{@code{-1}, @code{0}, それに @code{1}} に対応します。

通常、@code{\override} コマンドを用いて @code{self-alignment-X} の値を@c
変更しますが、@c
@code{\tweak} コマンドを用いることで@c
単一の音符に付けられている複数の注釈を個別に揃えることができます:

@lilypond[quote,verbatim,fragment]
a'
-\tweak self-alignment-X #-1
^"left-aligned"
-\tweak self-alignment-X #0
^"center-aligned"
-\tweak self-alignment-X #RIGHT
^"right-aligned"
-\tweak self-alignment-X #-2.5
^"aligned further to the right"
@end lilypond

@subsubsubheading オブジェクトを自動的に垂直方向に揃える

オブジェクトの @code{Y-offset} プロパティに
@code{ly:self-alignment-interface::y-aligned-on-self} がセットされていれば、@c
水平方向の揃えと同じように、垂直方向に揃えることができます。@c
しかしながら、垂直方向の揃えには他のメカニズムも関与します:
@code{Y-offset} の値は、垂直方向の揃えに関与する変数の 1 つに過ぎません。@c
このことにより、いくつかのオブジェクトの @code{Y-offset} 値の調整は@c
ややこしくなります。@c
単位はそのオブジェクトの垂直方向の広がりの半分です。@c
通常これは非常に小さいため、非常に大きな数値が必要になる可能性があります。@c
値が @code{-1} であればそのオブジェクトの下端が親オブジェクトの参照ポイントに@c
揃えられ、@c
値が @code{0} であればそのオブジェクトの中央が親オブジェクトの参照ポイントに@c
揃えられ、@c
値が @code{1} であればそのオブジェクトの上端が親オブジェクトの参照ポイントに@c
揃えられます。@c
記号 @code{DOWN}, @code{CENTER}, それに @code{UP} は@c
それぞれ @w{@code{-1}, @code{0}, それに @code{1}} に対応します。

@subsubsubheading オブジェクトを自動的に両方向に揃える

@code{X-offset} と @code{Y-offset} の両方の設定を行うことで、@c
オブジェクトの水平方向と垂直方向の揃えを同時に行うことができます。

以下の例は、運指記号を符頭に近づけるための調整方法を示しています。

@c KEEP LY
@lilypond[quote,verbatim,fragment]
a'
-\tweak self-alignment-X #0.5  % 左方向に移動させます
-\tweak Y-offset #ly:self-alignment-interface::y-aligned-on-self
-\tweak self-alignment-Y #-1  % 上方向に移動させます
-3  % 3 の指
@end lilypond

@ignore
@unnumberedsubsubsec Using the @code{aligned-on-parent} procedures

@c Cannot document as they do not seem to operate consistently on all objects -td
@c TODO investigate further

The @code{aligned-on-parent} procedures are used in the same way
as the @code{aligned-on-self} procedures, they difference being
that they permit an object to be aligned with the @emph{edges} of
the parent rather than the parent's reference point.  The following
example shows the difference:

@c TODO Add example

@lilypond[verbatim,quote]
@end lilypond

@end ignore

@ignore
@unnumberedsubsubsec Using the @code{centered-on-parent} procedures

@c Cannot document as they do not seem to operate consistently on all objects -td
@c TODO investigate further

@end ignore

@c TODO The align-interface, BassFigureAlignment and VerticalAlignment

@node break-alignable-interface を使用する
@unnumberedsubsubsec @code{break-alignable-interface} を使用する
@translationof Using the @code{break-alignable-interface}

@cindex align to object (オブジェクトに揃える)
@funindex break-align-symbols

リハーサル記号と小節番号を小節線ではなく、@c
記譜オブジェクトに揃えることができます。@c
対象となる記譜オブジェクトには、@code{ambitus},
@code{breathing-sign}, @code{clef}, @code{custos}, @code{staff-bar},
@code{left-edge}, @code{key-cancellation}, @code{key-signature}, それに
@code{time-signature} があります。

それぞれの記号は、リハーサル記号が揃えられる@c
デフォルトの参照点を持ち、その位置は種類ごとに異なります。

@c KEEP LY
@lilypond[verbatim,quote,fragment]
% リハーサル記号は音部記号の右端に揃えられます
\override Score.RehearsalMark.break-align-symbols = #'(clef)
\key a \major
\clef treble
\mark "↓"
e'1
% リハーサル記号は拍子記号の左端に揃えられます
\override Score.RehearsalMark.break-align-symbols = #'(time-signature)
\key a \major
\clef treble
\time 3/4
\mark "↓"
e'2.
% リハーサル記号はブレス記号の中央に揃えられます
\override Score.RehearsalMark.break-align-symbols = #'(breathing-sign)
\key a \major
\clef treble
\time 4/4
e'1
\breathe
\mark "↓"
@end lilypond

揃えの対象となり得るオブジェクトのリストを指定することができます。@c
揃えを行う時点で対象リストの中にあるオブジェクトのいくつかが不可視である
-- @code{break-visibility} の設定や、@c
調号と音部に対する明示的な可視性の設定により --
場合、リハーサル記号あるいは小節番号はリストの中にある@c
最初の可視のオブジェクトに揃えられます。@c
リストの中にあるオブジェクトがすべて不可視である場合、小節線に揃えられます。@c
小節線が不可視である場合、小節線があるはずの場所に揃えられます。

@c KEEP LY
@lilypond[verbatim,quote,fragment]
% リハーサル記号は調号の右端に揃えられます
\override Score.RehearsalMark.break-align-symbols = #'(key-signature clef)
\key a \major
\clef treble
\mark "↓"
e'1
% リハーサル記号は音部記号の右端に揃えられます
\set Staff.explicitKeySignatureVisibility = #all-invisible
\override Score.RehearsalMark.break-align-symbols = #'(key-signature clef)
\key a \major
\clef bass
\mark "↓"
gis,1
% リハーサル記号は小節線の中央に揃えられます
\set Staff.explicitKeySignatureVisibility = #all-invisible
\set Staff.explicitClefVisibility = #all-invisible
\override Score.RehearsalMark.break-align-symbols = #'(key-signature clef)
\key a \major
\clef treble
\mark "↓"
e'1
@end lilypond

以下の例で示すように、@c
記譜オブジェクトに対するリハーサル記号の揃えを変更することができます。@c
複数の譜を持つ楽譜では、この設定はすべての譜に適用されます。

@c KEEP LY
@lilypond[verbatim,quote,fragment]
% リハーサル記号は調号の右端に揃えられます
\override Score.RehearsalMark.break-align-symbols = #'(key-signature)
\key a \major
\clef treble
\time 4/4
\mark "↓"
e'1
% リハーサル記号は調号の中央に揃えられます
\once \override Score.KeySignature.break-align-anchor-alignment = #CENTER
\mark "↓"
\key a \major
e'1
% リハーサル記号は調号の左端に揃えられます
\once \override Score.KeySignature.break-align-anchor-alignment = #LEFT
\key a \major
\mark "↓"
e'1
@end lilypond

また、リハーサル記号を左端に揃えて、@c
さらに任意の量だけ右あるいは左にずらすことができます。@c
単位は譜スペースです:

@c KEEP LY
@lilypond[verbatim,quote,fragment]
% リハーサル記号は調号の左端に揃えられて
% さらに 3.5 譜スペース右にずらされます
\override Score.RehearsalMark.break-align-symbols = #'(key-signature)
\once \override Score.KeySignature.break-align-anchor = #3.5
\key a \major
\mark "↓"
e'1
% リハーサル記号は調号の左端に揃えられて
% さらに 2 譜スペース左にずらされます
\once \override Score.KeySignature.break-align-anchor = #-2
\key a \major
\mark "↓"
e'1
@end lilypond


@node グラフィカル オブジェクトを垂直方向にグループ化する
@subsection グラフィカル オブジェクトを垂直方向にグループ化する
@translationof Vertical grouping of grobs

@c FIXME Expand this section

VerticalAlignment グラフィカル オブジェクトと
VerticalAxisGroup グラフィカル オブジェクトは対で機能します。@c
VerticalAxisGroup は Staff, Lyrics, 等のような@c
異なるグラフィカル オブジェクトをグループにまとめます。@c
それから、VerticalAlignment が
VerticalAxisGroup によってグループ化されたグラフィカル オブジェクトを@c
垂直方向に揃えます。@c
通常、楽譜には VerticalAlignment は 1 つしかありませんが、@c
Staff, Lyrics 等はそれ自体でそれぞれに VerticalAxisGroup を持ちます。


@node ステンシルを変更する
@subsection ステンシルを変更する
@translationof Modifying stencils

すべてのレイアウト オブジェクトは、@c
@code{grob-interface} の一部である @code{stencil} プロパティを持ちます。@c
通常、デフォルトでこのプロパティには、@c
出力でそのオブジェクトを具現化する記号を描画するための@c
特有の関数がセットされています。@c
例えば、@code{MultiMeasureRest} オブジェクトの @code{stencil} プロパティに@c
対する標準設定は、@code{ly:multi-measure-rest::print} です。

@code{stencil} プロパティを変更して異なる描画関数を参照させることにより、@c
オブジェクトの標準記号を置き換えることができます。@c
これには LilyPond 内部機能についての高い知識が求められます。@c
しかしながら、多くの場合にまずまずの結果を生み出すもっと簡単な方法があります。

簡単な方法では、@code{stencil} プロパティにテキストを描画する関数
-- @code{ly:text-interface::print} -- をセットし、@c
必要な記号を生み出すマークアップ テキストを保持するよう設定された
 @code{text} プロパティ与えます。@c
マークアップの自由度の高さにより、多くのことを達成できます。@c
詳細は、@ref{マークアップ内部でのグラフィック記譜法} を参照してください。

以下の例では、この方法を用いて符頭記号を内部に×を持つ円に変更しています。

@lilypond[verbatim,quote]
XinO = {
  \once \override NoteHead.stencil = #ly:text-interface::print
  \once \override NoteHead.text = \markup {
    \combine
      \halign #-0.7 \draw-circle #0.85 #0.2 ##f
      \musicglyph "noteheads.s2cross"
  }
}
\relative {
  a' a \XinO a a
}
@end lilypond

@code{\musicglyph} マークアップ コマンドで、@c
Emmentaler フォントに含まれる任意の @emph{Feta}
グリフを使用することができます。@c
@ref{The Emmentaler font} を参照してください。

@file{EPS} ファイルや Postscript コマンドを、それぞれ
@code{\epsfile} や @code{\postscript} マークアップ コマンドを使って@c
行内に埋め込むことができます。@c
@ref{Graphic} を参照してください。

@morerefs
記譜法リファレンス:
@ref{マークアップ内部でのグラフィック記譜法},
@ref{テキストをフォーマットする},
@ref{Text markup commands},
@ref{The Emmentaler font},
@ref{Graphic}


@node 形状を変更する
@subsection 形状を変更する
@translationof Modifying shapes

@menu
* タイとスラーの形状を変更する::
@end menu

@node タイとスラーの形状を変更する
@unnumberedsubsubsec タイとスラーの形状を変更する
@translationof Modifying ties and slurs

@cindex slur, modifying (スラーの形状を変更する)
@cindex tie, modifying (タイの形状を変更する)
@cindex Bézier curve, control points (ベジエ曲線の制御ポイント)
@cindex control point, Bézier curve (ベジエ曲線の制御ポイント)

@code{Tie}, @code{Slur}, @code{PhrasingSlur}, @code{LaissezVibrerTie},
それに @code{RepeatTie} はすべて 3 次のベジエ曲線として描かれます。@c
自動的に算出されるタイやスラーの形状が最適ではない場合、以下の 2 つの@c
方法を用いて手動で形状を変更することができます:@c

@enumerate a
@item
自動的に算出されるベジエ曲線の制御ポイントの移動させる

@item
求める曲線を定義するのに必要な 4 つの制御ポイントの位置を明示的に指定する
@end enumerate

2 つの方法について以下で説明します。@c
曲線の調節がわずかであれば、最初の方法が適しています。@c
2 番目の方法は単一の音符に関連付けられる曲線を作り出す場合に適しています。

@subsubsubheading 3 次ベジエ曲線

3 次あるいは 3 乗のベジエ曲線は、4 つの制御ポイントによって定義されます。@c
1 番目と 4 番目の制御ポイントは曲線の始点と終点になります。@c
間にある 2 つの制御ポイントは曲線の形状を定義します。@c
Web でベジエ曲線が描かれる様子を示すアニメーションを@c
見つけることができるでしょう。@c
しかしながら、以下の記述も役に立つかもしれません。@c
ベジエ曲線は最初の制御ポイントから 2 番目の制御ポイントに進み、@c
徐々に 3 番目の制御ポイントの方へ向きを変えながら
4 番目の制御ポイントの方へ向かい続け、@c
3 番目の制御ポイントから 4 番目の制御ポイントに到達します。@c
ベジエ曲線は 4 つの制御ポイントからなる四角形の中に納まります。@c
制御ポイントの平行移動、回転、伸縮はすべて同じ操作です。

@subsubsubheading 制御ポイントを移動させる

@cindex shaping slurs and ties (スラーとタイの形状)
@funindex \shape

以下の例では、タイの自動配置が最適ではなく、@code{\tieDown} も役に@c
立ちません。

@lilypond[verbatim,quote]
<<
  { e'1~ 1 }
\\
  \relative { r4 <g' c,> <g c,> <g c,> }
>>
@end lilypond

@code{\shape} でタイの制御ポイントを調節することで衝突を避けることが@c
できます。

@code{\shape} の構文は以下の通りです:

@example
[-]\shape @var{displacements} @var{item}
@end example

これは @var{item} の制御ポイントを @var{displacements} だけ移動させます。@c
引数 @var{displacements} は数のペアのリスト、あるいはそのようなリストの@c
リストです。@c
ペアの要素は制御ポイントの座標の移動量を表しています。@c
@var{item} が文字列の場合、指定されたグラフィカル オブジェクト タイプ@c
に @code{\once \override} で適用されます。@c
@var{item} が音楽表記の場合、その音楽表記に調節が適用されます。

言い換えると、@code{\shape} 関数は、引数 @var{item} が @qq{Slur}
のようなグラフィカル オブジェクト名であるか @qq{(} のような音楽表記@c
であるかによって、@code{\once \override} コマンドあるいは @code{\tweak}
コマンドのどちらにでもなり得ます。@c
引数 @var{displacements} は 4 つの (dx . dy) ペアのリストで 4 つの@c
制御ポイントの移動を指定します -- 値の単位は譜スペースです。
(曲線が複数のセグメントを持つ場合、引数 @var{displacements} は 4 つの@c
ペアを持つリストのリストになります。)

@code{\tweak} 形式で用いる場合にのみ、先頭にハイフン @code{-} を付ける@c
必要があります。

それでは、上記の例に @code{\once \override} 形式の @code{\shape} を@c
使ってタイを 0.5 譜スペースだけ上に移動させてみましょう:

@lilypond[verbatim,quote]
<<
  {
    \shape #'((0 . 0.5) (0 . 0.5) (0 . 0.5) (0 . 0.5)) Tie
    e'1~ 1
  }
\\
  \relative { r4 <g' c,> <g c,> <g c,> }
>>
@end lilypond

タイの位置は改善されましたが、中央部分をもっと持ち上げるべきです。@c
以下の例で @code{\tweak} 形式でそれを行っています:

@lilypond[verbatim,quote]
<<
  {
    e'1-\shape #'((0 . 0.5) (0 . 1) (0 . 1) (0 . 0.5)) ~ e'
  }
\\
  \relative { r4 <g' c,> <g c,> <g c,> }
>>
@end lilypond

同じ方法で制御ポイントを水平方向に移動させることもできて、同じ音楽@c
タイミングで発生する 2 つの曲線をうまく配置することができます:

@lilypond[verbatim,quote,ragged-right]
\relative {
  c''8(\( a) a'4 e c\)
  \shape #'((0.7 . -0.4) (0.5 . -0.4) (0.3 . -0.3) (0 . -0.2)) Slur
  \shape #'((0 . 0) (0 . 0.5) (0 . 0.5) (0 . 0)) PhrasingSlur
  c8(\( a) a'4 e c\)
}
@end lilypond

@code{\shape} 関数は改行を跨ぐ曲線の制御ポイントを移動させることも@c
できます。@c
分割される曲線それぞれにリストを与えて制御ポイントを移動させます。@c
片方の曲線は変更する必要がない場合、空のリストを渡します。@c
以下の例では、1 つのスラーが改行で 2 つに分割されています:

@lilypond[verbatim,quote,ragged-right]
\relative {
  c'4( f g c
  \break
  d,4 c' f, c)
}
@end lilypond

分割されたスラーの形状を変更することで、改行を跨いで続くスラーである@c
ことがわかりやすくなります:

@c KEEP LY
@lilypond[verbatim,quote,ragged-right]
% 片方のスラーを変更する必要がない場合、
% () を ((0 . 0) (0 . 0) (0 . 0) (0 . 0)) の短縮形として使うことができます
\relative c' {
  \shape #'(
             (( 0 . 0) (0 . 0) (0 . 0) (0 . 1))
             ((0.5 . 1.5) (1 . 0) (0 . 0) (0 . -1.5))
           ) Slur
  c4( f g c
  \break
  d,4 c' f, c)
}
@end lilypond

S 字曲線が求められた場合は、常に制御ポイントを手動で調節する必要があります
--- LilyPond が自動的にそのような形状を選択することはありません。

@lilypond[verbatim,quote]
\relative c'' {
  c8( e b-> f d' a e-> g)
  \shape #'((0 . -1) (5.5 . -0.5) (-5.5 . -10.5) (0 . -5.5)) PhrasingSlur
  c8\( e b-> f d' a e-> g\)
}
@end lilypond

@subsubsubheading 制御ポイントの位置を明示的に指定する

ベジエ曲線の制御ポイントの座標を指定します -- 単位は譜スペースです。@c
X@tie{}座標はタイあるいはスラーを取り付ける音符の参照ポイントからの@c
相対位置で、X@tie{}座標は譜の中央線からの相対位置です。@c
制御ポイントの座標をリストで指定します -- リストは数のペアを 4 つ持ちます。@c
両端の座標を推測して、それから 2 つ中間点の座標を推測します。@c
最適値はトライ＆エラーで見つけます。@c
音楽やレイアウトに変更が加えられた場合、手動で値を調節する必要がある@c
ということに注意してください。

制御ポイントを移動させるよりも、位置を明示的に指定する方が望ましい@c
シチュエーションの 1 つは、単一の音符に関連付けられる曲線の場合です。@c
ここで、そのような例を示します。@c
繰り返しの差し替え部分まで延びるスラーを表示する方法を示しています。

@c KEEP LY
@lilypond[verbatim,quote]
\relative {
  c''1
  \repeat volta 3 { c4 d( e f }
  \alternative {
    { g2) d }
    {
      g2
      % スラーを作成して、新しい位置に移動させます
      % <> はスラーを終わらせるための空の和音です
      -\tweak control-points #'((-2 . 3.8) (-1 . 3.9) (0 . 4) (1 . 3.4)) ( <> )
      f,
    }
    {
      e'2
      % スラーを作成して、新しい位置に移動させます
      -\tweak control-points #'((-2 . 3) (-1 . 3.1) (0 . 3.2) (1 . 2.4)) ( <> )
      f,
    }
  }
}
@end lilypond

@knownissues
同じ音楽タイミングに複数のタイあるいはスラーが存在する場合、@c
@code{control-points} プロパティを変更しても@c
それらの形状を変更することはできません。@c
@code{\tweak} コマンドを用いたとしても変更できません。@c
しかしながら、@code{TieColumn} の @code{tie-configuration} プロパティを@c
オーバライドすることで、タイの垂直方向の位置と領域を変更することができます。

@morerefs
内部リファレンス:
@rinternals{TieColumn}


@node 改行するスパナを変更する
@subsection 改行するスパナを変更する
@translationof Modifying broken spanners

@menu
* alterBroken を使用する::
@end menu

@node alterBroken を使用する
@unnumberedsubsubsec @code{\alterBroken} を使用する
@translationof Using alterBroken

@cindex spanner, modifying (スパナを変更する)
@cindex broken spanner, modifying (改行するスパナを変更する)
@funindex \alterBroken

スパナが改行や改ページにまたがる場合、それぞれの部分は元のスパナの属性を@c
受け継ぎます。そのため、通常と同じようにスパナを変更することで、@c
改行するスパナの各部分を変更することができます。下の例では
@code{thickness} をオーバライドしていますが、改行するスラーの両方の部分が@c
変更されています。

@lilypond[verbatim,quote,ragged-right]
\relative c'' {
  r2
  \once\override Slur.thickness = 10
  c8( d e f
  \break
  g8 f e d) r2
}
@end lilypond

@code{\alterBroken} コマンドを用いることで、改行するスパナの各部分を@c
それぞれ独立して変更することができます。このコマンドはスパナのプロパティを
@code{\override} あるいは @code{\tweak} することができます。

@code{\alterBroken} の構文は:

@example
[-]\alterBroken @var{property} @var{values} @var{item}
@end example

引数 @var{values} は値のリストを取り、スパナの各部分に対応します。@c
@var{item} が @code{Slur} や @code{Staff.PianoPedalBracket} のような
Grob の名前である場合、結果はその Grob の @code{\override} となります。@c
@var{item} が @qq{(} や @qq{[} のような音楽表記である場合、@c
@code{\tweak} が適用された音楽表記が出力されます。

@code{\tweak} 形では前にハイフンが必要です。@code{\alterBroken} を
@code{\override} として用いる場合には、ハイフンを付けないでください。

@funindex \once
@funindex \temporary

@code{\override} として使用する場合、@code{\alterBroken} は
@code{\once} や @code{\temporary} を前置することができ、@c
@code{\revert} で元に戻すことができます
(@rextend{Intermediate substitution functions} を参照してください)。

次のコードは、前の例におけるスラーの各部分をそれぞれ @code{\override}
しています。

@lilypond[verbatim,quote,ragged-right]
\relative c'' {
  r2
  \alterBroken thickness #'(10 1) Slur
  c8( d e f
  \break
  g8 f e d) r2
}
@end lilypond

@code{\alterBroken} コマンドは全てのスパナに対して用いることができます
(例えば @code{Tie}, @code{PhrasingSlur}, @code{Beam}, @code{TextSpanner}
などです)。例えば、校訂譜を作成する際には、原典に無いスラーを追加する際に@c
点線で表示させたいことがあります。次の例ではこれをどのように実現するかを@c
示しており、今回は @code{\tweak} 形を用いています:

@c KEEP LY
@lilypond[verbatim,quote,ragged-right]
% 空リストが dash-definition のデフォルト設定であり、
% 繋がった曲線が出力されます
\relative {
  c''2-\alterBroken dash-definition #'(() ((0 1.0 0.4 0.75))) \(e
  \break
  g2 e\)
}
@end lilypond

@code{\alterBroken} において、@var{values} のリストの各要素が@c
スパナの各部分のプロパティに影響するということは重要です。@c
もしスパナの要素数よりも少ない数の値がセットされていた場合、@c
残りの部分は空リストがセットされたとして扱われます。この時、@c
プロパティのデフォルト値が空リストではない場合には意図しない結果を@c
もたらす可能性があります。そのような場合には、各部分について正しい値を@c
セットしてください。

@knownissues
レイアウトが変更された場合、改行の位置も変更されることがあります。@c
このように改行位置が変更されて、スパナの跨る行数が増減した場合、@c
@code{\alterBroken} の設定は適切ではなくなるでしょう。明示的に @code{\break}
を用いることによってこれを防止します。

@code{\alterBroken} コマンドは、@code{direction} のように、改行処理の前に@c
アクセスされるプロパティに対しては効果がありません。

@morerefs
拡張:
@rextend{Difficult tweaks}


@node unpure-pure コンテナ
@subsection unpure-pure コンテナ
@translationof Unpure-pure containers

@cindex Scheme, pure container (Scheme pure コンテナ)
@cindex Scheme, unpure container (Scheme unpure コンテナ)
@cindex pure container, Scheme (Scheme pure コンテナ)
@cindex unpure container, Scheme (Scheme unpure コンテナ)
@cindex horizontal spacing, overriding (水平方向のスペースを上書きする)

unpure-pure コンテナは @emph{Y-axis} スペース - 特に @code{Y-offset} と
@code{Y-extent} - の算出をリテラル (つまり、数字やペア) ではなく、Scheme 関数で@c
上書きする際に有用です。

ある特定のグラフィカル オブジェクトでは、@code{Y-extent} は @code{stencil}
プロパティをベースにしていて、それらの @code{stencil} プロパティを上書きする場合は
unpure-pure コンテナで @code{Y-extent} も上書きする必要があります。@c
関数によって @code{Y-offset} と/または @code{Y-extent} を上書きした場合、@c
その関数はコンパイルの最中の早すぎるタイミングで、@c
改行の算出が行われるものと見なされます。@c
そのため、その関数はまったく評価されず (通常、@samp{0} または @samp{'(0 . 0)} の@c
値を返します)、結果として衝突を引き起こすことがあります。@c
@q{pure} 関数はプロパティ、オブジェクト、あるいはグラフィカル オブジェクトの消失に@c
影響を与えないため、その関数の Y-axis に関する評価は常に正しく行われます。

現在のところ @q{pure} と見なされる関数が約 30 あり、Unpure-pure コンテナを用いて
@q{pure} ではない関数を @q{pure} な関数としてセットすることができます。@c
@q{pure} 関数は改行の @emph{前に} 評価されるため、水平方向のスペースを
@q{正しいタイミングで} 調節することができます。@c
@q{unpure} 関数は改行の @emph{後に} 評価されます。

@warning{どの関数が @q{pure} であるかを常に把握していることは困難なので、作成する @q{pure}
関数ではグラフィカル オブジェクト @code{Beam} や @code{VerticalAlignment} を@c
使わないことをおすすめします。}

unpure-pure コンテナは以下のように構築します:

@code{(ly:make-unpure-pure-container f0 f1)}

ここで @code{f0} は @var{n} (@var{n >= 1}) 個の引数を取る関数であり、最初の引数@c
は常にグラフィカル オブジェクトである必要があります。@c
これが実際に結果を返す関数です。@c
@code{f1} は @q{pure} であると見なされる関数であり、@var{n + 2} 個の引数を@c
取ります。@c
@code{f1} も最初の引数は常にグラフィカル オブジェクトである必要があり、2 番目と
3 番目の引数は @q{start} と @q{end} です。

@var{start} と @var{end} は事実上、@code{Spanners} (つまり、@code{Hairpin} や
@code{Beam}) だけで問題となるダミー値であり、スパナが開始あるいは終了する段@c
によって、高さの予想値が異なってくる場合に使用されるものです。

@code{f1} の残りの引数は @code{f0} の引数と同じです (@var{n = 1} である場合は@c
残りの引数はありません)。

関数 @code{f1} の結果は概算であり、@code{f0} が実際の値を得るのに用いられます。@c
@code{f0} の結果はもっと後のスペースの処理で微調整に用いられます。

@c TODO: The following example supposedly showing a collision no longer
@c 'works' since 2.18.x. Another example of a collision is needed.
@c Issue #3512

@lilypond[verbatim,quote,ragged-right]
#(define (square-line-circle-space grob)
(let* ((pitch (ly:event-property (ly:grob-property grob 'cause) 'pitch))
      (notename (ly:pitch-notename pitch)))
 (if (= 0 (modulo notename 2))
     (make-circle-stencil 0.5 0.0 #t)
     (make-filled-box-stencil '(0 . 1.0)
                              '(-0.5 . 0.5)))))

squareLineCircleSpace = {
  \override NoteHead.stencil = #square-line-circle-space
}

smartSquareLineCircleSpace = {
  \squareLineCircleSpace
  \override NoteHead.Y-extent =
   #(ly:make-unpure-pure-container
      ly:grob::stencil-height
      (lambda (grob start end) (ly:grob::stencil-height grob)))
}

\new Voice \with { \remove Stem_engraver }
\relative c'' {
  \squareLineCircleSpace
  cis4 ces disis d
  \smartSquareLineCircleSpace
  cis4 ces disis d
}
@end lilypond

最初の小節では unpure-pure コンテナを用いていないため、スペース算出エンジンは符頭の@c
幅を知ることができず、符頭と臨時記号が衝突しています。@c
次の小節では unpure-pure コンテナを用いているため、スペース算出エンジンは符頭の幅を@c
知ることができ、それに応じて小節の幅を増やすことで衝突を回避しています。

通常、簡単な計算では、unpure-pure コンテナの @q{unpure} パートと @q{pure} パート@c
の両方に、引数の数とスコープを変えただけのほとんど同じ関数を用いることができます。@c
このように使用されることが多いため、@code{ly:make-unpure-pure-container} に@c
関数を 1 つだけ与えた場合、デフォルトで同じ関数を用いてコンテナを作り出します。

@warning{@q{pure} と見なした関数が @q{pure} でなかった場合、予期しない結果となる@c
ことがあります。}


@node 音楽関数を使用する
@section 音楽関数を使用する
@translationof Using music functions

@c TODO -- add @morerefs, etc. to these subsections

調整を異なる音楽表記に再利用する必要がある場合、@c
その調整を音楽関数にしておくと便利です。@c
このセクションでは、@emph{置換} 関数についてだけ議論します。@c
置換関数は変数を LilyPond 入力コードに置き換えます。@c
他のもっと複雑な関数については、@rextend{Music functions} で記述されています。

@menu
* 置換関数の構文::
* 置換関数の例::
@end menu

@node 置換関数の構文
@subsection 置換関数の構文
@translationof Substitution function syntax

変数を LilyPond コードに置換する関数を作成することは簡単にできます。@c
置換関数の一般的な形式は以下のようなものです:

@example
function =
#(define-music-function
     (@var{arg1} @var{arg2} @dots{})
     (@var{type1?} @var{type2?} @dots{})
   #@{
     @var{@dots{}music@dots{}}
   #@})
@end example

@noindent
ここで

@multitable @columnfractions .33 .66
@item @code{@var{argN}}
@tab @var{n} 番目の引数

@item @code{@var{typeN?}}
@tab @code{@var{argN}} が @code{#t} を返す Scheme の @emph{型述語} (type predicate)。

@item @code{@var{@dots{}music@dots{}}}
@tab 通常の LilyPond 入力。引数を参照するには @code{$} (LilyPond 構造が@c
許可されている場合のみ) や @code{#} (引数を Scheme 値、音楽関数の引数、@c
あるいは音楽リスト内部の音楽として使う場合) を用います
(例: @samp{#arg1})。
@end multitable

です。

引数として、型述語のリストが必須です。@c
音楽関数で用いられる一般的な型述語には下記のものがあります:

@example
boolean?
cheap-list?  @emph{(}@q{list?}@emph{ の代わりに用いることで、処理を高速にします)}
ly:duration?
ly:music?
ly:pitch?
markup?
number?
pair?
string?
symbol?
@end example

@noindent
利用可能な型述語のリストは、@c
@ref{Predefined type predicates} を参照してください。@c
ユーザが型述語を定義することもできます。

@morerefs
記譜法リファレンス:
@ref{Predefined type predicates}

拡張:
@rextend{Music functions}

インストールされているファイル:
@file{lily/music-scheme.cc},
@file{scm/c++.scm},
@file{scm/lily.scm}


@node 置換関数の例
@subsection 置換関数の例
@translationof Substitution function examples

このセクションでは、置換関数の例をいくつか紹介します。@c
高度なことはしていませんが、シンプルな置換関数を実現する方法を示しています。

最初の例では、@c
@code{TextScript} のパディング設定を容易にするための関数が定義されています:

@lilypond[quote,verbatim,ragged-right]
padText =
#(define-music-function
     (padding)
     (number?)
   #{
     \once \override TextScript.padding = #padding
   #})

\relative {
  c''4^"piu mosso" b a b
  \padText #1.8
  c4^"piu mosso" b a b
  \padText #2.6
  c4^"piu mosso" b a b
}
@end lilypond

数値のほかに、音符などの音楽表記を音楽関数への引数にすることができます:

@lilypond[quote,verbatim,ragged-right]
custosNote =
#(define-music-function
     (note)
     (ly:music?)
   #{
     \tweak NoteHead.stencil #ly:text-interface::print
     \tweak NoteHead.text
        \markup \musicglyph "custodes.mensural.u0"
     \tweak Stem.stencil ##f
     #note
   #})

\relative { c'4 d e f \custosNote g }
@end lilypond

@funindex \etc
上に挙げた例の両方では、関数やオーバライドにおける最後の引数が空きに@c
なっているだけの、単一の式の形をしています。このような特別な場合では、@c
よりシンプルな関数の定義方法があり、一定の部分はそのまま書き出し、@c
引数となる最後の部分を @code{\etc} で置き換えるという書き方をします:

@lilypond[quote,verbatim,ragged-right]
padText =
  \once \override TextScript.padding = \etc

\relative {
  c''4^"piu mosso" b a b
  \padText #1.8
  c4^"piu mosso" b a b
  \padText #2.6
  c4^"piu mosso" b a b
}
@end lilypond

@lilypond[quote,verbatim,ragged-right]
custosNote =
  \tweak NoteHead.stencil #ly:text-interface::print
  \tweak NoteHead.text
     \markup \musicglyph "custodes.mensural.u0"
  \tweak Stem.stencil ##f
  \etc

\relative { c'4 d e f \custosNote g }
@end lilypond

複数の引数をとる置換関数を定義することもできます:

@lilypond[quote,verbatim,ragged-right]
tempoPadded =
#(define-music-function
     (padding tempotext)
     (number? markup?)
   #{
     \once \override Score.MetronomeMark.padding = #padding
     \tempo \markup { \bold #tempotext }
   #})

\relative {
  \tempo \markup { "Low tempo" }
  c''4 d e f g1
  \tempoPadded #4.0 "High tempo"
  g4 f e d c1
}
@end lilypond

@c TODO: add appropriate @@ref's here.
