pandoc-doc-ja: Pandocユーザーズガイド日本語版

Pandoc User's Guide を日本語訳するプロジェクトです。

• 日本Pandocユーザ会
  • Pandocユーザーズガイド 日本語版

Pandocのバージョンについて

ここでいう「Pandocのバージョン」は2つあります。

• 翻訳対象バージョン
  • 翻訳するターゲットとなるユーザーズガイドのバージョン
  • 今のGitリポジトリ jgm/pandoc のバージョン（tag）
    • git submodule で管理
  • ja-pandoc-version-lock ファイルに記述してある
• ツール用バージョン
  • Makefileの中で使うpandocのバージョン
  • Dockerfileの PANDOC_VERSION で定義

使用ツール・Webサービスまとめ

ツール

以下のツールはDockerイメージで整うようにしています。

• Pandoc
  • 補助的な変換ツールとして用いる
    • MANUAL.txt (markdown) -> users-guide.rst (rst)
    • 後述のsphinx-intlによる国際化の恩恵を受けるためにreSTに変換する
• Sphinx
  • reSTからHTML（サイト）を構築
  • sphinx-intl: 国際化のための拡張機能
• tx コマンド (Transifex Client)
  • 翻訳作業で使うWebサービスTransifex のクライアント
  • po/potファイルををpush/pullする（後述）

Webサービス

• GitHub
  • jgm/pandoc
    • ユーザーズガイド原文(MANUAL.txt)
    • git submodule で取り込む
  • pandoc-jp/pandoc-doc-ja: このリポジトリ
    • 日本Pandocユーザ会 サイト
    • ユーザーズガイド日本語版
• Transifex
  • 翻訳作業で使うWebサービス
  • 翻訳者がテキストを翻訳（ブラウザ上で共同作業）
• Read the Docs
  • GitHub上のSphinxサイトをビルドして公開
  • 必要なライブラリに関しては requirements.txt が参照される

初期設定：Dockerを使う場合

Docker Hubのpandocjp/pandoc-doc-jaでイメージを公開しています。

• 参考: ベースイメージは sphinxdoc/sphinx です
  • Sphinxのインストール — Sphinx 4.0.0+/c443e742f ドキュメント

txコマンド (Transifex Client) のセットアップ

※ APIトークンを持っている人のみ。権限ほしい人は日本Pandocユーザ会Slackで相談してください。

（翻訳の手引 for Pandocユーザーズガイドも参照）

• TransifexのAPIトークンページで「トークンを生成」
  • トークン文字列を記録しておく
• ホスト側のカレントディレクトリに環境変数ファイル .env を新規作成する
  • このファイルはgit addしないこと！

.env ファイルは次のように書きます。

TX_TOKEN=【APIトークン】

• docker run にて --env-file .env オプションでコンテナ側に環境変数を読み込ませる

※ ~/.transifexrc というファイルを新規作成する方法もありますが、Dockerを使う場合は環境変数で読み込ませるのがよいでしょう。

詳細: Init: Initialization | Transifex Documentation

docker pull

docker pull pandocjp/pandoc-doc-ja

ローカルで docker build

docker build -t pandocjp/pandoc-doc-ja .

docker run

※ -v ホスト側ディレクトリ:コンテナ側ディレクトリ で、カレントディレクトリを読み込ませる。

Bashにログインする（インタラクティブ実行）

docker run -v 【カレントディレクトリ】:/docs -it pandocjp/pandoc-doc-ja /bin/bash

例（macOSや純粋なLinux環境のBash）：

docker run -v $(pwd):/docs -it pandocjp/pandoc-doc-ja bash

任意のコマンドを実行する（環境変数を使わない場合、makeコマンド含む）

• 例：make ja-htmlコマンドを実行する場合
  • make ja-htmlの部分を任意のコマンドにできる
• -it はインタラクティブ実行が必要なときのみ付ける（シェルなど）

docker run -v $(pwd):/docs pandocjp/pandoc-doc-ja make ja-html

※ コマンドを指定しなかった場合のデフォルトはmake ja-html

docker run -v $(pwd):/docs pandocjp/pandoc-doc-ja

環境変数を使うコマンドを実行する（txコマンド、make tx-pullなど）

• docker run にて --env-file .env オプションでコンテナ側に環境変数を読み込ませる

docker run -v $(pwd):/docs --env-file .env pandocjp/pandoc-doc-ja make tx-pull

Docker for Windowsにおける【カレントディレクトリ】

WSL(1 or 2)上のカレントディレクトリからアクセスしたい場合(ホストBashからゲストBashにログイン)

• wslpath -aw: WSL上のパスをフルパス(/mnt/c/...)にした上で、Windows上のパスに変換する

docker run -v $(wslpath -aw $(pwd)):/docs -it pandocjp/pandoc-doc-ja bash

makeコマンド一覧

このプロジェクトにおけるあらゆる操作は、makeコマンドで行えます。 Makefileに書いてある記述を元に、直接元のコマンドを打っても動くはずです。

