議論と細かいノウハウ - doc-wiki-jp/wiki GitHub Wiki

日本Pandocユーザ会 Slackにおける、長めの議論やノウハウのログ。

文書における italic と emphasis について

みんな italic 使ってるんでしょうか?
- そもそもみんな強調マークアップ(斜体マークアップ)を使っているのだろうか、と。
- 新しいマークアップ言語を作ったときに、斜体を表すマークアップって必要なのか、と。
日本人的な感性かもしれませんが、下線とか赤字(or マーカー風ハイライト)だったり、そういう表現のほうが嬉しいんですけどねえ。
日本語だと漢字と相性が悪い (字形が複雑で判別しづらい、フォントの問題など) ので、あまり使われていないようなきがするんですが僕のまわりだけなんですかね。
Markdown だと *text* は emphasis と定義されているので、そこを間違って理解しているのかも…?
- 別のセマンティクスのはずなのに、同じとみなしちゃってる、ということでは。
iは、HTML5的には「文章中で抑揚が変わる箇所」なんですよねー
- 専門用語とか定義済みの用語に使うことが意図されている

Markdown treats asterisks (*) and underscores (_) as indicators of emphasis. Text wrapped with one * or _ will be wrapped with an HTML tag; double *'s or _'s will be wrapped with an HTML tag.

(ttps://daringfireball.net/projects/markdown/syntax#em)

元祖markdown では emphasis / strong という意味しかうたってない(表現についてはノータッチ)というか、HTML 側の <em>, <strong> と同じ意味だよ、と宣言してますね。
LaTeX視点: 表現に対応づけたい気持ちはわかる
- ターゲットが紙だけなので
HTML視点: 文書構造とスタイルは別物
- だから、italic とか bold みたいな直接的な装飾が出てくるとぎょっとしてしまう。
この話題は色んなレイヤーの話が混じっているので、整理してみます。
1. 英語圏の出版文化において、文字修飾（見た目上の斜体や太字）に対する意味はどうなっているか？
2. 日本語圏の出版文化（写植〜DTP）において、どんな文字修飾があり、文字修飾に対する意味はどうなっているか？
3. 既存の実装として 、HTMLやMarkdownは文字修飾に対して現状どのような意味づけをしているのか？（おそらく、英語圏の1.を参考にできる）
  - b 要素は文章のなかで、とくに付加的な重要性を与えるわけでも、異なるトーンや雰囲気を表現するわけでもないが、実利的な理由から注意を引きつける箇所を表すようになりました。たとえば文書の概要におけるキーワードや、レビューにおける製品名、対話的なテキストベースのソフトウェアにおける実行可能箇所、記事のリード文などが当てはまります。
  - i 要素は文章のなかで、異なったトーンや雰囲気、もしくは他ののテキストと性質が異なる箇所を表すようになりました。たとえば分類、専門用語、他言語での慣用句、考え、アルファベットでの船舶名表記などが当てはまります。
  - u 要素は、音声では明示化されることはないものの明示的に区別して表示される、文意に影響しない注釈を表します。たとえば、中国語での固有名詞や、スペルミスのある単語の指示などに利用されます。
  - strong 要素は、文章の一部を部分的に強調するものではなく、文章の重要度を示すものとなりました。
  - HTML5の変更例として面白いのは b,i,u要素とかかな。
    - 参考: http://standards.mitsue.co.jp/resources/w3c/TR/html5-diff/#changed-elementsより抜粋です。また、http://www.mdn.co.jp/di/articles/4040/?page=3
4. 実装案の提案として 、日本語用マークアップ言語を新しく作るとしたら、どのような文字修飾をどのような意味づけで定義すべきか？（おそらく、日本語圏の2.を参考にできる）
5. 英語圏プログラマの文化において、どんな文字修飾があり、文字修飾に対する意味はどうなっているか？（これについては、manページ(roff/groff)などが参考になるかも）

細かいノウハウ

Pandoc Filterのデバッグ

JSONに吐き出して、それPythonなどに食わせる
- pandoc -f md -t > hoge.json として、JSONを吐き出しておいて
- cat hoge.json | python ./filter.py でPythonレベルでprintfデバッグ

PandocのPDF出力ベストプラクティス

組版はそこそこでいいから、気軽に出したい: wkhtmltopdf

wkhtmltopdf
- 元々はHTMLをPDFに変換するためのツール
  - CSSでスタイルのカスタムも可
- Pandoc（最近のバージョン）は、これをPDF出力エンジンとして利用できる
- 逆に言えば、PandocからPDFを直接出力させたいなら、wkhtmltopdf（またはLaTeXエンジン）を事前にインストールする必要がある
パッケージを直接落としてインストール
1. ここからパッケージをダウンロード
  - Windowsは未検証ですが、MinGWの方を試してみてください
2. インストール
パッケージマネージャでインストール
- Mac: $ brew cask install wkhtmltopdf
  - Caskの方なので注意
使い方（少し紛らわしいので注意）
- 出力フォーマット: -f html5
- 出力ファイル名: -o (ファイル名).pdf
- 例: $ echo "**Hello**" | pandoc -f markdown -t html5 -o hello.pdf
  - （PDFが生成される）

綺麗に組版された文書を作りたい: LaTeXエンジンを使う

BXjsclsパッケージ
- pdflatex, lualatex, xelatex, uplatex, platex で使用可能な日本語文書組版のための LaTeX 文書クラスのコレクション
- BXjscls は新ドキュメントクラスから pLaTeX 依存の部分を分離したもの
  - これと各エンジン用の日本語処理パッケージを組み合わせることで，pLaTeX 以外でも新ドキュメントクラスを用いた場合と同等の文書作成が可能に
- Pandocでの使用
  - PandocのPDF直接出力(LaTeXエンジン使用時)はpdflatex, lualatex, xelatexのみ対応
    - さらに、pdflatexは日本語に（原則として）対応しないため、日本語を扱う場合はlualatexかxelatexのみ
  - BXjscls自体に「Pandoc」モードがあるらしい
    - BXjsclsを併用すると、Pandocから日本語かつ綺麗なPDF出力を得られる（はず）

使用例

参考: BXjscls がまた新しくなった（v1.1a） - マクロツイーター

あらかじめTeXLiveまたはMacTeX(Macユーザのみ)をインストールしておく。

例えば「LuaLaTeX を経由、文書クラスは（Pandoc モードの）bxjsarticle、用紙サイズは A5 縦、和文フォント設定は ipaex」という設定で PDF 文書に変換する場合は以下のコマンドを実行する:

$ pandoc sample.md -o sample.pdf --latex-engine=lualatex \
  -V papersize=a5 -V documentclass=bxjsarticle \
  -V classoption=pandoc -V classoption=jafont=ipaex

とコマンドを打てば、内部で生成されるLaTeXファイルには

\documentclass[pandoc,jafont=ipaex,a5paper]{bxjsarticle}

と書かれて、それをLuaLaTeXが適切に解釈してくれる（はず）。

余談: PandocのVariableを用いた指定

ちなみに、-Vで指定されるものはVariableというのですが、これはコマンドで指定する必要は無く、代わりにMarkdown文書(ここではsample.md)の先頭でYAML metadata blockとして指定できるはずです。

---
title:  'This is the title'
author: The Author
papersize: a5
documentclass: bxjsarticle
classoption: pandoc
classoption: jafont=ipaex
...