@@ -4,24 +4,20 @@ use crate::diag::HintedStrResult;
44use crate :: engine:: Engine ;
55use crate :: foundations:: { func, Array , Context , LocatableSelector , Value } ;
66
7- /// Finds elements in the document.
7+ /// 文書中の要素の検索。
88///
9- /// The `query` functions lets you search your document for elements of a
10- /// particular type or with a particular label. To use it, you first need to
11- /// ensure that [context] is available.
9+ /// `query`関数を用いると特定の型やラベルを持った要素を文書内から探すことができます。
10+ /// 使用するにはまず[コンテキスト]($context)が利用可能であることを確かめる必要があります。
1211///
1312
14- /// # Finding elements
15- /// In the example below, we manually create a table of contents instead of
16- /// using the [`outline`] function.
13+ /// # 要素の探索
14+ /// 以下の例では、[`outline`]を用いる代わりに手動で目次を作成しています。
1715///
18- /// To do this, we first query for all headings in the document at level 1 and
19- /// where `outlined` is true. Querying only for headings at level 1 ensures
20- /// that, for the purpose of this example, sub-headings are not included in the
21- /// table of contents. The `outlined` field is used to exclude the "Table of
22- /// Contents" heading itself.
16+ /// このために、まず第1レベルの見出しで`outlined`がtrueなものを検索します。
17+ /// この例において第1レベルの見出しのみを検索する目的は、第2レベル以下の見出しが目次に含まれないようにすることです。
18+ /// `outlined`フィールドは"Table of Contents"という見出し自身を取り除くために使われます。
2319///
24- /// Note that we open a `context` to be able to use the `query` function.
20+ /// `query`関数を使用可能にするために、`context`を作成していることに注意してください。
2521///
2622/// ```example
2723/// >>> #set page(
@@ -62,29 +58,25 @@ use crate::foundations::{func, Array, Context, LocatableSelector, Value};
6258/// #lorem(18)
6359/// ```
6460///
65- /// To get the page numbers, we first get the location of the elements returned
66- /// by `query` with [`location`]($content.location). We then also retrieve the
67- /// [page numbering]($location.page-numbering) and [page
68- /// counter]($counter/#page-counter) at that location and apply the numbering to
69- /// the counter.
70- ///
71- /// # A word of caution { #caution }
72- /// To resolve all your queries, Typst evaluates and layouts parts of the
73- /// document multiple times. However, there is no guarantee that your queries
74- /// can actually be completely resolved. If you aren't careful a query can
75- /// affect itself—leading to a result that never stabilizes.
76- ///
77- /// In the example below, we query for all headings in the document. We then
78- /// generate as many headings. In the beginning, there's just one heading,
79- /// titled `Real`. Thus, `count` is `1` and one `Fake` heading is generated.
80- /// Typst sees that the query's result has changed and processes it again. This
81- /// time, `count` is `2` and two `Fake` headings are generated. This goes on and
82- /// on. As we can see, the output has a finite amount of headings. This is
83- /// because Typst simply gives up after a few attempts.
84- ///
85- /// In general, you should try not to write queries that affect themselves. The
86- /// same words of caution also apply to other introspection features like
87- /// [counters]($counter) and [state].
61+ /// ページ番号を取得するために、まず[`location`]($content.location)メソッドを用いて`query`が返す要素のロケーションを取得します。
62+ /// 続けて、その位置にある[ページの番号付け]($location.page-numbering)と[ページカウンター]($counter/#page-counter)を取得し、カウンターに番号付けを適用します。
63+ ///
64+ /// # 注意事項 { #caution }
65+ /// 全てのクエリを解決するために、Typstは文書の評価とレイアウトを複数回行います。
66+ /// しかしながら、実際にクエリが完全に解決されるかは保証されません。
67+ /// 注意しないとクエリ自身に影響しうるクエリを書いてしまい、結果が決して収束しなくなります。
68+ ///
69+ /// 以下の例では、文書中の全ての見出しを検索し、同じ数だけ見出しを生成しています。
70+ /// 最初は`Real`という見出しが1つだけあります。
71+ /// したがって、`count`は`1`で、`Fake`という見出しが作成されます。
72+ /// Typstはクエリの結果が変わったことに気づき、再度処理を行います。
73+ /// このとき`count`は`2`で、 2つの`Fake`見出しが作成されます。
74+ /// これが延々と続きます。
75+ /// ご覧の通り、出力には有限個の見出ししかありません。
76+ /// これは単にTypstが数回試行した後に諦めるためです。
77+ ///
78+ /// 一般に、クエリ自身に影響を与えるようなクエリを書こうとしてはいけません。
79+ /// [カウンター]($counter)や[状態]($state)などの他の内省機能にも同じ注意が必要です。
8880///
8981/// ```example
9082/// = Real
@@ -95,17 +87,16 @@ use crate::foundations::{func, Array, Context, LocatableSelector, Value};
9587/// }
9688/// ```
9789///
98- /// # Command line queries
99- /// You can also perform queries from the command line with the `typst query`
100- /// command. This command executes an arbitrary query on the document and
101- /// returns the resulting elements in serialized form. Consider the following
102- /// `example.typ` file which contains some invisible [metadata]:
90+ /// # コマンドラインクエリ
91+ /// `typst query`コマンドを用いてコマンドラインからクエリを実行することもできます。
92+ /// このコマンドは文書上で任意のクエリを実行し、シリアライズされた形で結果の要素を返します。
93+ /// 以下の何らかの不可視の[メタデータ]($metadata)を含んだ`example.typ`ファイルを考えます。
10394///
10495/// ```typ
10596/// #metadata("This is a note") <note>
10697/// ```
10798///
108- /// You can execute a query on it as follows using Typst's CLI:
99+ /// Typst CLIを用いて以下のようにこのファイルに対してクエリを実行できます。
109100/// ```sh
110101/// $ typst query example.typ "<note>"
111102/// [
@@ -117,18 +108,16 @@ use crate::foundations::{func, Array, Context, LocatableSelector, Value};
117108/// ]
118109/// ```
119110///
120- /// Frequently, you're interested in only one specific field of the resulting
121- /// elements. In the case of the `metadata` element, the `value` field is the
122- /// interesting one. You can extract just this field with the `--field`
123- /// argument.
111+ /// 結果となる要素の特定の1つのフィールドにのみ興味があることが多いです。
112+ /// `metadata`要素の場合、`value`フィールドが興味の対象です。
113+ /// `--field`引数を用いてこのフィールドのみを抽出できます。
124114///
125115/// ```sh
126116/// $ typst query example.typ "<note>" --field value
127117/// ["This is a note"]
128118/// ```
129119///
130- /// If you are interested in just a single element, you can use the `--one`
131- /// flag to extract just it.
120+ /// 単一の要素にのみ興味がある場合は、`--one`フラグを用いてその要素のみを抽出できます。
132121///
133122/// ```sh
134123/// $ typst query example.typ "<note>" --field value --one
@@ -138,13 +127,14 @@ use crate::foundations::{func, Array, Context, LocatableSelector, Value};
138127pub fn query (
139128 engine : & mut Engine ,
140129 context : Tracked < Context > ,
141- /// Can be
142- /// - an element function like a `heading` or `figure`,
143- /// - a `{<label>}`,
144- /// - a more complex selector like `{heading.where(level: 1)}`,
145- /// - or `{selector(heading).before(here())}`.
130+ /// - `heading`や`figure`のような要素関数
131+ /// - `{<label>}`
132+ /// - `{heading.where(level: 1)}`のような、より複雑なセレクター
133+ /// - `{selector(heading).before(here())}`
134+ ///
135+ /// が可能です。
146136///
147- /// Only [locatable ]($location/#locatable) element functions are supported.
137+ /// [ロケータブル ]($location/#locatable)要素関数がサポートされています。
148138target : LocatableSelector ,
149139) -> HintedStrResult < Array > {
150140 context. introspect ( ) ?;
0 commit comments