読者です 読者をやめる 読者になる 読者になる

FPGA開発日記

FPGAというより、コンピュータアーキテクチャかもね! カテゴリ別記事インデックス https://sites.google.com/site/fpgadevelopindex/

マニュアルなどの文章をRestructuredTextに移行した

しっかりした文章や、マニュアルなどを作成してpdfやhtmlとして公開したい場合や他人に見てもらいたい場合、いくつかの方法が存在する。

  • LaTeX : それなりに昔から使われている文章整形ツール。非常に美麗な文章が作成できる。数式などもお手の物。ただし作成したり習得したりするのに時間がかかる。
  • Markdown : 最近有力な文章フォーマットになってきている。マークアップなので非常に整形が容易。また習得も簡単だし対応しているウェブサービスが多い。表の作成や文章整形の細かさに難が残る。
  • Textile : Redmineなどで使われている文章フォーマット。Markdownと比べて有名ではないが、Redmineが標準でこの形式なので使っている人も多いのではないか?表作成の細かさではmarkdownよりも上。
  • RestructuredText : MarkdownやTextileと似ているフォーマット。Sphinxというビルドプラットフォームと一緒に利用するのが一般的。RestructuredTextのフォーマットをそのまま使用するというよりも、一度Sphinxによりビルドして、htmlとかpdfに変換して使用することが多い。表作成の細かさなどでmarkdownより上。

という訳で、pdfに変換したい、かつ詳細な表などを利用した文章を作成したいということで、RestructuredTextを利用することにした。

RestructuredText事始め

Sphinx環境インストール

RestructuredTextの環境をWindows上に構築するのはちょっと厄介なので、手っ取り早くUbuntu Linuxの上に構築した。構築する手順は簡単にここに記録しておく。

sudo apt-get install python-sphinx
sudo apt-get install texlive texlive-lang-cjk

Sphinx環境でのビルド

pdfでの日本語環境構築方法は以下。まず、conf.pyを以下のように変更しておく。

language = 'ja'
latex_docclass = {'manual': 'jsbook'}

日本語環境でのビルド方法は以下となる。

make latexpdfja

面倒くさいテーブルの構築

RestructuredTextのテーブル構築は結構面倒だ。テキストエディタで整形するのは結構大変なので、まずはExcelで作るようにしている。

f:id:msyksphinz:20170102230341p:plain

次に、以下のページを使って、テーブルを整形した。

www.tablesgenerator.com

[File]-->[Paste table data]から、Excelのセルをコピーしたものを貼り付ける。

f:id:msyksphinz:20170102230501p:plain

セルを接続したい

以下のボタンで接続できる。

f:id:msyksphinz:20170102230658p:plain

f:id:msyksphinz:20170102230804p:plain

ただし若干の注意事項がある。このテーブルはRestructuredTextの記法と少し異なっており、きちんと表示させたければ、以下のように修正する。

  • 修正前
+---------+-------+-------+--------------+--------------------------------+
|                             ユーザモードCSR                             |
+---------+-------+-------------------------------------------------------+
| 00      | 00    | XX    | 0x000-0x0FF  | 標準  読み書き可能             |
+---------+-------+-------+--------------+--------------------------------+

f:id:msyksphinz:20170102230937p:plain

  • 修正後
+---------+-------+-------+--------------+--------------------------------+
|                             ユーザモードCSR                             |
+---------+-------+-------+--------------+--------------------------------+
| 00      | 00    | XX    | 0x000-0x0FF  | 標準  読み書き可能             |
+---------+-------+-------+--------------+--------------------------------+

f:id:msyksphinz:20170102231139p:plain