##############################################################
基本 (4) - コードリスティング - 
##############################################################

=========================================================
リテラルブロックとコードブロック
=========================================================

* コードの主要な表示方法として、以下の３つを挙げる．

  + ReSTソースファイル（.rst）に、直接コードを書く．
    
    1. **リテラルブロック**  （"::" ）
    2. **コードブロック**  ( "code-block" )

       
  + 外部ファイルを読み込む．
    
    3. **リテラルインクルード** （"literalinclude"）


| 

=========================================================
リテラルブロックによる表示
=========================================================

* 意味的には、リテラル（文章）を記載するためのブロック．
* 前の文書の末尾に ダブルコロン **"::"** を付記する．改行後空白行を挟み、インデントをつけて、コードを記載する． 例としては、 ::

     - SphinxのReST文書は、次のコマンドによりコンパイルできる． ::

         $ make html
     
  +  ダブルコロン（"::"）の前には空白区切りを入れ、その後には何も書かない． 


* （表示例） ::

    #include <cstdio>
   
    int main(void)
    {
      printf( "Hello World!!\n" )
    }

    
| 
     
=========================================================
code-block ディレクティヴによる表示
=========================================================

* 意味的には、コードを記載するためのブロック．
* code-blockディレクティヴでは、キャプションや行の強調などの設定を付与して、コードを表示することができる． ::

    .. code-block:: 言語の種類、ファイル拡張子 ( f90, cpp, python, bash など )
                    :caption: （キャプション）
                    :emphasize-lines: （強調したい行） etc.

                    （コードを記載）


* （表示例）
  
  .. code-block:: cpp
     :emphasize-lines: 3
     :caption: Example of "Hello World" code in c++.

     #include <cstdio>
   
     int main(void)
     {
        printf( "Hello World!!\n" )
     }


  + ３行目を強調し、キャプションを付けている．また、シンタックスハイライトも "cpp" に沿ってなされている（自動、外観変更はおそらく難しいが）．


| 

=========================================================
literalinclude ディレクティヴによる表示
=========================================================

* リテラルを外部から読み込みする．
* literalinclude ディレクティヴでは、外部ファイルに記載されているコードを読み込んで表示することができる．また、各種表示設定も適用可能である． ::
       
    .. literalinclude:: （ファイル名）
                        :caption: （キャプション）
                        :language: （言語の種類、拡張子）


* （表示例）

  .. literalinclude:: codes/hello.cpp
                      :caption: hello.cpp
                      :language: cpp