# 例: Sphinxでhtmlをビルドする
$ make ja-html

ターゲット：まとめて実行

$ make jgm-pandoc-checkout PANDOC_VER=バージョン番号
jgm/pandocを特定バージョンでチェックアウトし、独自のヘッダを付与する

$ make ja-update-src
アップデート作業をまとめてする
(users-guide-rst -> intl-update -> tx-push-pot)
要環境変数

$ make ja-build
Transifex: 翻訳ファイル(po)をpullし、そのままビルドする
(tx-pull -> ja-html)
要環境変数

$ make ja-build-local
ローカル環境のみ：アップデート・ビルド作業をまとめてする
(users-guide-rst -> intl-update -> ja-html)

ターゲット：Pandocバージョン関連

$ make ja-init
git submodule を初期化する
(下記コマンドを実行する前に、あらかじめ実行しておくこと)

$ make jgm-pandoc-version
元リポジトリPandocバージョンを表示する (pandoc/pandoc.cabalのversionを参照)

$ make ja-pandoc-version
翻訳対象Pandocバージョンを表示する (./ja-pandoc-version-lock ファイルを参照)

$ make ja-pandoc-version-lock
翻訳対象Pandocバージョンをjgm/pandocのものに固定する (ファイルに書き出すだけ)

ターゲット：リポジトリ・原文アップデート系

(jgm/pandoc: MANUAL.txt のアップデートと翻訳ファイルの更新)

$ make users-guide-rst
Pandoc: jgm/pandocの MANUAL.txt (Markdown) をrstに変換する

ターゲット：Sphinx系（単品）

$ make intl-update
users-guide.rst (原文) を更新するときに、翻訳ファイル (pot/po) を更新する

$ make ja-html
Sphinx: htmlをビルドする

ターゲット：Transifex系

# make tx-push-pot
Transifex: 【翻訳前pot】手元の更新後ソースファイル(pot)をpushする
要環境変数

# make tx-pull
Transifex: 【翻訳後po】Transifexから最新の翻訳ファイル(po)をpullする
要環境変数

# make tx-push-local-po
Transifex: 【翻訳後po】手元の翻訳ファイル(po)をpushする

典型的なワークフロー

下記の実行のために、あらかじめコンテナのBashにログインしておきます（環境変数も読み込ませる）。

docker run -v $(pwd):/docs --env-file .env -it pandocjp/pandoc-doc-ja bash

Pandoc翻訳対象バージョンのアップグレード

例: Pandoc 2.9.2.1 にバージョンアップ

make jgm-pandoc-checkout PANDOC_VER=2.9.2.1
make ja-update-src

HTMLビルド（Transifex上で翻訳済のpoファイルをpullしてから）

現段階の翻訳を取り込む際はこちら。

make ja-build

随時 ./_build/html/index.html をブラウザで開いて確認する。

HTMLビルド（ローカルファイルの変更をチェックしたいとき）

特にPandocテンプレートや翻訳前のrstをいじる際はこちら。

make ja-build-local

随時 ./_build/html/index.html をブラウザで開いて確認する。

ビルドしたものをGitHubにpush

• リリース時は git tag でタグ付けする。（Read the Docs側でタグが反映される）
• 同じバージョンを更新する際は _revN のプレフィックスを付ける
  • 例: v2.9.2.1_rev2

git add *
git commit -m '[update] 現時点での翻訳を取り込んでビルド'
git tag -a v2.9.2.1 -m 'Pandoc 2.9.2.1 準拠'
git push origin master

GitHubにpushできたら、Read the Docs側で自動的にビルド・更新されデプロイされる。

確認する: https://pandoc-doc-ja.readthedocs.io/ja/latest/

付録

初期設定：手動でインストールする場合

Makefileの中で使うpandocをあらかじめインストールしておいてください。 （翻訳対象バージョンにかかわらず、その時点での最新版のインストールを推奨します）

Pythonのバージョンについては、Python3系を前提とします。

pipでインストール

以下をpip (pip3) でインストールします。

• Sphinx
• sphinx-intl
• tx (Transifex Client)

実際には requirements.txt でまとめてインストールします。

pip3 install -r requirements.txt

Dockerfile・Dockerイメージのアップデート

まず（必要に応じて）Dockerfileを変更する。 次にイメージをビルドする。

docker build -t pandocjp/pandoc-doc-ja .

最後にイメージをpushする。

$ sudo docker push pandocjp/pandoc-doc-ja

原文について

• Pandoc
• GitHub - jgm/pandoc: Universal markup converter

ライセンス

© 2006-2022 John MacFarlane (jgm@berkeley.edu). Released under the GPL, version 2 or greater. This software carries no warranty of any kind. (See COPYRIGHT for full copyright and warranty notices.)

• fix-header-inconsistency.lua: MIT License
  • sky-y/sky-y-lua-filters: Custom lua filters for Pandoc