27 Apr 2014, 06:18

org-mode で書いたテキストを Pandoc で Restructured Text に変換する

やりたいこと

org-mode で書いたテキストを Restructured Text に変換したい.

Pandoc を利用すると, org-mode の文章を変換することができる.

[sourcecode language=”text” title=””]
入力 (org-mode) -> 変換 (Pandoc) -> 出力 (Restructured Text)
[/sourcecode]

Pandoc をつかう

Pandoc とは, 汎用的なドキュメント変換ツール. ある形式から別の形式へドキュメントの形式を変換できる.

org-mode の writer は以前からあったが, reader は最近ようやく pull request された.

ということで, 最新の Pandoc を試してみる. github からダウンロード.

pandoc は haskell でかかれてるので, ビルドには haskell がひつよう.

以下を順々に実施.

[sourcecode language=”bash” title=””]
$ cabal update
$ cabal install pandoc
$ pandoc -v
pandoc 1.12.3.3
Compiled with texmath 0.6.6.1, highlighting-kate 0.5.6.1.
[/sourcecode]

実験

<div class="outline-text-3" id="text-unnumbered-3">
  <p>
    これがゴール.
  </p>

  <p>
    [sourcecode language=&#8221;text&#8221; title=&#8221;&#8221;]<br /> Hello Sphinx<br /> ============
  </p>

  <p>
    テスト.
  </p>

  <p>
    テスト<br /> ======
  </p>

  <p>
    テストです.<br /> [/sourcecode]
  </p>

  <p>
    これを変換する.
  </p>

  <p>
    [sourcecode language=&#8221;text&#8221; title=&#8221;&#8221;]<br /> * Hello Sphinx
  </p>

  <p>
    テスト.
  </p>

  <p>
    * テスト
  </p>

  <p>
    テストです.<br /> [/sourcecode]
  </p>

  <p>
    変換はコマンドラインから以下を実行
  </p>

  <p>
    [sourcecode language=&#8221;bash&#8221; title=&#8221;&#8221;]<br /> pandoc -f rst hello2.org<br /> [/sourcecode]
  </p>

  <p>
    こうなった.
  </p>

  <p>
    [sourcecode language=&#8221;text&#8221; title=&#8221;&#8221;]<br /> &#8211; Hello Sphinx
  </p>

  <p>
    テスト.
  </p>

  <p>
    &#8211; テスト
  </p>

  <p>
    テストです.<br /> [/sourcecode]
  </p>

  <p>
    箇条がきではなくて, 見出しなのだが. . . 今後に期待ということで.
  </p>
</div>

org-pandoc をつかう

org-pandoc をというツールをつかっても, panodc に対応した色々なフォーマットに変換できる.

仕組みは, 一度 org-mode から markdown に変換して, markdown を pandoc にかけるというもの.

実験

<div class="outline-text-3" id="text-unnumbered-5">
  <p>
    変換には, 以下を評価したあとに, M-x org-pandoc-export-to-pandoc 実 行.
  </p>

  <p>
    [sourcecode language=&#8221;emacs-lisp&#8221; title=&#8221;&#8221;]<br /> (require &#8216;ox-pandoc)<br /> (setq org-pandoc-export-format &#8216;rst)<br /> [/sourcecode]
  </p>

  <p>
    こうなった.
  </p>

  <p>
    [sourcecode language=&#8221;text&#8221; title=&#8221;&#8221;]<br /> ======<br /> hello2<br /> ======
  </p>

  <p>
    :Author: tsu-nera
  </p>

  <p>
    .. raw:: html
  </p>

  <p>
    <div id="table-of-contents"><br /> \<h2\>
  </p>

  <p>
    Table of Contents
  </p>

  <p>
    .. raw:: html
  </p>

  <p>
    \</h2\><br /> <div id="text-table-of-contents"><br /> <ul><br /> <li>
  </p>

  <p>
    1. Hello Sphinx
  </p>

  <p>
    .. raw:: html
  </p>

  <p>
    </li><br /> <li>
  </p>

  <p>
    2. テスト
  </p>

  <p>
    .. raw:: html
  </p>

  <p>
    </li><br /> </ul><br /> </div><br /> </div>
  </p>

  <p>
    Hello Sphinx<br /> ============
  </p>

  <p>
    テスト.
  </p>

  <p>
    テスト<br /> ======
  </p>

  <p>
    テストです.<br /> [/sourcecode]
  </p>

  <p>
    ヘッダによけいなものがたくさんつくものの, default pandoc よりいいな.
  </p>
</div>

org-mode から markdown 経由で reST へ変換する

Markdown から reST への変換は いろいろな人がチャレンジして実績があるので, この道を考える.

org-mode には, デフォルトで markdown 変換コマンドあり. MarkDown どころか, HTML,Pandoc,LATex.. いろいろある.

詳しくは, org-export-dispatch (C-c C-e) を実行.

さっきのゴミは, emacs-export 機能のオプションを利用すれば消せた.

[sourcecode language=”text” title=””]
#+OPTIONS: toc:nil
[/sourcecode]

オプションの詳しい説明は, 以下.

コマンドラインから変換したい

<div class="outline-text-3" id="text-unnumbered-7">
  <p>
    上記の方法は, Emacs のなかで変換処理を行うのだが, 複数ファイルを処理するとするとコマンドラインから変換処理を行いたい.
  </p>

  <p>
    調べたところ, emacs には batch という機能があるようだ.
  </p>

  <ul class="org-ul">
    <li>
      <a href="http://d.hatena.ne.jp/rubikitch/20101107/org2html">org-mode → HTML 変換をする 3 つの方法 &#8211; (rubikitch loves (Emacs Ruby CUI Books))</a>
    </li>
    <li>
      <a href="http://shuzo-kino.hateblo.jp/entry/2014/01/02/012905">CLI で emacs の org-mode を使って html 化する &#8211; Bye Bye Moore</a>
    </li>
    <li>
      <a href="http://www.bookshelf.jp/texi/emacs-20.6-man-jp/emacs_32.html#SEC490">GNU Emacs マニュアル: A. コマンド行引数</a>
    </li>
  </ul>

  <p>
    batch については今回はわからなかったので, 次回に回す. 外部ライブラリまわりで苦戦.
  </p>

  <p>
    [sourcecode language=&#8221;bash&#8221; title=&#8221;&#8221;]<br /> emacs hello.org -f org-md-export-to-markdown<br /> [/sourcecode]
  </p>

  <p>
    とりあえず, なんとなくできるという道が開けた気がした.
  </p>
</div>

15 Dec 2012, 07:36

Sphinxでテキストから変幻自在の出力結果比較(HTML,Word,PDF,ePub)

Sphinxの魅力の一つが、ひとつのテキストから様々なフォルダ形式に出力可能な点だ。

今回は以下の形式の出力結果をまとめてみようと思う。

  • HTML
  • Word
  • PDF
  • ePub

HTML出力

まずは基本から。

image

PDF出力

rst2pdfを使ってPDF出力しました。

 

image

Word出力

Sphinx-docxbuilderを利用して、Word出力しました。

image

ePub出力

IMG_0014

15 Dec 2012, 07:21

SphinxのPDF出力をrst2pdfで試す@Windows64bit

SphinxでPDF出力する方法は以下の2つがあるらしい。

  • rst2pdf
  • Latex

以下のページを参考にした。
SphinxでPDFファイル作成 :: ドキュメンテーションツール スフィンクス Sphinx-users.jp
今回はWindows環境で、rst2pdfを使う方法を試してみた。

環境

  • Windows 7 64bit
  • Python 2.6
  • Sphinx1.1.3

rst2pdf設計方法

rst2pdfを手に入れる

easy_installに対応しているので、コマンドプロンプトから以下のコマンドを叩きます。

 easy_install rst2pdf

そうすると、すんなりいかないでしょう。

Pythonモジュールである、PILやReportLabをインストールするところで失敗します。

PILの入手@Winodows64bit version

Windows 64bitユーザはPILを以下のサイトから手に入れます。

ReportLabの入手@Winodows64bit version

ReportLabのインストールは注意が必要です。version2.6ではなくて、2.5を入れます。

以下のサイトにありました。

2.6を入れると以下の様なエラーが発生して、PDF作成に失敗しました。

これは、既知障害っぽいです。

http://code.google.com/p/rst2pdf/issues/detail?id=474

$ rst2pdf -s ja –font-path=C:\Windows\Fonts index.rst

Traceback (most recent call last):

File “/usr/bin/rst2pdf”, line 8, in

load_entry_point(‘rst2pdf==0.92’, ‘console_scripts’, ‘rst2pdf’)()

File “/usr/lib/python2.6/site-packages/rst2pdf-0.92-py2.6.egg/rst2pdf/createpdf.py”, line 1445, in main

section_header_depth=int(options.section_header_depth),

File “/usr/lib/python2.6/site-packages/rst2pdf-0.92-py2.6.egg/rst2pdf/createpdf.py”, line 183, in __init__

self.loadStyles(stylesheets)

File “/usr/lib/python2.6/site-packages/rst2pdf-0.92-py2.6.egg/rst2pdf/createpdf.py”, line 276, in loadStyles

def_dpi=self.def_dpi)

File “/usr/lib/python2.6/site-packages/rst2pdf-0.92-py2.6.egg/rst2pdf/styles.py”, line 527, in __init__

reportlab.platypus.tables.CellStyle1.fontname=self[‘base’].fontName

AttributeError: ‘module’ object has no attribute ‘CellStyle1’

日本語フォントのインストール

PDF出力をするためには、日本語フォントを追加する必要があります。

以下の2つをそれぞれダウンロードします。

それぞれ、拡張子がttfのファイルをWindowsのフォントフォルダにコピーします。

  • VL-Gothic-Regular.ttf
  • VL-PGothic-Regular.ttf
  • ipag.ttf
  • ipam.ttf
C:\Windows\Fonts

rst2pdfがインストールできたかの確認

試しにSphinxのindex.rstをpdfに変換します。

以下のコマンドを叩いて、index.pdfが生成出来れば成功です。

rst2pdf -s ja --font-path=C:\Windows\Fonts index.rst

Sphinxの設定

各RSTファイルへの実行は成功するようになったので、全てのRSTファイルをまとめて実行できるように、Sphinxの設定ファイルをいじります。

Makefileの修正

まずは、make pdfが実行できるように、Makefileの終わりに以下を追加します。

Makefileの常識で、先頭の空白は必ずタブにします。

pdf:
        $(SPHINXBUILD) -b pdf $(ALLSPHINXOPTS) $(BUILDDIR)/pdf
        @echo
        @echo "Build finished. The PDF files are in _build/pdf."

conf.pyの修正

conf.pyにrst2pdfを実行する際のオプションを設定します。

extensions = ['rst2pdf.pdfbuilder']

pdf_documents = [
    ('index', u'MyProject', u'My Project', u'Author Name'),
]

# A comma-separated list of custom stylesheets. Example:
pdf_stylesheets = ['sphinx','kerning','a4','ja']

import os
font_dir = os.path.abspath(os.path.join(os.path.split(__file__)[0], os.pardir, 'fonts'))
pdf_font_path = [font_dir, 'C:\WINDOWS\Fonts']

pdf_language = "ja"

フォントの指定

最後にフォントを指定するための設定ファイルを作ります。

ja.jsonという名前で、以下の内容を追記します。

{
  "embeddedFonts" : [
    [
        "VL-Gothic-Regular.ttf",
        "VL-PGothic-Regular.ttf",
        "ipam.ttf",
        "ipag.ttf"
     ]
  ],
  "fontsAlias" : {
    "stdFont": "VL-PGothic-Regular",
    "stdBold": "VL-PGothic-Regular",
    "stdItalic": "VL-PGothic-Regular",
    "stdBoldItalic": "VL-PGothic-Regular",
    "stdMono": "VL-PGothic-Regular",
    "stdMonoBold": "VL-PGothic-Regular",
    "stdSanBold": "VL-PGothic-Regular",
    "stdSansBold": "VL-PGothic-Regular"
  },
  "styles" : [
    ["base" , {
      "wordWrap": "CJK"
    }],
    ["literal" , {
      "wordWrap": "None"
    }]
  ]
}

PDFを生成する

以下のコマンドで、_build/pdf配下にPDFが生成されます。

make pdf

image

09 Dec 2012, 07:12

SphinxをWindowsに導入していろいろした使い方・カスタマイズまとめ

Sphinx関係の記事をたくさん投稿してきたので、ここらでまとめてみます。

Sphinxとは

Sphinx(スフィンクス)とは、文章を書くためのツール(フレームワーク)

エディタとも、wikiとも分類しがたい、新たな書き方のツール。

Sphinx-Users.jp :: ドキュメンテーションツール スフィンクス Sphinx-users.jp

導入方法はこの記事を参照されたし。

SphinxをWindowsPCにインストールした。

Sphinx導入のメリット

利用すると、以下のことができるようになります。

09 Dec 2012, 06:47

Sphinxからepub形式で出力して、Dropbox経由でiPadから読んでみる

Sphinxは、htmlやPDF以外にも、epub形式への変換をサポートしている。

今日は、epub形式でSphinxドキュメントをビルドして、iPadで電子書籍を読むところまでを試してみた。

ePubとは

ePub形式とは、電子書籍で広く採用されている拡張子の規格。

http://ja.wikipedia.org/wiki/EPUB

Sphinxを利用すると、テキストからepub形式のファイルが一瞬で作成できてしまう!

copy.pyのepubの出版情報を記入する

epub形式での出力のためには、sphinxルートディレクトリにあるcopy.pyにepubの情報を記入してやる必要がある。

そもそも、Sphinxを始めた時(sphinx-quickstart)、epubを有効にしていない場合は、設定する項目すらない。

Sphinx can also add configuration for epub output:
> Do you want to use the epub builder (y/N) [n]:

そんな時は、以下のサイトの下の方に設定情報があるので、それをcopy.pyの一番下にコピペする。(自分はそうした)

copy.pyには以下の情報を記入。

epub_basenameは必須項目。ほかは入れなくても大丈夫っぽい。

epub_basename(必須) epubのファイル名
epub_title epubのタイトル
epub_author epubの作者名
epub_copyright コピーライト

ちなにみに、入力のときは、=u’xxx’な感じで、日本語を使うときにuを入れないとエラーする。uがUTF-8を示す。

# -- Options for Epub output ---------------------------------------------------
epub_basename = 'Shinigami_kai'

# Bibliographic Dublin Core info.
epub_title = u'死神・改'
epub_author = u'神楽家きつね'
#epub_publisher = u'神楽家きつね'
epub_copyright = u'2012 神楽家きつね All right reserved'

make epubでSphinxからepub形式へ変換する

変換元のrst形式ファイルは作成済みであること。

rst形式ファイルからSphinxのmakeコマンドでepub形式へ変換するには、

sphinxのルートディレクトリで以下のコマンドを叩けばよい!(簡単\(^0^))

make epub

すると、./_build/配下にepubディレクトリが作成される。

そのしたに、(copy.pyでいれたepub_basename).epubというファイルがある。

これが、epub形式に変換されたファイルだ。

Droxbox経由でiPhone/iPadからepubファイルを見てみる

epubファイルをDropboxの任意の場所に置いて、iPhone/iPadのDropboxアプリで見てみる。

DropboxDropbox

価格: 0円 iTunesで見る

posted with sticky on 2012.12.9

Dropboxのアプリ自体にepub形式のファイルを閲覧する機能はないので、iOSのデフォルトアプリ、ibookで開くを選択。

skitch

すると、iBookが起動して、電子書籍のように閲覧することができる。
IMG_0014 

参考になったサイト

08 Dec 2012, 12:38

SphinxのRSTファイル編集のためにrst.elをemacsに入れる

せっかく、EmacsでRSTファイルを編集するのだから、Lispを使いたいもの。

というわけで、今日はRSTファイル用のEmacsモード

rst-mode

を試してみる。

rst.elをemacsに入れる

以下のHPをrst.elという名前で保存する。

rst.el

これをload-pathの通ったところに置く。

続いて、以下の行を.emacsに追加。

(自分の場合は~/.emacs.d/init.elファイルに書いた)

;; rst.elを読み込み
(require 'rst)
;; *.rst, *.restファイルをrst-modeでOpen
(setq auto-mode-alist
      (append '(("\\.rst$" . rst-mode)
                ("\\.rest$" . rst-mode)
                ) auto-mode-alist))

これで、キーバインドが使えるようになった。

rst-modeのキーバインド

rst-modeのキーバインドは以下のURLから。

とりあえず、よく使いそうなものを抜粋。

コメントアウト (リージョン指定)M-x comment-region
箇条書き (リージョン指定)C-c,C-b
見出しレベル変更 C-c,C-a,C-a
右にインデント C-c,C-r,
|を入れる C-c,C-d

 

ちなみに、いろんなページに書かれているキーバインドは、自分の環境(Windows Cygwin上のEmacs)では動作しなかった。キーバインドが変わったぽい。

実行すると、下の方に別のコマンドを使ってくださいと説明が出るので、そっちで実行するとよい。もしくは、M-x (関数名)でいける。関数名はこのサイトで調べた。

08 Dec 2012, 11:11

EmacsでSphinxのrstファイルを編集するときの気に食わない白色をなんとかしたメモ

emacsでSphinxの編集をしているとき、rstファイルの見出しが白くなってしまって

読みにくい!(というか、読めない)(¬_¬)

今日はこれをなんとかしようと思う。

Before

skitch(1)

frame-background-mode を有効にする

これを解決するためには、Emacsの frame-background-mode を有効にする。
以下の一行を.emacsに追加。
(自分の場合は~/.emacs.d/init.elファイルに書いた)

(setq frame-background-mode 'dark)

これで、背景が黒色に適した色に変更できる。

after

skitch(2)

参考

frame の色を由緒正しく (?) 設定する for frame-background-mode

08 Dec 2012, 10:08

watchdog(watchmedo)でrst定期監視してsphinxビルド。

今週は、1週間かけて、shinixサイトを立ち上げた。
シェルスクリプトでサーバ公開までを自動化した。
シェルスクリプトがバクっていて、rm -rfでsphinxサイトを完全削除してしまった。

うわ~~~~~ w(◎o◎)w

sphinxでrstファイルを作成したあとに、自動ビルドが実行できたら便利だなと思った。
というわけで、(なんか前置きとつながってないけど)自動ビルドを調べてみた。

2つの方法があるっぽい

  • omake
  • watchdog

今回は、watchdogを試してみた。

watchdogでなにができる?

watchdogとはpythonモジュールの一つ。
この中に含まれる、watchmedoコマンドを使うことで、
ファイルの更新があったときにコマンドを実行できる。

環境

  • Sphinx 1.1.3
  • phthon 2.6
  • Windows 7 64bit

watchdogのインストール

pythonとpython setuptoolはインストールされていることが前提。
(なければこのページを参考にして、インストール)
インストールはコマンドプロンプトからeasy_installを実行する。

easy_install watchdog

watchdogの使い方

watchdogのコマンド watchmodeを利用して更新を監視するには以下のコマンドを叩く。

watchmedo shell-command --patterns="*.rst" --recursive --wait --command="make html"

これで、rstファイルを編集すると、watchmedoコマンドが再帰的に変更されたファイルを検索して、変更を検出したら “make htm”を実行する。

watchmedoコマンドオプション

 

コマンド 説明
-h, –help ヘルプ表示
-c COMMAND,

–command COMMAND
実行したいコマンド
-p PATTERNS,

–pattern PATTERNS,

–patterns PATTERNS

監視したい拡張子を指定
-i IGNORE_PATTERNS,

–ignore-pattern IGNORE_PATTERNS

–ignore-patterns IGNORE_PATTERNS

無視する拡張子
-D,

–ignore-directories
無視するディレクトリ
-R, –recursive 再帰的に監視
–interval TIMEOUT

–timeout TIMEOUT
タイムアウト時間指定
-w, –wait 複数実行禁止
          <p>
            &#160;
          </p>

          <h4>
            参考サイト
          </h4>

          <ul>
            <li>
              <a href="http://tell-k.hatenablog.com/entry/2012/01/04/022229">omakeもmakeも使わずに、Sphinxドキュメントの継続的ビルド &#8211; Study08.net 対シンバシ殲滅用人型機動兵器</a>
            </li>
            <li>
              <a href="http://d.hatena.ne.jp/nullpobug/20120331/1333125058">watchdogモジュールのwatchmedoコマンドが便利</a>
            </li>
          </ul>

02 Dec 2012, 11:24

git commitからJenkinsでSphinxドキュメントをビルド+α

SphinxとJenkinsを組み合わせたら、どんなことが可能なのか考えてみた。

  • (版数管理を前提として)チェックインをトリガにして、Sphinxドキュメント生成。
  • 文字列をカウントして、グラフ化。
  • スペルチェックや表記の揺れをチェック。

結局いろいろ調べて、まだそういうツールないということはわかった。

文字列カウントも、スペルチェックもできないことは分かった。

文字列カウントは make textで生成したテキストファイルをカウントして、グラフ化する仕組みを作れば実現可能かも。

表記の揺れは、Yahoo の提供する校正支援APIを利用すれば、実現可能かも。

http://developer.yahoo.co.jp/webapi/jlp/kousei/v1/kousei.html

というわけで、できることとして、文字列カウントの代わりに、ステップカウントを入れた。

追加で、JenkinsのTask Scanner Pluginを入れた。

こんな流れ

sphinxのファイルをgit commit

Jenkinsにwgetで通知

Jenkinsで make html

Task Scan

ステップカウント

うーん、これではまだまだ使い物にはならないな。

image

01 Dec 2012, 07:13

gitでSphinxのドキュメントを版数管理。commitでビルドさせた。

前回の続き。

Sphinxを試してみた動機は、テキストで版数管理しつつ、WordやWeb形式に変換したいということだったので、今回はgitとSphinxを連携してみた。

Gitリボジトリをつくる

まずは、Sphinxのトップディレクトリでgitのリポジトリを作成。

git init

次に、.gitignoreの設定。

ここでは、ビルドした生産物を除外する。

echo “_*” >> .gitignore

はじめてのコミットをする。

git add .

git commit -m”first commit”

git commit でSphinxを make html してみる

commit後にコマンドを実行するためには、.git/hooks/ディレクトリ配下に、post-commitフォルダを作成し、そこに実行したいコマンドを書く。

というわけで、

cd .git/hooks/

emacs post-commit

post-commtの内容は以下

#!/bin/sh

make html

実行権限を与えて完了

chmod a+x post-commit

 

参考リンク