かわろぐ

技術、セキュリティ、その他もろもろ

MENU

Markdown から pandoc で PDF ファイルを生成する

以前の記事では sphinx を使って Markdown から、PDF形式に変化を試していました。 ただし、表紙を作る方法を発見できなかったので、今回は Haskell で書かれたドキュメントコンバーターの pandoc を試してみました。今回の記事では到達していませんが、最初のファイルに記述することで表紙扱いにすることが可能です。

pandoc をインストールする

前提として、Homebrew はインストール済みであるとします。 Homebrew が入っていれば、 pandoc は以下のコマンド一発でインストールが可能です。なお、LATEX の環境は別途構築済みであるとして進めます。

$ brew install pandoc

pandoc で Markdown を PDF に変換する

今回は、以下の3つのファイルに分かれた Markdown を表紙、目次付きの一つのPDFファイルに変換してみたいと思います。この3つの Markdown ファイルは一つのディレクトリに入っているものとします。

# はじめに

この文章は Pandoc のテストで使う文章です。
# コンテンツだよ

* リスト1
* リスト2

---
# おわりに

終わります。

上記三つの Markdown ファイルを作ったら、以下のコマンドでPDFファイルに変換します。

$pandoc -N --toc --toc-depth=2 *.md -f markdown --pdf-engine=lualatex -V documentclass=ltjsarticle  -o ./test.pdf

こんな感じのPDFができあがります。

f:id:kawa_xxx:20201123164556p:plain

使用したオプションについて

それぞれのオプションの意味は、 man コマンドなどを見てもらうのがいいと思いますが、以下にざっとまとめます。

-N : ページ番号を付与する
--toc : 目次をつける
--toc-depth=2 : 目次にどこまでの見出しを記載するか指定します。この例では2階層目までですね。
-f : インプットファイルのフォーマットです。今回は markdown ですね。
--pdf-engine=lualatex : 
-o : アウトプット先を指定します。

-V 以降のオプションがないと日本語が表示されないので注意が必要です。

長いオプションをなんとかする

pandoc はオプションが猛烈に長くなりますね。コマンドラインで打つのも直すのがめんどくさすぎる!と言うことで、改善しましょう。 pandoc には バージョン 2.8 以降でこの長いオプション類を yaml 形式で記載し、そのファイルを呼び出すことでシンプルにコマンドを実行できます。

input-files:
  - 01.md
  - 02.md
  - 03.md

output-file: test.pdf
table-of-contents: true
toc-depth: 2

pdf-engine: lualatex
variables:
  documentclass: ltjsarticl

このファイルを -d オプションで指定します。

$ pandoc -d default.yml

と、ここまでいろいろ調べましたが、結局最後は、微妙なレイアウト調整がきかずに docx 形式で出力して、手で調整することになりそうな感じを受けています。。。

参考文献

Sphinx で PDF ファイルを生成する

前回の記事で Shinx のセットアップと Markdown を扱えるように設定変更をしました。今回はPDFファイルに出力できる環境を整えた時の備忘録です。

Mac に TeX 環境を作る

公式のドキュメントによると、Sphinx は LaTeXを利用したPDF出力が可能なようです。ということでまずは、TeXの環境を構築します。

私の環境(Mac)ではインストールの完了までに30分程度時間がかかりました。途中でパスワードの入力も求められるのが注意点ですね。

$ brew cask install mactex-no-gui

インストールが終わったら以下のコマンドで環境をアップデートします。これも結構時間かかります。

$ sudo tlmgr update --self --all

Shpinx の設定ファイルを更新しPDF出力する

Conf.py に以下の2行を追加する

# LaTeX の docclass 設定
latex_docclass = {'manual': 'jsbook'}

アップデートが終わったら、前回の記事事で作成した index.md のあるディレクトリに移動し、以下のコマンドでPDFが作成できます。

$ make latexpdf

生成されたPDFファイルを開くと、表紙やら目次やらが自動生成されています。肝心の index.md の内容のページはこんな感じでした。

f:id:kawa_xxx:20200815220456p:plain

ん?ヘッダーはどこ行った?とかデザインがダサいなとかいろいろ問題がありますね。少しずつ調べてきれいなドキュメントをPDFでも出力できるようにしていきたいと思います。

参考文献

https://sphinx-users.jp/cookbook/pdf/index.html?highlight=pdfhttps://qiita.com/t-shmp/items/3588161b92a9a26a351b

Sphinx で Markdown を使えるようにする

前回前々回とエンジニア向けのドキュメントを作る話をしていて、gitbook を使ってみましたが、なんとメンテナンスされていないという自体が発覚しました。最初からちゃんと調べろよという感じですが。。。

そこで Python 界隈でよく使われている Sphinx に狙いを定めました。最初は markdown でないマークアップ言語しか使えないと思っており、敬遠していましたが、プラグインを入れることでMarkdownでもドキュメントがかけるようになっているとのことで改めて調査しました。

今回は Sphinx の環境セットアップとMarkdownでサンプルドキュメントを作るところまでをやってみたいと思います。

環境

  • MacOSX
  • Homebrew

Sphinx をインストールする

Python は Homebrew を使って pyenv をインストールしてあるものと仮定します。 

pip install -U Shinx

クイックスタートでひな形を作る

Sphinx には初期に必要なファイルを自動で生成してくれるツールがあります。 専用に作ったディレクトリの中で、 sphinx-quickstart と打ってみると、設定項目をいくつか聞かれた後に、いくつかのファイルやディレクトリが作成されます。

$ sphinx-quickstart
Sphinx 2.2.1 クイックスタートユーティリティへようこそ。

以下の設定値を入力してください(Enter キーのみ押した場合、
かっこで囲まれた値をデフォルト値として受け入れます)。

