Pandoc User's Guide を日本語訳するプロジェクトです。
ここでいう「Pandocのバージョン」は2つあります。
- 翻訳対象バージョン
- 翻訳するターゲットとなるユーザーズガイドのバージョン
- 今のGitリポジトリ jgm/pandoc のバージョン(tag)
git submoduleで管理
ja-pandoc-version-lockファイルに記述してある
- ツール用バージョン
- Makefileの中で使う
pandocのバージョン - Dockerfileの
PANDOC_VERSIONで定義
- Makefileの中で使う
以下のツールはDockerイメージで整うようにしています。
- Pandoc
- 補助的な変換ツールとして用いる
- MANUAL.txt (
markdown) -> users-guide.rst (rst) - 後述のsphinx-intlによる国際化の恩恵を受けるためにreSTに変換する
- MANUAL.txt (
- 補助的な変換ツールとして用いる
- Sphinx
- reSTからHTML(サイト)を構築
- sphinx-intl: 国際化のための拡張機能
txコマンド (Transifex Client)- 翻訳作業で使うWebサービスTransifex のクライアント
- po/potファイルををpush/pullする(後述)
- GitHub
- jgm/pandoc
- ユーザーズガイド原文(MANUAL.txt)
git submoduleで取り込む
- pandoc-jp/pandoc-doc-ja: このリポジトリ
- 日本Pandocユーザ会 サイト
- ユーザーズガイド日本語版
- jgm/pandoc
- Transifex
- 翻訳作業で使うWebサービス
- 翻訳者がテキストを翻訳(ブラウザ上で共同作業)
- Read the Docs
- GitHub上のSphinxサイトをビルドして公開
- 必要なライブラリに関しては requirements.txt が参照される
Docker Hubのpandocjp/pandoc-doc-jaでイメージを公開しています。
- 参考: ベースイメージは sphinxdoc/sphinx です
※(注記) APIトークンを持っている人のみ。権限ほしい人は日本Pandocユーザ会Slackで相談してください。
- TransifexのAPIトークンページで「トークンを生成」
- トークン文字列を記録しておく
- ホスト側のカレントディレクトリに環境変数ファイル
.envを新規作成する- このファイルは
git addしないこと!
- このファイルは
.env ファイルは次のように書きます。
TX_TOKEN=【APIトークン】
docker runにて--env-file .envオプションでコンテナ側に環境変数を読み込ませる
※(注記) ~/.transifexrc というファイルを新規作成する方法もありますが、Dockerを使う場合は環境変数で読み込ませるのがよいでしょう。
詳細: Init: Initialization | Transifex Documentation
docker pull pandocjp/pandoc-doc-ja
docker build -t pandocjp/pandoc-doc-ja .
※(注記) -v ホスト側ディレクトリ:コンテナ側ディレクトリ で、カレントディレクトリを読み込ませる。
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 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
docker runにて--env-file .envオプションでコンテナ側に環境変数を読み込ませる
docker run -v $(pwd):/docs --env-file .env pandocjp/pandoc-doc-ja make tx-pull
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コマンドで行えます。
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)
$ 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に変換する
$ make intl-update
users-guide.rst (原文) を更新するときに、翻訳ファイル (pot/po) を更新する
$ make ja-html
Sphinx: htmlをビルドする
# 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 2.9.2.1 にバージョンアップ
make jgm-pandoc-checkout PANDOC_VER=2.9.2.1
make ja-update-src
現段階の翻訳を取り込む際はこちら。
make ja-build
随時 ./_build/html/index.html をブラウザで開いて確認する。
特にPandocテンプレートや翻訳前のrstをいじる際はこちら。
make ja-build-local
随時 ./_build/html/index.html をブラウザで開いて確認する。
- リリース時は
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 (pip3) でインストールします。
- Sphinx
- sphinx-intl
- tx (Transifex Client)
実際には requirements.txt でまとめてインストールします。
pip3 install -r requirements.txt
まず(必要に応じて)Dockerfileを変更する。 次にイメージをビルドする。
docker build -t pandocjp/pandoc-doc-ja .
最後にイメージをpushする。
$ sudo docker push pandocjp/pandoc-doc-ja
© 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