FAQ

Timeline DSL は何を出力できますか？

tdsl build でIR JSON、tdsl render でスタンドアロンHTMLを出力できます。HTMLはブラウザで開いて年表を確認できます。

どんな用途に向いていますか？

ソース（.tdsl テキスト）を真実とし、差分やレビューを Git で管理したい年表に向いています。歴史・プロジェクト・人物史・プロダクトのリリース史などを、手書きまたは Wikidata / CSV 由来のデータから構築できます。

• 手早く試したい: ブラウザ完結の Playground で、インストールなしに DSL を書いて即描画できます。
• 資料・成果物にしたい: CLI の tdsl render でスタンドアロン HTML（テーマ・独自 CSS 対応）を出力できます。
• 継続的に運用したい: tdsl check / tdsl lint を CI に組み込み、年表をコードと同じレビュー対象にできます。

逐次更新されるリアルタイムなダッシュボードや、対話的な編集 UI が主目的の場合は、本ツールの守備範囲外です。

Wikidataなしでも使えますか？

使えます。timeline、lane、span、event、event_range を手で書く静的な .tdsl ファイルはローカルで検証・ビルド・描画できます。Wikidata import を含むファイルでも、build と render に --offline を付けると静的項目だけを処理します。

どのコマンドから始めればよいですか？

手で作る場合は tdsl init、Wikidataから作る場合は tdsl search と tdsl inspect から始めます。既存ファイルを確認するだけなら tdsl check と tdsl lint を使います。

紀元前の年はどう書きますか？

負の整数で表現します。例えば紀元前 206 年は -206、紀元前 221 年は -221 です。

span qin -221..-206 "秦" { tags ["dynasty"]; };

range の開始にも負の整数が使えます。

timeline "古代年表" {
    range -500..500;
}

lane（レーン）を複数定義できますか？

lane 宣言を複数並べるだけです。order でレーンの表示順を制御できます（数値が小さいほど上に表示）。

lane "秦" as qin     { kind dynasty; order 10; }
lane "漢" as han     { kind dynasty; order 20; }
lane "三国" as sanguo { kind dynasty; order 30; }

kind は分類ラベルで、dynasty（王朝）・person（人物）・nation（国）などを自由に指定できます。as で内部 ID を明示しない場合、ラベルから ASCII スラッグが自動生成されます（日本語ラベルのみの場合は lane_1、lane_2… のように自動採番されます）。

CSVから取り込めますか？

tdsl import-csv が使えます。CSVはUTF-8で、lane,type,start,end,time,label,tags,id のヘッダー行が必要です。任意で source / origin 列も追加でき、tdsl export-csv が出力する10列CSVをそのまま取り込めます。

tdsl import-csv items.csv
tdsl import-csv items.csv --append manual.tdsl

CIでは何を実行すべきですか？

基本は tdsl check と tdsl lint です。成果物の生成まで確認する場合は tdsl build --pretty --output timeline.json を追加します。Wikidata取得を避けたい場合は --offline を使います。

Wikidataの取得キャッシュをリセットできますか？

できます。Wikidata取得キャッシュは ~/.cache/tdsl/ に保存されており、tdsl cache コマンドで管理できます。

tdsl cache status
tdsl cache clear
tdsl cache clear --older-than 30

HTMLテーマは選べますか？

tdsl render --theme で default、dark、print、pastel を指定できます。独自CSSは --custom-css で追加できます。

印刷・一覧用にすべてのラベルを常時表示できますか？

できます。CLIの tdsl render --show-event-labels、または Playground ツールバーの「ラベルを常時表示（一覧・印刷向け）」トグルで、Event / EventRange のラベルをホバー不要で常時描画できます（v1.17.0〜）。Gallery のサンプル一覧も同じトグルで印刷・一覧向けの表示を確認できます。