153 lines
15 KiB
Markdown
153 lines
15 KiB
Markdown
# DocView
|
||
|
||
PDF、ローカルHTML、HTML ZIP、DRMなしのEPUB 2/3を読む、Qt Quick製の文書ビューアーです。日本語UIとVim風のキーボード操作を備え、PDF原本の編集・保存は行いません。
|
||
|
||
**動作を確認したのはLinux開発版です。Windows向けの起動・保護・配布コードは実装しましたが、Windowsでのコンパイルと実行、対象OSでの配布確認、基準機での性能受入は未完了です。** 実施範囲と残作業は [検証記録](docs/VALIDATION.md)、設計基準は [設計書](docs/design/00-guide.md) を参照してください。
|
||
|
||
[PDFiumの第2修正候補](tests/results/pdfium-intent-context/README.md)を専用ビルドとUbuntu検証用debへ組み込みました。ICC変換指定、パターンの状態継承、タイルの線色を修正し、Arch・Ubuntuで各972点の描画試験とDocView全24群、上流1,979試験が成功しました。PDF性能4条件と約1GB・5,000ページの負荷試験も成功しています。
|
||
|
||
比較用に残した元の依存版には[ICC変換指定による描画差](tests/results/cmyk-lut/README.md)があります。修正版の試験では以前のパターン期待値も訂正しています。生成資料の成功だけで色の互換性全体を保証するものではなく、人による描画承認を含む最終受入は未完了です。
|
||
|
||
## ビルドと起動
|
||
|
||
この作業環境の修正版は `./build-context/docview` で起動します。[修正版PDFiumの配置・再ビルド手順](docs/PDFIUM-CANDIDATE.md)を参照してください。以下の `.deps/pdfium` を使う手順は比較用に保持した元の依存版です。
|
||
|
||
確認済み環境はArch Linux x64（GCC 16.2.1）と専用Ubuntu 24.04仮想環境（GCC 13.3.0）、Qt 6.11.2です。C++20、CMake 3.24以上、Ninja、pkg-config（Archではpkgconf）、Qt Core/Gui/Network/Qml/Quick/QuickControls2/WebEngineQuick/Xml/LinguistTools、libzip 1.11以上、toml++ 3.4以上、qpdf 12.4.1、libseccomp 2.5以上、Fontconfig 2.13以上が必要です。Qt標準部品の日本語表示にはQtの日本語翻訳資源も必要です（Archのqt6-translations）。試験にはQt Test/QuickTestとXvfbを使います。PDFiumは固定版の非V8ビルドを取得します。
|
||
|
||
```sh
|
||
python3 cmake/fetch_pdfium.py
|
||
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
|
||
cmake --build build -j 6
|
||
./build/docview "/path/to/book.pdf"
|
||
```
|
||
|
||
引数なしでも起動でき、`Ctrl+O`、ドラッグ＆ドロップ、`:open "パス"`で文書を開けます。`--page 42`でPDFの実ページを指定できます。独自設定を使う場合は`--config /path/to/config.toml`を指定します。通常起動時は同一ユーザーの既存ウィンドウへ文書を引き渡します。
|
||
|
||
Linuxワーカーの隔離にはLandlock ABI 3以上、seccomp、利用可能なQt WebEngineのサンドボックスが必要です。隔離できない環境では文書処理を開始しません。`QTWEBENGINE_DISABLE_SANDBOX`、`--no-sandbox`などによる回避はサポートしません。
|
||
|
||
Ubuntuの公式Qt SDKを用いた[ビルド・検証手順](tests/ubuntu_vm/README.md)、[ローカル検証用debの手順](docs/UBUNTU-PACKAGE.md)、[URL比較修正後の試験記録](tests/results/portal/README.md)、[Qt告知補足版の検証](tests/results/qt-notice-supplement/README.md)も保存しています。
|
||
|
||
Windowsでのビルド手順、必要な依存物、未検証項目は [Windowsの準備手順](docs/WINDOWS-BUILD.md) にまとめています。
|
||
|
||
日本語を初期表示にし、翻訳可能な文言を[翻訳カタログ](resources/i18n/docview_ja.ts)へ分離しています。
|
||
文言を変更したときは[更新手順](docs/TRANSLATIONS.md)に従ってカタログを更新します。
|
||
|
||
## 主な操作
|
||
|
||
| キー | 動作 |
|
||
|---|---|
|
||
| `j` / `k` / `h` / `l` | 下・上・左・右へスクロール |
|
||
| `Ctrl+D` / `Ctrl+U` | 半画面進む・戻る |
|
||
| `Ctrl+F` / `Ctrl+B` | 一画面進む・戻る |
|
||
| `gg` / `G` | 文書の先頭・末尾 |
|
||
| `42G` / `:page 42` | PDFの42ページ目へ移動 |
|
||
| `J` / `K` | 次・前のPDFページ |
|
||
| `]]` / `[[` | 次・前の見出し |
|
||
| `]c` / `[c` | 次・前のEPUB章 |
|
||
| `t` / `p` / `zs` | 目次・ページ一覧・ステータスの個別切替 |
|
||
| `Ctrl+W` → `w` | 本文・目次・ページ一覧の操作先を切替 |
|
||
| `Enter` / `Esc` | 項目・リンク・PDF注釈の確定 / 取消・本文へ戻る |
|
||
| `+` / `-` / `=` | 拡大・縮小・幅に合わせる |
|
||
| `:rotate 90` | PDFを90度回転 |
|
||
| `Tab` / `Shift+Tab` | 次・前のリンクを選択（PDFでは注釈も対象） |
|
||
| `/` / `n` / `N` | 本文検索・次・前の結果 |
|
||
| `Alt+Left` / `Alt+Right` | 移動履歴を戻る・進む |
|
||
| `?` / `:help` | 現在の設定に対応する操作一覧 |
|
||
| `:info` / `:reload` / `:q` | 文書情報・設定再読込・終了 |
|
||
|
||
目次・ページ一覧では`j`/`k`で選択し、`Enter`で移動します。目次の`>`は現在読んでいる節、枠はキー操作で選択中の項目を示します。`h`/`l`は階層の折りたたみ・展開です。入力欄やダイアログでは閲覧キーを停止します。操作一覧・コマンド入力・ダイアログを閉じると元の操作先へ戻ります。元のパネルが非表示になった場合は本文へ戻り、文書の切替などで操作先が指定された場合はその指定を優先します。PDFのステータスにはページラベルと実ページ番号を表示します。
|
||
|
||
目次の準備中に`t`を押すと読み込み中の表示を開き、準備できた項目を表示します。PDFの構造見出しがない場合、文書内の移動先を持つ目次項目を見出し移動に使います。外部リンクや禁止されたアクションは代替候補に含めません。Webの選択リンクは`Esc`で解除できます。
|
||
|
||
HTML・EPUBで欠落した資源や遮断された参照がある場合は、`:info`で理由と検出件数を確認できます。同じ資源の再試行も件数に含まれます。URLや本文を警告履歴に保存しません。資源提供側の読込み失敗は、不在・アクセス拒否・破損・上限・保存や読取りの失敗などを理由別に区別します。
|
||
|
||
すべての形式でステータスに倍率を表示します。HTML・HTML ZIP・流込EPUBの倍率は25–500%です。固定レイアウトEPUBでは、ページ全体または幅に合わせた大きさを100%とし、倍率に「ページ合わせ」「幅合わせ」を添えます。`privacy.remember_position`が有効なら、読書位置と倍率を保存して同じ原本を開き直したときに復元します。固定EPUBは合わせ方も保存するため、ウィンドウの大きさが変わってもその基準で表示します。
|
||
|
||
ファイル選択や`:open`で読込みに失敗した場合は、対象名、原因の分類、利用者ができる対処を表示します。切替前の文書は表示を続け、`:info`で最後に開こうとした文書の失敗を確認できます。この情報は表示中の文書の警告と分けて扱い、ディスクには保存せず、次に文書を開く試行で更新します。
|
||
|
||
固定レイアウトEPUBは著者指定に応じた見開きに対応し、RTL、中央の単独ページ、項目別指定を反映します。複数入口のHTML ZIPで選んだページは、履歴または位置保存が有効なら、同じ原本を開き直したときに再利用します。`:history clear`でこの選択も消去できます。
|
||
|
||
PDF検索は既存の文字情報、HTML/ZIP検索は表示中のHTML、EPUB検索は表示中の章を対象にします。EPUBの`gg`/`G`は通常の読書順序に含まれる先頭章の先頭／最終章の末尾へ移動します。
|
||
|
||
## 設定と保存先
|
||
|
||
[設定例](resources/config.example.toml)を配置して編集し、`:reload`で再読込します。検証に失敗した設定は適用されず、現在の有効な設定が維持されます。既定のLinux保存先は次のとおりです。
|
||
|
||
| 用途 | パス |
|
||
|---|---|
|
||
| 設定 | `$XDG_CONFIG_HOME/docview/config.toml`（未指定時`~/.config/docview/config.toml`） |
|
||
| 読書状態 | `$XDG_STATE_HOME/docview/state.json`（未指定時`~/.local/state/docview/state.json`） |
|
||
| 一時資源 | `$XDG_CACHE_HOME/docview/sessions`（未指定時`~/.cache/docview/sessions`） |
|
||
|
||
`privacy.remember_position`と`privacy.recent_documents`で位置・履歴の保存を制御します。`:history clear`は件数を確認して履歴と保存位置を消去します。本文引用の保存は既定で無効です。パスワードは保存しません。
|
||
|
||
開いた原本の識別情報を保存・復元時に再確認します。閲覧中に原本が変更・置換された場合、以前の文書の位置を新しい原本へ保存しません。保存済み位置との同一性を確認できない原本を明示的に開いた場合は、復元できないことを通知して先頭から表示します。
|
||
|
||
履歴を有効にしている場合、文書を開く前の画面に最近使った文書を表示します。矢印または`j`/`k`で選び、`Enter`で開けます。削除・変更・置換された原本は自動では開かず、ファイル選択から開き直すよう通知します。
|
||
|
||
単独HTMLは原則として同じフォルダー配下の資源を参照します。親フォルダーにある資源が必要な場合は`:root`で許可する文書フォルダーを明示します。文書のJavaScript、外部資源の自動取得、フォーム送信は無効です。利用者が選んだ外部リンクは宛先を確認して外部ブラウザーで開きます。
|
||
|
||
## 試験
|
||
|
||
試験資料はリポジトリー内の生成スクリプトから作成します。基本PDFの再生成にはqpdf、追加PDFの再生成にはReportLab、pypdf、Pillowと指定フォントが必要です。生成済み資料とハッシュも含めています。
|
||
|
||
```sh
|
||
python3 tests/fixtures/pdf/generate.py
|
||
python3 tests/generate_web_fixtures.py
|
||
QT_QPA_PLATFORM=xcb QT_QUICK_BACKEND=software \
|
||
QTWEBENGINE_CHROMIUM_FLAGS=--disable-gpu \
|
||
xvfb-run -a ctest --test-dir build --output-on-failure --output-junit tests.xml
|
||
```
|
||
|
||
通常のデスクトップセッションではXvfbを省略できます。試験でもアプリ内部の隔離は有効です。外側の実行環境がローカルソケットや名前空間を禁止する場合、その環境ではGUI・ワーカー試験を実施できません。
|
||
|
||
Linuxの実時間watchdog試験は`./build/test_worker_deadlines`で別途実行できます。PDFの30秒通知・120秒停止、展開の10秒通知・30秒停止、待機中の取消を検証します。[現行結果と再現手順](tests/results/completion-final/worker-deadlines/README.md)を参照してください。
|
||
|
||
```sh
|
||
python3 tests/compare_pdf_renderers.py
|
||
python3 tests/compare_pdf_extended.py
|
||
python3 tests/compare_pdf_fonts.py
|
||
python3 tests/compare_font_collection.py
|
||
python3 tests/compare_pdf_icc.py
|
||
QT_QPA_PLATFORM=xcb QT_QUICK_BACKEND=software \
|
||
QTWEBENGINE_CHROMIUM_FLAGS=--disable-gpu \
|
||
xvfb-run -a python3 tests/benchmark.py --operations 125 --cold-process-runs 30
|
||
```
|
||
|
||
描画比較には独立したPopplerを使います。実TTCと個別TTFを比べる追加試験にはfontToolsとOFLフォントを使い、一時フォントは試験後に削除します。性能測定は新プロセス・空のアプリキャッシュで30回、同一プロセスの初回と再openを30回、同条件の29開閉、対応するページ・見出し・章系列を各125操作、継続scrollを240入力で記録します。PDFの125操作はページ移動101回と倍率変更24回です。OSファイルキャッシュは消去しません。Qtのフレーム通知は物理ディスプレイへの提示時刻ではなく、この開発機の結果で基準機・両OSの合格とはしません。
|
||
|
||
PDFの比較は本番の隔離ワーカーとフォント供給処理を経由します。非埋込日本語の横書き・縦書き資料は`tests/fixtures/pdf/generate_fonts.py`で、タグ付きPDFの境界資料は`tests/fixtures/pdf/generate_headings.py`で再生成できます。使用した代替フォントと制約は[PDFの検証記録](tests/PDF-VALIDATION.md)にまとめています。
|
||
|
||
500ページのPDF、500章のEPUB、400見出しのHTMLを使う測定も実行できます。これらは小さな画像を再利用した生成資料であり、1 GiBのスキャン資料ではありません。
|
||
|
||
```sh
|
||
python3 tests/generate_performance_corpus.py
|
||
QT_QPA_PLATFORM=xcb QT_QUICK_BACKEND=software \
|
||
QTWEBENGINE_CHROMIUM_FLAGS=--disable-gpu \
|
||
xvfb-run -a python3 tests/benchmark.py --corpus standard --operations 125 --cold-process-runs 30 --output tests/results/performance-standard
|
||
```
|
||
|
||
長押し、連続する遠距離ジャンプ、リサイズ、文書切替、取消の計測は別に実行します。出力先は新規ディレクトリーを指定してください。通常のCTestではこの計測用slotだけを意図的にskipします。
|
||
|
||
```sh
|
||
QT_QPA_PLATFORM=xcb QT_QUICK_BACKEND=software \
|
||
QTWEBENGINE_CHROMIUM_FLAGS=--disable-gpu \
|
||
xvfb-run -a -s '-screen 0 1100x760x24' python3 tests/measure_interaction.py \
|
||
--binary build/test_app --output tests/results/performance-interaction/new-run
|
||
```
|
||
|
||
約1GB・5,000ページの画像PDFも生成し、100操作と末尾への移動を検証しました。[負荷試験記録](tests/STRESS-PDF-VALIDATION.md)に数値と再現手順があります。大容量資料は試験後に自動削除します。
|
||
|
||
## ローカルインストール
|
||
|
||
```sh
|
||
cmake --install build --prefix "$PWD/build/install"
|
||
./build/install/bin/docview
|
||
```
|
||
|
||
本体、ワーカー、PDFiumとそのライセンスを配置します。Qtとその他のライブラリはシステムの動的ライブラリを利用します。単体で配布できるパッケージではありません。依存関係は [DEPENDENCIES.md](docs/DEPENDENCIES.md)、追加形式の接続方法は [adapter-contract.md](docs/adapter-contract.md) を参照してください。
|
||
|
||
Arch Linux向けの開発用tar.gzと、依存物の版・ハッシュ・告知をまとめる手順は [ローカルパッケージ](docs/LINUX-DEVELOPMENT-PACKAGE.md) にあります。生成物は同じ開発環境のシステムライブラリーを必要とします。
|
||
|
||
Ubuntu 24.04 amd64向けには、修正版PDFiumとQt SDK等を同梱した[validation4 deb](docs/UBUNTU-PACKAGE.md)を作成しました。ビルド環境とSDKのない既存試験VMで、それぞれX11・Wayland合計12条件の起動、install/remove/purgeを確認しています。新規OSからの試験は旧validation1の履歴です。公開リリースの受入は未完了です。
|