個人出版・AI校正

vscodeでpandoc 3の使い方/商用利用やライセンスは?Re:VIEWとSphinxとの比較

個人出版・AI校正

pandocの使い方覚書です。ePUBとHtmlの出力に主に利用しています。

pandocはmarkdown preview enhancedとあわせて使うと便利です。

Re:VIEWとpandocとSphinxの比較

pandocを使う前にいろいろと検討しました。

markdown系のソフトもエクスポートにpandocを使っているため、より柔軟性があるpandocに。

pandocとよく比較されるものに次のものがあります。

ライセンス
言語
pandoc
GPL v2
node.js
Re:VIEW
LGPL が適用される Re:VIEW のプログラム
MIT が適用される Re:VIEW のテンプレート
Ruby
Sphinx
修正BSDライセンス
Python

言語とライセンスが違います。あと、使ってないため何とも言えませんがSphinxはドキュメンテーションジェネレータというカテゴリなのでしょうか。pandocやRe:VIEWは技術同人誌でよく使われています。

日本製ならRe:VIEW、海外製ならpandocやSphinxという単純な理解をしました。

Re:VIEWのメリットデメリット

Re:VIEWのメリットデメリットです。Re:VIEWとPandocを使っている人が多そうでした。

  • 使っている人が多いため情報が豊富でした。
  • テンプレートもあります。
  • Re:VIEWはRubyのインストールが必要ならしいです。
  • LATeX。組版といえどもそこまでPDFを作るのに、結構、細かすぎるかなと思い、
  • また、デザインの柔軟性が欠ける情報もありで見送り。

ライセンスについてはこちらです。

Re:VIEWは未使用のため、もしかしたらもっといいところがあるかもしれません。

Re:VIEW のプログラムには、「GNU Lesser General Public License Version 2.1」(以下LGPL)が適用されます。

EPUB / TeX 用のレイアウトテンプレート、TeX 用のスタイルファイルについては「MIT License」(以下MIT)が適用されます。

TeX (pdfmaker)向けに内包している jumoline.sty スタイルファイルには「The LaTeX Project Public License」(以下LPPL)が適用されます。

https://review-knowledge-ja.readthedocs.io/ja/latest/faq/faq-license.html

pandocのデメリットとメリット

  • 使っている人が多いため情報が豊富でした。
  • Pandocのインストールほか、日本語対応も必要です。
  • node.jsを使っているjavascript系の人はこっちがいいかも。
  • LATeX(個人的にCSSの方が取っつきやすいというだけです。人により違うかもしれません)。ただし、ePUBやHtmlは関係ない
  • デザインの柔軟性がかけるっぽい。。

Re:VIEWとPandocのどちらかを少し使ってみようと思っていたところ、

個人的にnode.jsが入っていたためpandocを使うことに。Pandocがライセンス的には1番厳しいGPLで多少気になる人もいるかもですが、いうても電子書籍のソースコードなんかテンプレートを使うならHtmlやCSS程度で大したものではないですし。

Pandoc導入1年後の感想

不満点はほとんどないけど、

  • コードブロックのファイル名をQiita風に書きたかった。 →luaのフィルターを使ったら簡単に解決できました。
  • htmlのテンプレで目次じゃなくてmdのファイル名のリストを取得する命令がないっぽい。章のファイルが増えるたびに手動追加。 →Node.jsでスクリプトをかいて解決

デフォ機能ではできないっぽい。

他はかなり満足しています。PDFは直接出力するより、1回Wordに変換する方法がよさそうです。VivliostyleというCSS組版もあります。

スポンサーリンク

pandocの評判(商用利用もあり?ライセンスは?)

普通に出版社さんが使っているようですね。

All code must be released under the general license governing pandoc (GPL v2).

https://pandoc.org/CONTRIBUTING.html

公式サイトをみるとGPLのようですね。WordPressと同じといえばわかりやすいでしょうか。

  • 有料テーマも販売できるけどGPLライセンスになる(Pandocを使っているTyporaも有料)
  • ソースコードの公開が必要
  • 配布しない限り、ソースを公開しなくていい

みたいな感じだった気がします。

販売についてはこちら!

詳しくは専門じゃないので本に譲ります。

著:上田 理, 監修:岩井 久美子
¥3,168 (2022/09/13 15:18時点 | Amazon調べ)
著:姉崎章博
¥2,010 (2022/09/13 15:22時点 | Amazon調べ)

Pandocは個人的にもなかなかいい気がしますね。

(追記)markdown preview enhancedのエクスポート機能は使わず、markdown preview enhancedはプレビューのみにして、pandocでエキスポートが最適解になりつつあります。

スポンサーリンク

pacdocの使い方の電子書籍

解説本はこちらの洋書です。

markdownの書籍でも少しだけ紹介されていました。

pandocはシェルスクリプトの知識があると、いろいろ自動化できます。

スポンサーリンク

vscodeでpandocの使い方

pandocのインストールと基本的な使い方

長くなったため、noteに寄稿しました。

pandocの目次

