reST To Reveal.js

Reveal.jsスライドをreStructuredTextから作る。

Noboru Yamamoto

$Date: 2019/10/14 04:36:55 $

概要

文書変換ツールpandocを用いて、 textベースでプレゼンテーションを作成し、webベースで表示する方法を説明します。

Java script ライブラリreveal.jsを使用するので、動的な表現も可能になっています。

目的

様々な発表において、Power Pointなどのプレゼンテーションツールを使うことが一般的です。しかし、特定のツールに依存することよる問題が生じることがあります。
HTMLベースのプレゼンテーションツールを使うことで、利用環境への依存性を最小にできます。また、ネットワーク上での公開も簡単になります。¹
入力ファイルテキストファイルなので、 GIT, mercurialなどのバージョン管理システムで管理が簡単にできます。

Reveal.js

Reveal.jsはHTML5とjavascriptを組み合わせて、web browserによるプレゼンテーションを表示するツールです。
slidesという会社がReveal.jsによるプレゼンテーションを作成するためのweb上のサービスを提供しています(有料）。
プレゼンテーションを一つのHTMLファイルに納めるので、配布や公開などが簡単。

Reveal.jsプレゼンテーションの作成法

reveal.js の機能を使ってHTML文書を直接書く。(一部はmarkdownを使えるが、さすがに面倒）
reveal.jsのMarkdownサポートを使って、Markdownで書く。(Web　server が必要)
slides.comにお金を払って、Online Editorを使う。(Power point並の使い心地？）
sphinxのreveal.jsサポートを使う。(ちょっと安定性に欠ける。)
pandocをつかってreveal.js対応のHTMLに変換する。これでいきましょう

Pandoc

pandocはフリーウェアとして公開されている高機能な文書変換プログラム
- 入力形式: markdown, reStructuredText, HTML, LaTeX, MediaWiki, DocBookなど
- 出力形式: markdown, reStructuredText, HTML 5, LaTeX(beamerを含む), OpenDocument, Word, EPUB, HTMLスライドショー(Slidy, Slideous, DZSlides, reveal.js, S5)など
- 詳しくはpandoc --list-input-formatsやpandoc --list-input-formatsでチェック.

reStructuredText

Pythonのドキュメントを制作するために開発／使用されているSphinxプログラムの入力形式。
SphinxはreStructuredTextの入力から、HTML, LaTex, epub, pdf などの出力を生成できる。
reStructuredText自体はSphinxとは独立にも、pythonプログラム中のdocument記述に使われている。
Markdownと同様に、textベースで作成できる。LaTexに比べて、読み易く、書き易い。
Sphinxは出版レベルの出力が可能なほど、表現力が高い。

reST + pandoc = reveal.js

ここでは、reStructuredTextからHTML スライドショウに変換するのに必要なツールのインストールや実際の操作の流れを説明します。

必要なツール

pandocとreStructuredTextでreveal.jsのスライドを作成するには、最低、次のツールが必要です。

テキストエディタ：テキストファイルの作成／編集が行えるエディタであれば、なんでもOK.
pandoc: pandoc web siteからダウンロード。プラットフォーム毎のバイナリ²,³ も用意されている。
reveal.js: githubからダウンロード, 適当な場所⁴で展開しておく。
HTMLブラウザ(javascript+HTML4/5をサポートしていることが必要)

入力の作成

スライドの作成には、

reStructuredTextによる入力ファイルをテキストエディタで作成。
pandocにより入力ファイルをhtmlファイルに変換。
htmlファイルをブラウザで表示。

の手順が必要です。

まずは、テキストエディタで次の内容を含むファイルを作成します。名前をhabits.rstとします。

入力例

===============
ReSt to html
===============
:Author: 著者 (複数の場合はセミコロンで区切る)
:date: 2019.9.28

今日の予定
=============

朝にやること
-------------

起きる
++++++++
-  アラームを止める
-  ベッドから出る


朝ご飯
++++++++++++
-  卵を食べる
-  コーヒーを飲む

昼にやること
-------------

昼ご飯
+++++++++++++
- 昼ごはんを食べる
- 昼寝をする
- おやつを食べる

夜にやること
-------------
夜ご飯
+++++++++++

-  スパゲッティを食べる
-  ワインを飲む

htmlへの変換

次のコマンドを使ってhabbits.rstをhabbit.htmlへ変換します。指定したオプションについては、別途説明(pandocopts)します。

/usr/local/bin/pandoc -f rst -t revealjs  --standalone \
 --self-contained \
 -V revealjs-url=file:<where/you/installed/reveal.js-master \
 -V theme=sky \
 -o habits.html habits.rst

スライドショーを開く

作成されたhabits.htmlをwebブラウザで開く。

スライドの操作

webブラウザ上のスライドショーで可能な操作。

カーソルキー	上げ左右でスライド移動
スペースキー	次のスライドへ
ESCキー	スライド一覧
S	発表者用ノートの表示
B	一時的に画面を暗転／復帰
'Alt'+click	画面のズーム／復帰

スライドの一覧

'ESC'キーを押すと、次のようなスライドの一覧が表示されます。

Zoom

'Alt'＋マウスクリックでクリックした場所を中心にスライドを拡大して表示します。

発表者ノート

’s’キーを押すと、発表者用の画面が表示されます。ブラウザのセキュリティ設定によっては、別ウィンドウを開く為の許可を求められます。このあと、発表者画面が正常に表示されない場合には、発表者画面を一度閉じて、 ’s’キーをもう一度押してみてください。

スライドの印刷

webブラウザでHTMLファイルを開く際に、ファイル名に続けて"?print-pdf#" を入れておくと、印刷向けのCSSを使った画面が表示されます。
これをブラウザの印刷機能を使って、印刷あるいはPDFに変換することができます。

この方法で作成したPDFファイルの例:

reStructuredTextの要素

ここでは、reStructured Textの文書を作成するために必要となる要素の記述法を説明します⁵。

セクションタイトル

reStructuredTextではセクションタイトルは、記号(=,-,+,^,_,等)を使った下線で示されます。
- 下線はタイトルのテキストより長いことが必要です。
セクションのレベルは、異なるタイプの下線がテキスト中の現れる順番によって、動的に割当られます。
トップレベルのタイトルは文書のタイトルとして使われます。
トップレベルのタイトルでは著者、作成日などをフィールドリストの形式で挿入できます。(optional)

セクションタイトルの一例

========================================
reST To Reveal.js
========================================
:subtitle: reStructuredTextをpandocでReveal.jsスライドに
:Author: Noboru Yamamoto
:Date: 2019.10.03

レベル1のタイトル
=================

レベル2のタイトル
------------------

番号付きリスト

item 1
item 2

#. item 1
#. item 2

リストの逐次表示

reveal.jsのフラグメント機能を使うことで、リストを一行ずつ表示します。リストの行頭をインデントして始めることで、リストが逐次表示されます。

item 1
item 2

#. item 1
#. item 2

定義リスト

項目1 :: 定義1
項目2 :: 定義2

定義リスト入力

項目1 :
  定義1

項目2 :
  定義2

フィールドリスト

field name: field body
second field name: second field body

インラインマークアップ

`斜体`	斜体
`太字`	太字
``コードサンプル``	`コードサンプル`

表(シンプルテーブル）

reStructuredTextでは、テーブルを作成する複数の方法(シンプル、CSV、リスト、グリッド)があります。

シンプルテーブル
A	B	A and B
False	False	False
True	False	False
False	True	False
True	True	True

シンプルテーブルの入力例

=====  =====  ========
A      B      A and B
=====  =====  ========
False  False  False
True   False  False
False  True   False
True   True   True
=====  =====  ========

表(CSV　テーブル）

CSV　テーブル
A	B	A and B
False	False	False
True	False	False
False	True	False
True	True	True

CSV テーブルの入力例

.. csv-table:: CSV　テーブル
   :widths: "auto", "auto", "auto"
   :header:  A,      B,      "A and B"

   False,  False,  False
   True,   False , False
   False,  True,   False
   True,   True,   True

表(リスト　テーブル）

リスト　テーブル
A	B	A and B
False	False	False
True	False	False
False	True	False
True	True	True

リストテーブルの入力例

.. list-table:: リスト　テーブル
   :widths: "auto", "auto", "auto"
   :header-rows: 1

   * - A
 - B
 - A and B
   * - False
 - False
 - False
   * - True
 - False
 - False
   * - False
 - True
 - False
   * - True
 - True
 - True

表(グリッド　テーブル）

A	B	A and B
False	False	False
True	False	False
False	True	False
True	True	True

グリッドテーブル入力例

+-------+-------+-------------------+
|A      |B      |A and B            |
+=======+=======+===================+
|False  |False  |False              |
+-------+-------+-------------------+
|True   |False  |False              |
+-------+-------+-------------------+
|False  |True   |False              |
+-------+-------+-------------------+
|True   |True   |True               |
+-------+-------+-------------------+

画像

画像を挿入するのにも二つの方法があります。

まずは基本的な .. image:: ディレクティブを使った方法。

画像の入力例

.. image:: habits-title.png
   :width: 400px

オプションとして、widthの他にも, height, scale, alt, align, targeteと言ったオプションが使えます。

画像(キャプション付き)

figureディレクティブも使えます。

figureのレジェンド

画像の入力例

.. figure:: habits-title.png
   :width: 400px

   Figureのキャプション

   figureのレジェンド

figureのオプションには、imageのオプションに加えて figwidth, figclassが使えます。

コードサンプル

言語を指定する事で、コードの色付けが自動で行われます。

def hello():
   print("Hello World!")

.. code:: python

   def hello():
   print("Hello World!")

発表者用ノート

Viewerスクリーンに現れる発表者用ノートを作ります。

ブラウザで'S' キーを押して見て下さい。

.. note::
   :class: notes

   発表者用ノートをここに   

   - リストなどの
   - ReST要素をいれることも可能
   - キーsを押すと発表者用ノートが別ウィンドウで表示されます。
   - \ `:class: notes`\　をお忘れなく。

数式

数式はインラインモード　 $E=m c^2$ でも、
ディスプレイモードでも可能(↓)

$\mathcal{S} = \int_{-\infty}^{\infty} d t m_0 \sqrt{1- \frac{\dot{x}^2}{c^2}}$

数式（インライン）の入力例：

数式はインライン\ :math:`E=m c^2`\ でも

数式(ディスプレイモード)の入力例：

.. math::

   \mathcal{S} = \int_{-\infty}^{\infty} d t  m_0 \sqrt{1- \frac{\dot{x}^2}{c^2}}

Pandocのオプション

htmlスライドを作成するのに必要となるpandocのオプションについて説明します。

pandoc 一般オプション

pandoc 一般オプション
-f, --from	入力ファイルのフォーマット、reSTは `rst`で指定する。
-t, --to	出力ファイルのフォーマット、reveal.jsは `revealjs`で指定する。
-o, --output	出力先ファイルの指定。省略時は標準出力に出力。

Pandocのオプション(続き)

pandoc 一般オプション（続き）
-s, --standalone	完結し、独立な出力ファイルを作成。
--self-contained	外部依存を持たない、standaloneな出力ファイルを作成する。
--mathml	数式をmathmlを使って出力する。(--mathjaxオプションもある。)

Pandocのオプション(HTML スライドショー)

HTMLスライドショー向けオプションの幾つか

HTMLスライドショーオプション
--V <name>=<value>	メタバリアブルズ <name>の値を <value> に設定する。
--base-header-level	最上位のセクションのレベルを設定する。
--slide-level	スライドが始まるセクションレベルを指定。

Pandoc 変数(HTML スライドショー)

HTMLスライドショーに使われる変数の幾つか (-V <var>=<value>の形式で指定する)。

HTMLスライドショーバリアブル
revealjs-url	reveal.jsのjava scriptライブラリのある場所を指定する。
s5-usr, slidy-url, slideous-url	revealjs-urlのs5,slidy,slideous版

その他のPandoc スライド

pandocはslide向けの出力形式として、reveal.js の他に、s5などのhtml スライドショーまた、latex/beamerによるpdf出力をサポートしています。

html スライドショー: slideous, slidy, dzslides, s5
latex/beamer slide: beamer

同じreStructured Textによるスライド原稿から、適切なpandocのオプションを指定する事で、これらのスライドショーに変換することもできます。

Beamer スライドでの注意点

日本語を含んだslides も beamerを使って、PDFファイルに変換できます。
- この時、デフォルトのpdflatexではなくて、lualatexを使うのが便利。
- 但しこの時も、日本語処理のための指定を標準のテンプレートに追加してやる必要があります。

Note

'pandoc -D beamer'で出力されるテンプレートに次の行を加えたテンプレート(default.beamer) を作成する。この新しく作成したテンプレートをpandoc実行時に"--template"オプションで指定する。

\usepackage{luatexja} 
\usepackage[utf8]{inputenc}

をtemplateに追加します。元になるtemplateはpandoc -D beamerで出力されます。

参考

参考資料へのリンクなどを挙げておきます。

webリンク

reStructuredText　入門: https://www.sphinx-doc.org/ja/master/usage/restructuredtext/basics.html
pandoc ドキュメント: Pandoc ユーザーズガイド日本語版 http://sky-y.github.io/site-pandoc-jp/users-guide/

ソースコード

このスライドのソースコードは、 ./reST2RevealjsSlides.rstからご覧いただけます。
また、ここで使われたpandocのオプションは ./Makefileをご参照下さい。

test

container ディレクティブによるfragment

item1
item2
item3

compound ディレクティブによるfragment

item1
item2
item3

topic

Topic Title

Subsequent indented lines comprise the body of the topic, and are interpreted as body elements.

option list

-o option

-a another option

Definition list

Word1 :: a first definition
word2 :: second definition

Interpreted Text Role Quick Reference

See <http://docutils.sf.net/docs/ref/rst/roles.html> for full info.

roles

Role Name	Description
emphasis	Equivalent to emphasis
literal	Equivalent to `literal` but processes backslash escapes
math	Mathematical notation (input in LaTeX format)
PEP	Reference to a numbered Python Enhancement Proposal
RFC	Reference to a numbered Internet Request For Comments

roles(cont'd)

Role Name	Description
raw	For non-reST data; cannot be used directly (see docs) [0.3.6]
strong	Equivalent to strong
sub	Subscript
sup	Superscript
title	Title reference (book, etc.); standard default role

Directive Quick Reference

See <http://docutils.sf.net/docs/ref/rst/directives.html> for full info.

Directives

Directive Name	Description (Docutils version added to, in [brackets])
attention	Specific admonition; also "caution", "danger", "error", "hint", "important", "note", "tip", "warning"
admonition	Generic titled admonition: `.. admonition:: By The Way`
rubric	`.. rubric:: Informal Heading`

Directives(cont'd)

Directive Name	Description (Docutils version added to, in [brackets])
image	`.. image:: picture.png`; many options possible
figure	Like "image", but with optional caption and legend
sidebar	`.. sidebar:: Title`; like a mini parallel document

Directives(cont'd)

Directive Name	Description (Docutils version added to, in [brackets])
parsed-literal	A literal block with parsed inline markup
topic	`.. topic:: Title`; like a mini section
epigraph	Block quote with class="epigraph"
highlights	Block quote with class="highlights"

Directives(cont'd)

Directive Name	Description (Docutils version added to, in [brackets])
pull-quote	Block quote with class="pull-quote"
compound	Compound paragraphs [0.3.6]
container	Generic block-level container element [0.3.10]

Directives(cont'd)

Directive Name	Description (Docutils version added to, in [brackets])
table	Create a titled table [0.3.1]
list-table	Create a table from a uniform two-level bullet list [0.3.8]
csv-table	Create a table from CSV data [0.3.4]

Directives(cont'd)

Directive Name	Description (Docutils version added to, in [brackets])
contents	Generate a table of contents
sectnum	Automatically number sections, subsections, etc.
header, footer	Create document decorations [0.3.8]

Directives(cont'd)

Directive Name	Description (Docutils version added to, in [brackets])
target-notes	Create an explicit footnote for each external target
math	Mathematical notation (input in LaTeX format)
meta	HTML-specific metadata

Directives(cont'd)

Directive Name	Description (Docutils version added to, in [brackets])
include	Read an external reST file as if it were inline
raw	Non-reST data passed untouched to the Writer
replace	Replacement text for substitution definitions
class	Set a "class" attribute on the next element

Directives(cont'd)

data-backgroud: black

Directive Name	Description (Docutils version added to, in [brackets])
role	Create a custom interpreted text role [0.3.2]
default-role	Set the default interpreted text role [0.3.10]
title	Set the metadata document title [0.3.10]

themeを変えて、beamer経由でpdfにすることも原理的には可能。↩︎
Windows, Macでは、バイナリパッケージをダウンロードして、インストーラーを起動す。↩︎
Linuxでは、apt,yumなどのツールでインストールすれば良いでしょう。 source codeからのインストールには、Haskellのコンパイラが必要です。↩︎
pandocで処理する際に, --revealjs-urlオプションで指定する。↩︎
pandocのmarkdownでは、セクションタイトルに対応するHTMLタグにアトリビュートを設定する方法が、用意されています。しかし、pandocの受け付けるreStructuredTextにもこの機能はありません。これがあればdata-background-imageなどの設定が可能となるのですが。↩︎

reST To Reveal.js

概要

目的

Reveal.js

Reveal.jsプレゼンテーションの作成法

Pandoc

reStructuredText

reST + pandoc = reveal.js

必要なツール

入力の作成

入力例

htmlへの変換

スライドショーを開く

スライドの操作

スライドの一覧

Zoom

発表者ノート

スライドの印刷

reStructuredTextの要素

セクションタイトル

セクションタイトルの一例

リスト

番号付きリスト

リストの逐次表示

定義リスト

定義リスト入力

フィールドリスト

インラインマークアップ

表(シンプル テーブル）

シンプル テーブルの入力例

表(CSV テーブル）

CSV テーブルの入力例

表(リスト テーブル）

リスト テーブルの入力例

表(グリッド テーブル）

グリッド テーブル入力例

画像

画像の入力例

画像(キャプション付き)

画像の入力例

コードサンプル

発表者用ノート

数式

Pandocのオプション

pandoc 一般オプション

Pandocのオプション(続き)

Pandocのオプション(HTML スライドショー)

Pandoc 変数(HTML スライドショー)

その他のPandoc スライド

Beamer スライドでの注意点

参考

webリンク

ソースコード

test

topic

option list

Definition list

Interpreted Text Role Quick Reference

roles

roles(cont'd)

Directive Quick Reference

Directives

Directives(cont'd)

Directives(cont'd)

Directives(cont'd)

Directives(cont'd)

Directives(cont'd)

Directives(cont'd)

Directives(cont'd)

Directives(cont'd)

contents

sidebar directive

表(シンプルテーブル）

シンプルテーブルの入力例

表(CSV　テーブル）

表(リスト　テーブル）

リストテーブルの入力例

表(グリッド　テーブル）

グリッドテーブル入力例