Drafts

@cm3 の草稿置場 / 少々Wikiっぽく使っているので中身は適宜追記修正されます。

ScholarlyMarkdown の調査 → Pandoc_mmd で代替

ScholarlyMarkdown についての記述は January 31, 2015 時点の ScholarlyMarkdown Syntax Guideに基づいている。

要は下で何をごっちゃごっちゃ（とても長いので興味ない人が読むものではない）書いてるかというと、

  • Markdown で書く新しい論文スタイルは構想しうるか
    • 「論文」という文書のスタイルがある程度決まっているのならば、そこに書く項目も決まっているのだから、初めにタイトルを書く（末尾にタイトルを書く論文なんてわけわからん！）、その次は著者のリスト（著者の前にアブストラクトとか入れるなよ？）みたいに構造を決定することによって、過剰な構文上の拡張なしに Markdown で書くことができるのではないか。そして、意味と見た目の対応を明確にできるのではないか。
    • 著者なら、他の論文にも同じ著者があるだろう、文献なら、同じ文献を参照している論文があるだろう、すべてをネットワークとして表現するには、そういった論文内の要素を繋ぎやすいように、また末尾に詳細を置くようなスタイルで書けないだろうか。
    • 論文のスタイルは、ある程度、今ある様々な論文を表現できたらいいけれど、もっと制限するような形で良い。既存の論文をただ再現するのではなく、以下のようなものを目指す。
      • コーパスとしても利用できる論文
      • 機械の補助で知識共有をより促進できる論文
      • 研究者がレイアウトなどに悩まされず、より内容に集中できるようなフォーマット
    • 最低限、html5 と PDF で綺麗にレンダリングできる必要がある（epubはhtml5に従う。css組版はまだ発展途上だし、ポータビリティの側面からPDFに分がある。docxやodtにも変換できると便利だが優先順位は低い。プレゼン資料は構成が全く違うので無視）。

ヘッダーレベル

HTML Level LaTeX/Word meaning
Header 1 Chapter
Header 2 Section
Header 3 Subsection
Header 4 Subsubsection
Header 5 Paragraph
Header 6 Subparagraph

Title を Header 1 にした方がいいんじゃないか。後述のように title を metadata で書いていて、それが自動でタイトル化されるので、Chapter を Header 1 にしたんだと思う。

f:id:cm3ak:20151020020556p:plain

でも Pandoc で HTML 出力すると、Title も Header 1 になっていてレベルが重複するので、やっぱ本文で使う Header は 2 からだよね。

でも、著者やアブストラクトはどうなるんだ！ってなる。それは次項で述べる。

参考:

著者、各種メタデータ

著者も本文にリストとして書かれているという理解をする。この２つは必須だから。

ScholarlyMarkdown でメタデータの埋め込み方は

---
title: ScholarlyMarkdown Syntax Guide
author:
        - Time Lin
        - Graham Beales
subject: The differences between ScholarlyMarkdown and Pandoc's implementation of Markdown.
date: October 01, 2014
company: University of British Columbia
keywords: markdown, scholarly, scholmd, latex, html, word, docx, guide
---

のような YAML 形式が提案されていて、これは Pandoc の yaml_metadata_block だ。これは、Jekyll の YAML Front Matterと一緒だし、---をなくせばPelicanのMetadataで使われているMultiMarkdownのメタデータ記法に一致する。

これが適切に HTML に出力されるようにすればよい。元々はツールには全く手を加えないことを考えていたので、ツールによる Markdown と HTML や PDF の対応を絶対視して以下のことを考えていたが、「論文」という特定のメディアにカスタマイズして HTML 出力を整えるのは当然だと思う。bibの埋め込みはそれはそれですればいいと思うけれど。

元々の考え

これで abstract 節を書いても HTML 出力や PDF 出力で無視されるし、それならば、上のタイトルに関する修正を施したうえで、

h1+ul>li{
 list-style-type: none;
 display:inline-block;
}

のようなセレクタで著者名を修飾できるようにすればいいので、普通にタイトルに続くリストを著者とすればいい。

あと、HTML 化の時に結合する link 要素（例: <link rel="meta" type="application/x-bibtex" href="metadata.bib" />）で bib ファイルとかにリンクすればいい。少なくとも機械はそちらを読めばいいし。Abstract は統制語彙扱いにしておけば、他のチャプターとややこしくならないので、普通にヘッダーで書く。また、References も同様。中に Bibliography も入ってくるけれど、他も入ってくるので、統制語彙としては References（詳しくは後述）

