はじめに
研究室の研究会でorg-modeのドキュメント環境作成について発表した。わりと好評だったので、キータにも記事にしようかなと。簡単に言うと
- plantuml
- gnuplot
の文法に対応したorg-modeフォーマットのテキストをpdf(tex経由)へのexport環境を作った。dockerで作ったので、windowsでも使える。dockerだけinstallすれば手元のorg-mode文書をpdf化できる。
技術文書でよく使うUML図や実験データの描画を全部テキストで記述できるので、そのままバージョン管理ツールかけられる。技術文書の作成においてはこの環境はなかなか良いではないかと個人的におすすめする。サンプルのorgファイルもgithubに上げたので、ぜひ合わせて見てみてください。
以下の内容が発表のスライドをそのまま写したもの:
Table of Contents
ドキュメント書いてますか?
- 論文、レポート
- マニュアル
- 仕様書
- 履歴書
皆様何使ってんの?
- word
- 分けわからない独自の拡張子、フォーマット
- tex
- いいんだが、敷居はそこそこ高い。
- 手書き
- 履歴書くらいかな。別にワープロでも全然いい…
待って!そのドキュメントは共同編集されますか?
- しない
->
まあ、何でも良いじゃないですか - する
->
絶対バージョン管理できるようにした方が良い!絶対!
バージョン管理とは
- 版を重ねるにつれ変更履歴情報全部残す
- いつ、誰か、何を
- 過去のバージョンに戻せる
- 並列に共同編集してからマージできる
- conflictsなければ自動マージ
- 代表的ソフト
- git、svn、hg
- 対象ファイルがテキストファイルであることを前提している。
- git、svn、hg
バージョン管理しないと…
- ドキュメントが更新になったことにも気づかないし、どこが変更になったのかを知る手順がない
- バージョン管理せずにサーバーに置かれるものは、いつの間に内容が変わったのかを気づきようもない
ある日会社でこんな光景みました
- うちの会社word、かつ外部サーバー置かない主義
- 事情があってあるwordファイルが同時編集されていた→
-
仕様書_0412.doc
、仕様書_承太郎.doc
、仕様書_花京院.doc
と増殖
-
- どれが最新版なのかわからない!自動マージできない!カオス!
さすがにこのままじゃやばい!
- 上司に提案してみた。バージョン管理できるようにしようぜ!
- office365はできるらしい
- 外部サーバー置くことになるので×
- そもそも会社買ってない。office2010現役
- ExcelやWordなどはデータ形式の互換性がバージョンアップの際に失われることがある。10年後に読めるファイル形式であるかの確信が持てない
- linuxユーザoffice使えない。
- simulというクラウドサービスもある
- 外部サーバ置くとこになるので×
- 無料プランだと10個のファイルまで
じゃあどうすればいいの?
- OS非依存したい
- バージョン管理ツールをかけたい
- 外部サーバーに置きたくない
- 金払いたくない
救世主org-modeキター!!!
- emacsの拡張機能(もともとエディタのはずだったが、環境になりつつある)
- 完全なプレーンテキスト
->
gitとかかけられる!- 社内サーバーにおけばそのままリポジトリにできる!
- テキストで書いた文書をtex、html、markdownなど様々なフォーマットにexportできる!
- tex数式書ける
- plantUML埋め込める!
- クラス図、ユーズケース図、フローチャート図、シーケンス図全部テキストで記述しちゃう!
- gnuplot使える!
- 文法がeasy
- 無料、OS環境非依存
- 自分の論文をgithubにアップすれば誰かがpull request出してくれるかもしれない!
ただし、環境の整備が必要
- tex環境や
- plantUML環境や
- いくつかのemacsパッケージをインストールしたり
- emacsの設定ファイル書いたりする
- 日々の行いにより環境設定で挫折する人も…
めどいね…でも大丈夫だ!なぜなら…
docker
イメージを作った
- https://hub.docker.com/r/hsnuhayato/org-exporter
- https://github.com/hsnuhayato/docker-org-export/tree/support_pdf
-
dockerインストールし、dockerイメージ取ってくれば環境構築一瞬で終わる!
- $ docker pull hsnuhayato/org-exporter
-
ソース取得:
- $ git clone https://github.com/hsnuhayato/docker-org-export.git -b support_pdf
- $ git clone https://github.com/hsnuhayato/docker-org-export.git -b support_pdf
使い方
- Linux:
- githubリポジトリ内のdocker-org-export-pdfスクリプトをパスの通っているディレクトリに入れる。
- $ ./docker-org-export-pdf orgファイル名
- Windows(power shell):
-
>
docker run –rm -i -t -vC:\Users\username:/emacs/tmp --workdir=/emacs hsnuhayato/org-exporter
emacs --batch --load /emacs/emacs_init.el --file /emacs/tmp/orgファイル名 –eval '(org-latex-export-to-pdf)'-
(対象orgファイルが"C:\Users\username\orgファイル名"の場合。windows bat作り方よくわからない...)
- ただし、win10 pro以上じゃないとdocker desktopインストールできない。(hyper-vが必要。win10 homeのユーザは代わりにdocker toolboxインストルしてください)
-
-
githubリポジトリ内にexample.orgというサンプル置いてあった。まずはこのファイルの変換を試してみてください。
この発表の目的
- 少しでもorg-mode + バージョン管理ツールの組み合わせる作法を広めたい
- こんなツールもあるよ!だけ心のどこかに留めていただきたい
次回を待て!!