2階層目まで目次をつけます。mdの上部に目次がつきます。

pandoc -s --toc --toc-depth=2 test.md -o test.html

--toc--table-of-contents

出力文書に自動生成された目次を含めます

https://pandoc-doc-ja.readthedocs.io/ja/latest/users-guide.html

--toc-depth=NUMBER

目次に含めるセクションレベルを指定します。既定は3です

https://pandoc-doc-ja.readthedocs.io/ja/latest/users-guide.html

ただ、サイドバーに目次をつけたいですかね。サイドバーで目次をつける際はMarkdown Preview Enhancedを使う方法もあります。ただpandocでつけた方がソースコードは扱いやすいですね。

スポンサーリンク

pandocのhtmlカスタムテンプレート

pandocのhtmlカスタムテンプレート

pandoc -D html

このコマンドはテンプレートファイルを作成するのではなく、コマンドラインやターミナルの画面上に直接表示するだけです。

pandoc -D html > mytemplate.html

テンプレートを生成したい場合は、このコマンドです。同階層に作られます。htmlをカスタマイズしたい場合、mytemplate.htmlをいじるとよいです。

変換する際はテンプレートを割り当てます。

pandoc -f markdown -t html --template=mytemplate index.md > index.html    
pandoc -s sample.md -c ./theme/css/base.css --template=template/mytemplate.html -o sample.html

–templateは拡張子をつけてもつけなくても通りました。

各コマンドの補足です。

ファイルへ出力したい場合は -o オプションを使用してください

https://pandoc-doc-ja.readthedocs.io/ja/latest/users-guide.html

Pandoc は分割された文書群を生成します。スタンドアロン文書(例えば、 <head> と <body> を含む有効な HTML ファイル)を生成するには、 -s または -standalone フラグを使います:

https://pandoc-doc-ja.readthedocs.io/ja/latest/users-guide.html

入力形式の指定は -f/--from オプションを、出力形式の指定は -t/--to オプションを使います。

https://pandoc-doc-ja.readthedocs.io/ja/latest/users-guide.html

pandocのカスタムCSS

単純な外部リンクになりますね。もとから適応されるスタイルシートはなくなるようです。逆に指定しないとデフォルトのCSSが入るため注意です。

同階層の場合です。

pandoc -s sample.md -c base.css -o sample.html

複数のときはこう。

pandoc -s sample.md -c base.css -c theme.css -o sample.html

まとめ

まとめるとこんな感じです。

pandoc -s sample.md -c base.css --template=template --toc --toc-depth=2 -o sample.html

pandocでJavaScriptを追加

次のものを使うと、各々の場所に追加されます。

--include-in-header=FILENAME                    
--include-before-body=FILENAME                  
--include-after-body=FILENAME   

JavaScriptはbodyの前でしょうから–include-after-bodyで指定してあげます。

読み込むJSのファイルは外部ファイルと違ってあらかじめscriptで囲う必要があります。

<script></script>

pandocでコードブロック(シンタックスハイライト)を追加

長くなったため別記事にしました。

pandocのメタデータ

markdownファイルの1番上に記載する感じです。

タイトルは最低限必要です。

---
title: "タイトル"
---

htmlの場合、メタ情報が変更されることはもちろんタブに表示される名前が、ファイル名からタイトルに変わります。

ePUBの場合、画面上がタイトルになります。mdを1つだけ変えると全般的に反映されてしまうようです。

$author$

デフォルトテンプレートがforになっていたため、少し謎でした。

$for(author)$
<p class="author">$author$</p>
$endfor$

どうやら引数が複数あるので、forを使っているようです。

---
author:
- neru
- kun
---

$date$

dateは引数ひとつのようです。日付を表示します。

$if(date)$
<p class="date">$date$</p>
$endif$

自動で表示するわけではなく、YAMLの指定が必要です。

---
date: 2021/04/27
---

$abstract$、$include-before$

$abstract$は文書の要約に使うみたいだけど、個人的に使わなさそうなのでテンプレートから削ってしまった。$abstract-title$も同様。必要なら戻せばいいし。

$include-before$も用途がいまいちわからないので消し。あんま調べてないけど。。

$styles.html()$

  <style>
    $styles.html()$
  </style>

あまり詳しく調べていませんが、こちら削ると、コードブロックなどのスタイルが無効化されますね。

スポンサーリンク

pandocのePUB編

表紙をつける

 pandoc -s sample.md -o sample.epub --epub-cover-image=theme/images/cover.png

ePUBのスタイルシート

–epub-stylesheetは使わないでください。過去のもののようです。

Removed –epub-stylesheet; use –css instead

https://github.com/rstudio/bookdown/issues/478
pandoc $(dir *.md) -c base-epub.css -o export.epub

ePUBのCSS、tips

ePUBのCSSってシンプルになりますかね。

htmlと違ってメニューも勝手にできます。

そのためePUBは専用のCSSを作成します。一部のコードはそのまま使いまわしがききますかね。

なおコードブロックは全部折り返した方がよさそうですね。

