======================================== reST To Reveal.js ======================================== :subtitle: Reveal.jsスライドをreStructuredTextから作る。 :Author: Noboru Yamamoto :Date: |HGdate| :transition: slide :theme: white :transitionSpeed: fast :revealjs-url: file:/Users/noboru/Sites/jslib/reveal.js-master :lang: ja_JP-UTF8 .. |date| replace:: $HGdate: Mon, 14 Oct 2019 13:36:55 +0900 $ .. |HGdate| replace:: $Date: 2019/10/14 04:36:55 $ 概要 ==================== 文書変換ツール\ **pandoc**\ を用いて、 textベースでプレゼンテーションを 作成し、webベースで表示する方法を説明する。 Java script ライブラリreveal.jsを使用するので、 動的な表現も可能になっている。 .. note:: :class: notes 動的な表現とは、リストの項目を順次表示あるいは消去していく事を指しているつもり。 発表者用ノートもサポートしている。 reStructuredTextとPandocの組み合わせでは、reveal.jsの持つ機能を全て使いこなすことはできない、残念ながら。 しかし、スライドの執筆の簡便さを優先させた結果こうなった。出来上がったhtmlにreveal.jsの機能を追加していくことも不可能ではないが、 rstを変更するたびに同じ事を繰り返すことは難しい。 目的 ------------- * 様々な発表において、Power Pointなどの プレゼンテーションツールを使うことが一般的です。 しかし、特定のツールに依存することよる問題が生じることがあります。 * HTMLベースのプレゼンテーションツールを使うことで、 利用環境への依存性を最小にできます。また、ネットワーク上での公開も 簡単になります。\ [#]_\ * 入力ファイルテキストファイルなので、 GIT, mercurialなどのバージョン管理システム で管理が簡単にできます。 .. [#] themeを変えて、beamer経由でpdfにすることも原理的には可能。 .. note:: :class: notes 発表者用ノート 研究者として、論文執筆と研究発表は欠かせない。reStructuredTextを論文執筆(with Sphinx)と発表資料(with Pandoc)の 双方に使うことができれば、省力化に繋がると期待できる。 Reveal.js -------------------------- .. _Reveal.js: https://revealjs.com/#/ .. _slides: https://slides.com/ - \ Reveal.js_\ はHTML5とjavascriptを組み合わせて、web browserによるプレゼンテーションを表示するツールです。 - \ slides_\ という会社がReveal.jsによるプレゼンテーションを作成するためのweb上のサービスを提供しています(有料）。 - プレゼンテーションを一つのHTMLファイルに納めるので、配布や公開などが簡単。 .. note:: :class: notes backにbusinessを行っている会社があるということは、それなりに安定した基盤があると考えて良い。 したがって、Reveal.jsはその他のHTML slide　showに比べて、寿命があるだろう。(最も現状で問題なく、javascriptのソースコード も公開されている）ということで、これから長期に渡って使い続けることができるだろう。 ------------- 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に変換する。\ **これでいきましょう**\ .. note:: :class: notes Sphinxのreveal.jsサポートには、contribjp-revealjsやrevealjsがあるが、更新されていないとか、出たばかりでちょっと安定性(or 信頼性）に欠ける。それぞれで書き方が異なるのも問題。 できることならreStructuredText + Sphinxで閉じてしまいたいが、現状ちょっと難しい。 Pandocの拡張markdownでも良い事になるが、プレゼンテーション以外の媒体としてはsphinx/reStructuredTextを使いたい。 Pandoc -------- * pandocはフリーウェアとして公開されている高機能な文書変換プログラム .. class:: fragment - 入力形式: markdown, reStructuredText, HTML, LaTeX, MediaWiki, DocBookなど .. class:: fragment - 出力形式: markdown, reStructuredText, HTML 5, LaTeX(beamerを含む), OpenDocument, Word, EPUB, HTMLスライドショー(Slidy, Slideous, DZSlides, \ **reveal.js**\ , S5)など .. class:: fragment - 詳しくは\ ``pandoc --list-input-formats``\ や\ ``pandoc --list-input-formats``\ でチェック. .. note:: :class: notes #) markdownは複数の方言をサポートしている。主にはPandoc独自拡張を含むmarkdown #) PDF出力はLaTeX経由 #) PandocはHaskellで書かれている。 reStructuredText ----------------------- #. Pythonのドキュメントを制作するために開発／使用されているSphinxプログラムの入力形式。 #. SphinxはreStructuredTextの入力から、HTML, LaTex, epub, pdf などの出力を生成できる。 #. reStructuredText自体はSphinxとは独立にも、pythonプログラム中のdocument記述に使われている。 #. Markdownと同様に、textベースで作成できる。LaTexに比べて、読み易く、書き易い。 #. Sphinxは出版レベルの出力が可能なほど、表現力が高い。 .. note:: :class: notes pandocを使うのだから、「markdownを使えば良いのでは」との声はとりあえず無視（？） pandocのMarkdownを使ってsphinxの文書を作成することも一部可能ではあるが、sphinxを使いこなすためには、 reStructuredTextの仕組み(ロール、ディレクティブ）を使わざるを得ない。 reST + pandoc = reveal.js =============================== .. class:: myclass attrbute=1 :name: myclass :attributes2: value2 ここでは、reStructuredTextからHTML スライドショウに変換するのに必要なツールの インストールや実際の操作の流れを説明します。 必要なツール -------------------------- .. _pandoc_web_site: http://pandoc.com pandocとreStructuredTextでreveal.jsのスライドを作成するには、最低、次のツールが必要です。 #. テキストエディタ：テキストファイルの作成／編集が行えるエディタであれば、なんでもOK. #. pandoc: \ `pandoc web site`_\ からダウンロード。プラットフォーム毎のバイナリ\ [#]_, [#]_ も用意されている。 #. reveal.js: githubからダウンロード, 適当な場所\ [#]_\ で展開しておく。 #. HTMLブラウザ(javascript+HTML4/5をサポートしていることが必要) .. [#] Windows, Macでは、バイナリパッケージをダウンロードして、インストーラーを起動す。 .. [#] Linuxでは、apt,yumなどのツールでインストールすれば良いでしょう。 source codeからのインストールには、Haskellのコンパイラが必要です。 .. [#] pandocで処理する際に, --revealjs-urlオプションで指定する。 入力の作成 ------------------------ スライドの作成には、 #. reStructuredTextによる入力ファイルをテキストエディタで作成。 #. pandocにより入力ファイルをhtmlファイルに変換。 #. htmlファイルをブラウザで表示。 の手順が必要です。 まずは、テキストエディタで次の内容を含むファイルを作成します。 名前を\ `habits.rst<./habits.rst>`_\ とします。 入力例 ------------------- .. code:: =============== ReSt to html =============== :Author: 著者 (複数の場合はセミコロンで区切る) :date: 2019.9.28 今日の予定 ============= 朝にやること ------------- 起きる ++++++++ - アラームを止める - ベッドから出る 朝ご飯 ++++++++++++ - 卵を食べる - コーヒーを飲む 昼にやること ------------- 昼ご飯 +++++++++++++ - 昼ごはんを食べる - 昼寝をする - おやつを食べる 夜にやること ------------- 夜ご飯 +++++++++++ - スパゲッティを食べる - ワインを飲む htmlへの変換 ------------------------ 次のコマンドを使ってhabbits.rstをhabbit.htmlへ変換します。 指定したオプションについては、別途説明(`pandocopts`_)します。 .. code:: /usr/local/bin/pandoc -f rst -t revealjs --standalone \ --self-contained \ -V revealjs-url=file: reStructuredTextの要素 =============================== ここでは、reStructured Textの文書を作成するために必要となる要素の記述法を 説明します\ [#]_\ 。 .. [#] pandocのmarkdownでは、セクションタイトルに対応するHTMLタグにアトリビュートを設定する方法が、 用意されています。しかし、pandocの受け付けるreStructuredTextにもこの機能はありません。 これがあればdata-background-imageなどの設定が可能となるのですが。 セクションタイトル ------------------------------------------------------------------ - reStructuredTextではセクションタイトルは、記号(=,-,+,^,_,等)を使った下線で示されます。 - 下線はタイトルのテキストより長いことが必要です。 - セクションのレベルは、異なるタイプの下線がテキスト中の現れる順番によって、動的に割当られます。 - トップレベルのタイトルは文書のタイトルとして使われます。 - トップレベルのタイトルでは著者、作成日などをフィールドリストの形式で挿入できます。(optional) セクションタイトルの一例 ------------------------------------------------------------------ .. code:: ======================================== reST To Reveal.js ======================================== :subtitle: reStructuredTextをpandocでReveal.jsスライドに :Author: Noboru Yamamoto :Date: 2019.10.03 レベル1のタイトル ================= レベル2のタイトル ------------------ リスト ---------- * item 1 * item 2 .. class:: fragment .. code:: * item 1 * item 2 番号付きリスト -------------------- #. item 1 #. item 2 .. class:: fragment .. code:: #. item 1 #. item 2 リストの逐次表示 -------------------- reveal.jsのフラグメント機能を使うことで、リストを一行ずつ表示します。 リストの行頭をインデントして始めることで、リストが逐次表示されます。 #. item 1 #. item 2 .. class:: fragment .. code:: #. item 1 #. item 2 インラインマークアップ ---------------------- .. csv-table:: :widths: "auto", "auto" "``*斜体*``", "\ *斜体*\ " "``**太字**``", "\ **太字**\ " "\`\`コードサンプル\`\`", "\ ``コードサンプル``\ " 表(シンプル テーブル） ------------------------ reStructuredTextでは、テーブルを作成する複数の方法(シンプル、CSV、リスト、グリッド)があります。 .. table:: シンプル テーブル ===== ===== ======== A B A and B ===== ===== ======== False False False True False False False True False True True True ===== ===== ======== シンプル テーブルの入力例 ---------------------------- .. class:: fragment .. code:: ===== ===== ======== 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 CSV テーブルの入力例 ---------------------------- .. class:: fragment .. code:: 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 表(リスト　テーブル） ------------------------ .. 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 リスト テーブルの入力例 ---------------------------- .. class:: fragment .. code:: .. 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 | +-------+-------+-------------------+ グリッド テーブル入力例 ---------------------------- .. class:: fragment .. code:: グリッド テーブル :caption: グリッド テーブル　ソースコード +-------+-------+-------------------+ |A |B |A and B | +=======+=======+===================+ |False |False |False | +-------+-------+-------------------+ |True |False |False | +-------+-------+-------------------+ |False |True |False | +-------+-------+-------------------+ |True |True |True | +-------+-------+-------------------+ 画像 -------- 画像を挿入するのにも二つの方法があります。 まずは基本的な `.. image::` ディレクティブを使った方法。 .. image:: habits-title.png :width: 400px :caption: テーブルキャプション 画像の入力例 --------------- .. code-block:: rst .. image:: habits-title.png :width: 400px オプションとして、widthの他にも, height, scale, alt, align, targeteと言ったオプションが使えます。 画像(キャプション付き) ----------------------- figureディレクティブも使えます。 .. figure:: habits-title.png :width: 400px Figureのキャプション figureのレジェンド 画像の入力例 ------------------- .. class:: fragment .. code-block:: rst .. figure:: habits-title.png :width: 400px Figureのキャプション figureのレジェンド .. class:: fragment figureのオプションには、imageのオプションに加えて figwidth, figclassが使えます。 コードサンプル ---------------- 言語を指定する事で、コードの色付けが自動で行われます。 .. code:: python def hello(): print("Hello World!") .. class:: fragment .. code:: .. code:: python def hello(): print("Hello World!") 発表者用ノート ------------------ Viewerスクリーンに現れる発表者用ノートを作ります。 ブラウザで'S' キーを押して見て下さい。 .. note:: :class: notes 発表者用ノートをここに - リストなどの - ReST要素をいれることも可能 - キーsを押すと発表者用ノートが別ウィンドウで表示されます。 - \ `:class: notes`\ 　をお忘れなく。 .. code:: .. note:: :class: notes 発表者用ノートをここに - リストなどの - ReST要素をいれることも可能 - キーsを押すと発表者用ノートが別ウィンドウで表示されます。 - \ `:class: notes`\　をお忘れなく。 数式 ==================== * 数式はインラインモード　\ :math:`E=m c^2`\ でも、 * ディスプレイモードでも可能(↓) .. math:: \mathcal{S} = \int_{-\infty}^{\infty} d t m_0 \sqrt{1- \frac{\dot{x}^2}{c^2}} -------------- 数式（インライン）の入力例： .. code:: 数式はインライン\ :math:`E=m c^2`\ でも 数式(ディスプレイモード)の入力例： .. code:: .. math:: \mathcal{S} = \int_{-\infty}^{\infty} d t m_0 \sqrt{1- \frac{\dot{x}^2}{c^2}} Pandocのオプション ==================== htmlスライドを作成するのに必要となるpandocのオプションについて説明します。 .. note:: :class: notes pandocのオプションは幾つかのカテゴリーに分けることができます。 * 入力や出力形式によらない一般的なオプション * 出力形式固有のオプション * 出力プログラムに渡す変数の指定("-V") pandoc 一般オプション ----------------------------- .. list-table:: pandoc 一般オプション :widths: "auto", "auto" * - -f, --from - 入力ファイルのフォーマット、reSTは \ :command:`rst`\ で指定する。 * - -t, --to - 出力ファイルのフォーマット、reveal.jsは \ :command:`revealjs`\ で指定する。 * - -o, --output - 出力先ファイルの指定。省略時は標準出力に出力。 .. _pandocopts: Pandocのオプション(続き) -------------------------------- .. list-table:: pandoc 一般オプション（続き） :name: pandocopts :class: fragment :widths: "auto", "auto" * - -s, --standalone - 完結し、独立な出力ファイルを作成。 * - --self-contained - 外部依存を持たない、standaloneな出力ファイルを作成する。 * - --mathml - 数式をmathmlを使って出力する。(--mathjaxオプションもある。) Pandocのオプション(HTML スライドショー) ------------------------------------------------------------------------ HTMLスライドショー向けオプションの幾つか .. list-table:: HTMLスライドショーオプション :name: pandocoptshtml :class: fragment :widths: "auto", "auto" * - --V = - メタ バリアブルズ の値を に設定する。 * - --base-header-level - 最上位のセクションのレベルを設定する。 * - --slide-level - スライドが始まるセクションレベルを指定。 Pandoc 変数(HTML スライドショー) ---------------------------------------------- HTMLスライドショーに使われる変数の幾つか (\ `-V =`\ の形式で指定する)。 .. list-table:: HTMLスライドショーバリアブル :name: pandocvars :class: fragment :widths: "auto", "auto" * - 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:: :class: notes 'pandoc -D beamer'で出力されるテンプレートに次の行を加えたテンプレート(default.beamer) を作成する。この新しく作成したテンプレートをpandoc実行時に"--template"オプションで指定する。 .. code-block:: latex \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<./reST2RevealjsSlides.rst>`_\ からご覧いただけます。 - また、ここで使われたpandocのオプションは \ `./Makefile<./Makefile>`_\ をご参照下さい。 test =========== container ディレクティブによるfragment .. container:: fragment * item1 * item2 * item3 ---------- compound ディレクティブによるfragment .. compound:: :class: fragment * item1 * item2 * item3 topic --------- .. topic:: Topic Title Subsequent indented lines comprise the body of the topic, and are interpreted as body elements.