org-mode のリスト要素と export について
概要
作成.
org-mode の極めて初歩的な要素 list だが、標準のエクスポーター
org-html-export-to-html,
org-html-export-as-html で出力する時にハマりどころがある。
リストの出力だけで、どれほど奥が深いか分かってもらえるはずだ。
リストの種類
.
org-mode のリストには 標準リスト, 順序リスト, 説明つきリスト の3種類がある。
標準リストは:
- こんな
- ふうに
- 見える
[-]チェックボックスつきは混ぜ書きOK[1/2]- 子リスト
[X]子チェックボックス[ ]子チェックボックス- [ ]は<li class="off"><code>[ ]</code>〜</li>になる- [X]は<li class="on"><code>[X]</code>〜</li>になる- [-]は<li class="trans"><code>[-]</code>〜</li>になる
- リストの頭
-,+1.,1)などができるが、混ぜ書きは出来ない -,+は区別なく<ul class="org-ul">〜</ul>のなかの<li>〜</li>になる1.,1)は区別なく<ol class="org-ol">〜</ol>のなかの<li>〜</li>になる
順序リストは:
[X]順序つきリストもチェックボックスになれる(混ぜ書き可能)範囲内のリストは自動的にナンバリングされて出力される
ここでいう範囲とは、- 同じ序列(等インデント)をもつリスト群
- 行間が0行または1行空けた1リスト群
のことで、このリスト群に入った混ぜ書きができない要素は その内の先頭の要素に強制的に変形される(例)。
このリスト群に入った混ぜ書きができる要素は先頭の要素の影響を受けない。
なので、異なるリストのタイプを 続けて 使うときは 2 行以上空ける必要がある。
ただしリストと等インデント、または親インデントをもつ別要素2が挟まれたら改行の必要はなくなる。- こうすると順序を強制できる(
[@10000]の挿入) - 更にそのまま続く3
- 減らすこともできる(
[@42]の挿入)
説明つきリストは:
- 難しい用語
- 用語の説明
改行(文末の\\が<br>になる)でインデントして継続できる(どのリストでも出来る)htmlでは<dt>用語</dt><dd>説明</dd>と出力される [ ]チェックリスト- やはり混ぜ書き出来る
- 子要素
- 説明つきリストと普通のリストの争い(先に来る要素が強い)
- タイトルつきリストが export 時に見えなくなってしまう
– (上下の 2 項目は順序のみが逆) –
- 内部では見えている筈の
- タイトルつきリストが export 時に見えなくなってしまう
- (no term)
- 説明つきリストと普通のリストの争い(先に来る要素が強い)4
ソースコード
.
リストの種類でどのような .org ファイルを書いたのかを示す。
どう書けばどう出力されるのかを見比べてみてほしい。
=org-mode= のリストには /標準リスト/, /順序リスト/, /説明つきリスト/ の3種類がある。 標準リストは: - こんな - ふうに - 見える - [-] チェックボックスつきは混ぜ書きOK[1/2] - 子リスト - [X] 子チェックボックス - [ ] 子チェックボックス - =- [ ]= は ~<li class="off"><code>[ ]</code>〜</li>~ になる - =- [X]= は ~<li class="on"><code>[X]</code>〜</li>~ になる - =- [-]= は ~<li class="trans"><code>[-]</code>〜</li>~ になる + リストの頭 =-=, =+= =1.=, =1)= などができるが、混ぜ書きは出来ない + =-=, =+= は区別なく ~<ul class="org-ul">〜</ul>~ のなかの =<li>〜</li>= になる + =1.=, =1)= は区別なく ~<ol class="org-ol">〜</ol>~ のなかの =<li>〜</li>= になる 順序リストは: 1. [X] 順序つきリストもチェックボックスになれる(混ぜ書き可能) 2. 範囲内のリストは自動的にナンバリングされて出力される\\ ここでいう範囲とは、 1) 同じ序列(等インデント)をもつリスト群 2) 行間が0行または1行空けた[fn:1]リスト群 のことで、このリスト群に入った混ぜ書きができない要素は _その内の先頭の要素に強制的に変形される[[list-type-comfliction][(例)]]。_ \\ このリスト群に入った混ぜ書きができる要素は先頭の要素の影響を受けない。\\ なので、異なるリストのタイプを _続けて_ 使うときは 2 行以上空ける必要がある。\\ ただしリストと等インデント、または親インデントをもつ別要素[fn:2]が挟まれたら改行の必要はなくなる。 10000. [@10000] こうすると順序を強制できる(=[@10000]= の挿入) 10001. 更にそのまま続く[fn:3] 42. [@42]減らすこともできる(=[@42]= の挿入) 説明つきリストは: - 難しい用語 :: 用語の説明 \\ 改行(文末の\\が =<br>= になる)でインデントして継続できる(どのリストでも出来る) =html= では ~<dt>用語</dt><dd>説明</dd>~ と出力される - [ ] チェックリスト :: やはり混ぜ書き出来る - 子要素 ---------- <<list-type-comfliction>> - 説明つきリストと普通のリストの争い(先に来る要素が強い) - 内部では見えている筈の :: タイトルつきリストが export 時に見えなくなってしまう -- /(上下の 2 項目は順序のみが逆)/ -- - 内部では見えている筈の :: タイトルつきリストが export 時に見えなくなってしまう - 説明つきリストと普通のリストの争い(先に来る要素が強い)[fn:4] ---------- [fn:1] なぜ1行空けても同じ群と見做されるのか、というのは哲学的な問題だ。\\ おそらく =org-mode= で用いるときの外観が整う(0空行だとぎっちり詰まって見えてしまう)からだろう。 [fn:2] 等インデントであればリスト以外の要素(パラグラフ: 普通の地の文など)である必要がある。\\ 親インデントならばリストでも良い。 [fn:3] 順序の強制変更 http://pragmaticemacs.com/emacs/org-mode-start-a-numbered-list-from-any-number/ [fn:4] 用語部分がない説明つきリストに強制的に変更されているのが分かると思う。
更なる深みへ
.
このページではリストの出力について書いたが、単に org-mode のリストについての資料をまとめておく。
- https://orgmode.org/manual/Plain-lists.html
org-modeのリストについての公式資料。
マニュアルひとつで標準的な紹介からマニアックな変数までかなり分かるが、どこになにが書いてあったかよく忘れる。- https://code.orgmode.org/bzg/org-mode/src/master/lisp/org-list.el
org-modeのソースコード。
コードのコメントがとても叮嚀。 stackexchange を調べるよりも早く目的のものに辿りつけることもある。これを直接弄るのではなく、せいぜい(defvar xxx option1)のような部分を自らの設定ファイルで(setq xxx option2)などと書き換えるときの参考に使うのがいいだろう。