white-space: pre-wrap;

ePUBのリーダーは背景色を変更できるものが多いです。background-colorは透明度を指定する形で見せた方がよい気もします。

目次をつける

pandoc  $(dir *.md) -o output.epub --toc --toc-depth=2

なお、AppleBooksなどでメニューから開く目次は、この指定をしなくても勝手につくようです。あくまで本の最初に目次ページを作るか否かです。

ePUBは文頭に目次を入れていない場合もあるようです。UIに目次がついていますから、そのように割り切っているのでしょう。

html書き出し時に使った目次は使えなかったため、このePUBの目次を使わないとダメなようです。

目次の数字を消す

/* 目次の数字を消す */
nav ol {list-style-type: none;}

目次のタイトルを消す

目次って普通、”目次”と表示されるのですが、Pandocの本のタイトルが割り当てられています。

CSSで消してしまいましょう。

/* 目次のタイトル消す */
nav #toc-title { display: none; }

新規で追加したい場合はePUBのカスタムフォーマットでいけるようです。

$if(navpage)$
<h1>目次</h1>
$endif$

pandoc作者さまのコメントを参考にしました。

Try putting this inside a conditional

$if(navpage)$

$endif$

That variable is set for nav.xhtml but not the
other pages.

https://github.com/jgm/pandoc/issues/4829

ePUBの改ページ(見出し)

ePUBの改ページをする方法は2とおりあります。

1つはpandocのコンバートするときに指定してあげます。デフォルトではh1の見出しのみ改ページされます。ただ、見出しにh2で使っていると、ePUBが前の章と繋がってしまって見栄えが悪いです。

その際は変換する際に次のオプションを指定するとh2の見出しまで改ページされます。

--epub-chapter-level=2

この指定によりxhtmlがどの単位で分割されるかが決まります。

ePUBは拡張子をzipに変えると中身を見ることができます。見出しを細かく分割するとxhtmlが増えているはずです。

ePUBの改ページ(CSS)

もう1つはcssで分割する方法です。長いリストやコードブロックなどうしても1つのページにおさめたいとき便利です。

区切り線のhr改ページできるように。

/* 改ページ */
hr.pagebreak {
  height: 0;
  visibility: hidden;
  border: 0;

  /* page-break-after: always; */
  break-after: always;
}

老舗とほほさんの記載によると、page-break-afterからbreak-afterになったようです。

印刷時に、page-break-before は要素の直前で、page-break-after は要素の直後での改ページを制御します。CSS3 では、改カラムを制御する機能が拡張された break-before, break-after に移行される予定

https://www.tohoho-web.com/css/prop/page-break-x.htm

ヘッダー・フッター

デフォルトの場合、ヘッダーに本のタイトル、フッターにページ数が入るようです。Apple Booksで確認。

ePUBのデータサイズが大きい!

単純に画像やgifなど動画系のデータが大きくなっていることが多いですね。圧縮し忘れなど。9999kbぐらいにおさえたいですかね。

ePUBの拡張子をzipファイルにして調査するとわかります。

コマンドが長いから、設定ファイルをYAMLファイルに書く

ePUBを真面目につくればつくるほど、ePUBのコマンドが長くなります。コピペで使っていても見にくいと感じる人がいるでしょう。Default fileがPandoc 2.8以降使えるようになりました。

New FileでYAMLファイルを新規生成します。

YAMLファイルはコメントもかけます。

# 入力
input-files:
- test.md

# 出力
output-file: outputfile.epub

YAMLの詳しい使い方は適当に調べましょう。

どんなオプションがあるのかは公式サイトをみましょう。

Default fileのGeneral options以下です。

次のコマンドでコンバートできます。

pandoc -d epub.yaml

pandocのepubカスタムテンプレート

htmlのカスタムテンプレートを考え方は一緒です。

pandoc -D epub

ただ、コードを確認したところ、htmlのテンプレートと中身はもちろん違いましたね。ePUBはePUBのカスタムテンプレートを使う必要がありそうです。

生成はこうやります。海外も含めてほとんど情報がなかったのですが、たぶんxmlファイルのテンプレでいいんじゃないかな。

pandoc -D epub > epub.xml
pandoc -D epub3 > epub3.xml

どちらも中身は一緒です。

(追記)xmlでも特に問題なさそうだったのですが、こちらの方がいいかもです。拡張子はepub3です。epubにするとVsCode上でコードが見えないなんていう理由もあります。

pandoc -D epub3 > custom.epub3

デフォルトのテンプレート自体はこちらから見れます。

なぜテンプレを作ったのかといえば、1ページ目に挟まるヘッダーみたいなものが邪魔だったから少しカスタマイズしたかったからです。

子のテンプレもyamlから読み込めばテンプレもOKです。

スポンサーリンク

PandocでPDFの書き出し(Wordのテンプレートにした方がよい!?)

長くなったため別記事にしました。

スポンサーリンク
neruをフォローする
スポンサーリンク

コメント

タイトルとURLをコピーしました