選択されたルートパス: .

Sphinx 出力用のビルドディレクトリを配置する方法は2つあります。
ルートパス内にある "_build" ディレクトリを使うか、
ルートパス内に "source" と "build" ディレクトリを分ける方法です。
> ソースディレクトリとビルドディレクトリを分ける(y / n) [n]:

プロジェクト名は、ビルドされたドキュメントのいくつかの場所にあります。
> プロジェクト名: test
> 著者名(複数可): kawa
> プロジェクトのリリース []:

If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.

For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> プロジェクトの言語 [en]: ja

ファイル ./conf.py を作成しています。
ファイル ./index.rst を作成しています。
ファイル ./Makefile を作成しています。
ファイル ./make.bat を作成しています。

終了:初期ディレクトリ構造が作成されました。

マスターファイル ./index.rst を作成して
他のドキュメントソースファイルを作成します。次のように Makefile を使ってドキュメントを作成します。
 make builder
"builder" はサポートされているビルダーの 1 つです。 例: html, latex, または linkcheck。

Markdown 用のプラグインをインストールし、使えるようにする

次に Sphinx で Markdown を使えるようにプラグインを一つインストールします。

pip install recommonmark

インストールが完了したら、先程のquickstart で作った conf.py に以下のように追記します。 Extention 自体は記載があるはずなので、 recommonmark の部分を追記すればOKです。

extensions = [
    'recommonmark'
]

Markdownファイルを Sphinx に認識させるために拡張子と、使うパーサーを同じ設定ファイルに書きます。

source_suffix = ['.rst', '.md']
source_parsers = {
   '.md': 'recommonmark.parser.CommonMarkParser',
}

Recommonmark は table に対応していないようなので sphinx-markdown-tables をインストールします。

pip install sphinx-markdown-tables

Recommonmark と同じく、 extentions に名前を書きます。

Markdown ファイルを作って html で表示してみる

プロジェクトのルートディレクトリにある、 index.rst ファイルは削除してください。このファイルが残っていると、markdown ファイルを指定してもこちらが優先されてしまいます。

今回はサンプルとして以下のようなドキュメントを用意しました。

index.md

# hello sphinx!
スフィンクスで書く最初のドキュメントです。

ビルドし、HTMLファイルを生成するのは以下のコマンドです。

$ sphinx-build . out index.md 

これで out ディレクトリの中に html ファイルが生成されているので、適当なブラウザで表示してみてください。

次回はPDFファイルに出力できる用にしてみたいと思います。

参考文献

https://sphinx-users.jp/gettingstarted/index.htmlhttps://qiita.com/it__ssei/items/2a1205cfd3ac3ee61a57https://qiita.com/unhurried/items/f0372688e8a8485718b5

Anker Soundcore 2 が想像以上にいい音だった話

4、5月の長引くコロナの在宅のなか、子どもたちをあやすためにテレビを見たり、様々な遊びを試みたり。結構なストレスが親にもかかっているなぁと感じていました。

無音の中子どもを相手にするのは割としんどい。なにかBGMを!と思って最初の頃は iPhone から直接音楽を流していましたが、音質も音量もいまいち。そこで思い切って、取り回しやすいコンパクトなスピーカーを買おうと調べてみました。

私はこれまで、スピーカーやイヤホンはBoseと決めていましたが、 Bose SoundLink Mini Bluetooth speaker II は 2万円以上してしまう…。流石に金額的に子どもに壊されたらショックだよなぁ…と思っていました。

更に少し調べてみるとAnkerから同じようなものがでていました。

Anker SoundCore2ですね。

音が上下するようなレビューがありちょっと不安でしたが、5000円を切る価格でBose に近しい音が出るということでダメ元で買ってみました。

が、結果として大正解だったと思っています。

モノラルではありますが、音質もとてもいいし、何よりずんずんくる低音がいい。

そして持ち運びにも苦にならないサイズ感ですし、子どもが持ち歩いて落としてもそんなに危なくない重さです。 肌触りもマットな感じでいいですが、手で触ったあとが多少目立つのが残念ポイントですね。

Bluetoothも切れることなく快適に聞けます。

AUXケーブルも使えるので、使わなくなったらPC用のスピーカかな。

tmux に powerline-status が反映されなかったので調べてみた

これまでは powerline-status を使っていたのですが、 tmux を3.0に更新したあたりから、 powerline-staus を認識してくれなくなってしまいました。

結論から言うと、私のMacは上記の更新をしたタイミングでメインの言語を日本語から英語に変更していました。加えて、環境変数の LC_ALL が定義されていなかったことが原因のようでした。

export LANG='en_US.UTF-8'
export LC_ALL='en_US.UTF-8’  #これが書いてなかった!

どうやって特定したか?

tmux の設定ファイルを変更して、リロードコマンド

$ tmux source-file path/to/.tmux.conf

を打ったら poworline xxx returned 1 という文字列が表示された。これはおそらく何らかのエラーが起きている証だと思いました。

そこで、シェルから直接 powerline-damon を起動させてみると、locale 周りでエラーが出ていました。 Shell の設定ファイルを確認してみると LANG は設定しているけど LC_ALL を設定していないことに気づいたので、LANG 同様に追記して Shell を再起動してtmux を起動してみるときれいなステータスラインが表示されました。

エラーコードとかしっかり書かなくては。とおもって LC_ALL を削除してすべて再起動しても powerline-status はきれいに表示されたままでエラーが再現せず。。。内部でキャッシュしてるのかなぁ。。。?

tmux 2: Productive Mouse-Free Development

tmux 2: Productive Mouse-Free Development

  • 作者:Hogan, Brian P.
  • 発売日: 2016/11/27
  • メディア: ペーパーバック