キーワードとかも書く必要があれば、アブストラクトの末尾に普通の Markdown で書いて、セマンティクスはbibファイルに任せればいい。bib ファイルの生成は、その Markdown を読み取る独自コードがあると便利だけど。

# Title

- [me]
- [you]

## Abstract

...
...

*Keywords:* hogehoge, fugafuga

ジャーナルで末尾に著者情報があるように author もリンクにしてしまって画像などと同様に末尾にまとめて情報を書く。

数式

数式は以下の方法が正式である。

 ```math #yourmathlabel
    \textit{insert latex math code here}
 ```

しかし、

![\frac{2y+3}{x-1}](http://chart.apis.google.com/chart?cht=tx&chl=%5Cfrac%7B2y%2B3%7D%7Bx-1%7D)

のような方法も簡便（参考: グーグルチャートで数式画像作成大きさも一番下の例のように指定できるし、背景色をbg,s,00000000に指定すれば透過にすることもできる。） これだと外部APIに依存してしまうので、永続性が求められる論文データには向かないけれども、要は、[]内にセマンティックスを書いて、画像として見た目をかけるのならば画像張り付けてもいいじゃないかと思う。

そして、引用と同様の方式にすることも可能

![math 1]

[math 1] は周回積分についての公式である。

[math 1]: http://chart.apis.google.com/chart?cht=tx&chl=%5Cdisplaystyle%5Coint+_%7BC%7D%5Cleft%28+Pdx%2BQdy%5Cright%29%3D%5Cint+%5Cint+_%7BD%7D%5Cleft%28%5Cfrac%7B%5Cpartial+Q%7D+%7B%5Cpartial+x%7D-%5Cfrac%7B%5Cpartial+P%7D%7B%5Cpartial+y%7D%5Cright%29dxdy&chs=120&chco=008000&chf=bg%2Cs%2C00000000 "\displaystyle\oint _{C}\left( Pdx+Qdy\right)=\int \int _{D}\left(\frac{\partial Q} {\partial x}-\frac{\partial P}{\partial y}\right)dxdy"

Babelmark 2 - Compare markdown implementationsによると使えないのもちらほらあるが commonmark とかでは意図通りレンダリングされる。

図

図に関しても ScholarlyMarkdown は独自拡張が大きい。

#### Figure: this text is ignored {#figure2}

![look at me](sealbaby.jpg){#sealA width=50%}\
![and also me](sealbaby.jpg){#sealB width=30%}
![](sealbaby.jpg){#sealC width=same}

Caption: Look at all my baby seals!

で、

f:id:cm3ak:20151019004419p:plain

のようなレンダリングが得られるというのだが、Scholdoc | a fork of Pandoc that understands ScholarlyMarkdown以外の Markdown レンダラ―では解釈できない。

それより

![Fig 1]

2014 年時点で [Fig 1] のような分布になっている。

[Fig 1]: http://previews.figshare.com/2258234/preview_2258234.jpg "Location of Journals using Open Journal Systems as of September 2015"

のように記述したほうが統一性が取れる。figshare - credit for all your researchのように図など細かい単位で共有できるプラットフォームは既にあるのだからそれを活用するという発想だ。

画像の下にキャプションを付ける実装は Pandoc と Minima しか確認できなかったが、独自実装色は薄いのではないか。

参考文献

詳しくはまた追記するが、NDL か WorldCat のデータをリンクとしてつけておいた方がいい。

ちなみに、例えば、The religion of Java (Free Press): 1960｜書誌詳細｜国立国会図書館サーチ から https://lccn.loc.gov/59013863/dcみたいなのにリンクが張られているのね。

末尾

この方式に統一したら、参考文献、画像、数式へのリンクが末尾にずらずら並ぶ。Markdown で基本的に参考文献章が見れなくなってしまう（上の表記だと、リンクとしてしかレンダリングされず、末尾の文字列は大抵なくなる）のは、論文ではない一般の文書だと、外部リソースの扱いに無頓着だということの証左だと思うが、やはり論文ではそれらを区別して見たいので、## References の下の ### Bibliography ### Figure ### Formula ### Authors にそれぞれ書くというのはどうだろうか。

Yet Another Xanadu?

僕の提案している方法はどれも、外部へのリンクを含めて論文を構成する方法だ。これは Semantic Web の亡霊だし、Xanadu の亡霊だ。それへの反発はもちろん分かっている。リンク切れだ。そういう時に現実的な解はもう知っている。「今まで通りの情報にプラスしてリンクがつけられる。そして、手間は増えない。」すでに文字情報はそれを満たすように設計してある。画像だけはそれが難しかったので、

<http://previews.figshare.com/2258234/preview_2258234.jpg> owl:sameAs :fig1.jpg

のようなメタデータと画像をセットにしておくしかないと思う。メタデータへのリンクは本文に

<link rel="meta" property="meta" type="application/rdf+xml" href="metadata.rdf" />

のように書いておくのがいいと思う。

参考:

ToDo

  • 僕も Lin さんみたいに Pandoc のモジュール作らないと、ここで構想だけしててもダメ。でも、もう少し練らないと、歪んだ車輪の再発明になってしまう。
  • A Call for Scholarly Markdown - Gobbledygookを読んだ。読んだ結果、Pandocが引用などほとんどの機能を有しており、それで書ける範囲を上限にすべきだと思った（Multimarkdown でもいいけれども、現在の開発状況などから前者が優勢 fletcher/MultiMarkdown-4 vs jgm/pandoc でもドキュメント読むと、ほぼ Pandoc ⊃ MMD）。僕が ScholarlyMarkdown で気持ち悪いと思った独自実装はそれですべて解決するし、リッチなメタデータとかは上で書いたように外に出せばいい。だから、「Pandoc Markdown で論文をどのようにコーパス化するか」を Documentation する。初めから論文を Pandoc Markdown で書く方法も模索する。
  • でも基本的には CommonMark に基づく。つまり、CommonMark に少しだけ Pandoc 独自の記法を足して構成する。
    • 上で好んで使っている記法は、Pandoc だと、Extension: shortcut_reference_links で、多くの実装で用いられている。
    • メタデータは Pandoc の yaml_metadata_block でもよかったが、mmd_title_block を採用する。これと上で考察したタイトルを # で書くことが整合するか確認する必要がある。 pandoc の mmd_title_block は使い物にならなかったので、上の考察のとおり、普通に書くような仕様にする。
    • 表は Pandoc が普及しているもののかなり独自で、bebelmark 使ったら Pandoc でしかレンダリングに成功しないものも。表を Markdown の記法に制限されないように専用のツールとか欲しいくらい。一応 pipe_tables は採用。
    • H~2~O で H2Oとか、2^10^ で 210 とかは便利なので導入してもいいが採用例が少ないので、raw_html で書く。例: H<sub>2</sub>O, <sup>10</sup>
    • 数式は基本的に tex_math_double_backslash を使うけれども（mmdと共通）、上の画像による記法も、commonmark でできるから、正式にしておく。
    • citation の拡張は独自色が強すぎる（Markdown variantsのどれでも採用されていない）ので、上の考察の通りにする。
    • footnotes 拡張は採用する（phpextra でも mmd でも使われている）
  • 結果的に、pandoc の markdown_mmd varitant が標準のレンダラ―になる。js だと multimarkdown でプレビューできるが、上記のようにプレビューは commonmark で、論文作成レベルになったら、pandoc-mmd でやる。
  • Pandoc vs Multimarkdown · jgm/pandoc Wiki 基本的に変換するつもりなら、Pandoc 上の variant で試した方がいい。つまり、どれだけ方言許容しても、実装としては Pandoc を使えと。

いろいろ試してみた

f:id:cm3ak:20151020032748p:plain

けっこう綺麗にレンダリングできてるじゃん。でも、PDF だとボロボロ。なぜ？だって、画像とかが外部リンクだから！！「外部へのリンクを含めて論文を構成する方法」は HTML への変換は問題ないけど、PDF に変換するのに一筋縄ではいかない。だから、ローカルのファイルで構成して、＋αで外部リンクという方式にする方がいい。もちろん、PDF 変換の部分を、wget 的なプログラムかませてローカルファイル構成を自動化して… という方法もあるけど、あまりメリットがない。--self-containedというオプションで HTML でも PDF でもファイルをローカルにもってくることができるようなので、あまり気にしなくてよいと思う。

いろいろ考えなおそう。まず、できなければいけない出力フォーマットは次の３つくらいを想定している: html5, epub, PDF。でも epub は詳しくないし、epub 3 なら中身は html5 だったりするので、考えるのはまず html5 と PDF。それぞれのワークフローは以下の通りで、今回は HTML 化を優先。

f:id:cm3ak:20151020034802p:plain

参考:

  • commonmark.js demo commonmark での変換を確認。比較はbabelmarkが便利だけど、commonmark 単独だと、これの方が便利。

追記