update README/docs

ickc · Nov 30, 2016 · 72c9d5f · 72c9d5f
1 parent 9d4cd7d
commit 72c9d5f
Show file tree

Hide file tree

Showing 7 changed files with 306 additions and 38 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,8 +1,8 @@
 # macOS files
 .DS_Store
 
-tests/test_*.native
-tests/test_*.pdf
+tests/*.native
+tests/*.pdf
 
 # python auxiliary 
 __pycache__/

diff --git a/README.md b/README.md
@@ -1,20 +1,35 @@
 <!--This README is auto-generated from `docs/README.md`. Do not edit this file directly.-->
 
--   [CSV Tables in Markdown: Pandoc Filter for CSV Tables](#csv-tables-in-markdown-pandoc-filter-for-csv-tables)
--   [Example](#example)
--   [Install and Use](#install-and-use)
--   [Syntax](#syntax)
--   [Related Filters](#related-filters)
+-   [`pantable`](#pantable)
+    -   [Example](#example)
+    -   [Install and Use](#install-and-use)
+    -   [Syntax](#syntax)
+    -   [Related Filters](#related-filters)
+-   [`pantable2csv`](#pantable2csv)
 
 [![Build Status](https://travis-ci.org/ickc/pantable.svg?branch=master)](https://travis-ci.org/ickc/pantable) [![GitHub Releases](https://img.shields.io/github/tag/ickc/pantable.svg?label=github+release)](https://github.com/ickc/pantable/releases) [![PyPI version](https://img.shields.io/pypi/v/pantable.svg)](https://pypi.python.org/pypi/pantable/) [![Development Status](https://img.shields.io/pypi/status/pantable.svg)](https://pypi.python.org/pypi/pantable/) [![Python version](https://img.shields.io/pypi/pyversions/pantable.svg)](https://pypi.python.org/pypi/pantable/) <!-- [![Downloads](https://img.shields.io/pypi/dm/pantable.svg)](https://pypi.python.org/pypi/pantable/) --> ![License](https://img.shields.io/pypi/l/pantable.svg) [![Coveralls](https://img.shields.io/coveralls/ickc/pantable.svg)](https://coveralls.io/github/ickc/pantable) <!-- [![Scrutinizer](https://img.shields.io/scrutinizer/g/ickc/pantable.svg)](https://scrutinizer-ci.com/g/ickc/pantable/) -->
 
-CSV Tables in Markdown: Pandoc Filter for CSV Tables
-====================================================
+The pantable package comes with 2 pandoc filters, `pantable.py` and `pantable2csv.py`. `pantable` is the main filter, introducing a syntax to include CSV table in markdown source. `pantable2csv` complements `pantable`, is the inverse of `pantable`, which convert native pandoc tables into the CSV table format defined by `pantable`.
+
+Some example uses are:
+
+1.  You already have tables in CSV format.
+
+2.  You feel that directly editing markdown table is troublesome. You want a spreadsheet interface to edit, but want to convert it to native pandoc table for higher readability. And this process might go back and forth.
+
+3.  You want lower-level control on the table and column widths.
+
+4.  You want to use all table features supported by the pandoc’s internal AST table format, which is not possible in markdown for pandoc &lt;= 1.18.[1]
+
+[1] In pandoc 1.19, grid-tables is improved to support all features available to the AST too.
+
+`pantable`
+==========
 
 This allows CSV tables, optionally containing markdown syntax (disabled by default), to be put in markdown as a fenced code blocks.
 
 Example
-=======
+-------
 
 Also see the README in [GitHub Pages](https://ickc.github.io/pantable/). There’s a [LaTeX output](https://ickc.github.io/pantable/README.pdf) too.
 
@@ -70,7 +85,7 @@ becomes
 (The equation might not work if you view this on PyPI.)
 
 Install and Use
-===============
+---------------
 
 Install:
 
@@ -85,7 +100,7 @@ pandoc -F pantable -o README.html README.md
 ```
 
 Syntax
-======
+------
 
 Fenced code blocks is used, with a class `table`. See [Example](#example).
 
@@ -118,7 +133,7 @@ Optionally, YAML metadata block can be used within the fenced code block, follow
 When the metadata keys is invalid, the default will be used instead.
 
 Related Filters
-===============
+---------------
 
 The followings are pandoc filters written in Haskell that provide similar functionality. This filter is born after testing with theirs.
 
@@ -230,3 +245,53 @@ The followings are pandoc filters written in Haskell that provide similar functi
 </tr>
 </tbody>
 </table>
+
+`pantable2csv`
+==============
+
+This one is the inverse of `pantable`, a panflute filter to convert any native pandoc tables into the CSV table format used by pantable.
+
+Effectively, `pantable` forms a “CSV Reader”, and `pantable2csv` forms a “CSV Writer”. It allows you to convert back and forth between these 2 formats.
+
+For example, in the markdown source:
+
+``` markdown
++--------+---------------------+--------------------------+
+| First  | defaulted to be     | can be disabled          |
+| row    | header row          |                          |
++========+=====================+==========================+
+| 1      | cell can contain    | It can be aribrary block |
+|        | **markdown**        | element:                 |
+|        |                     |                          |
+|        |                     | -   following standard   |
+|        |                     |     markdown syntax      |
+|        |                     | -   like this            |
++--------+---------------------+--------------------------+
+| 2      | Any markdown        | $$E = mc^2$$             |
+|        | syntax, e.g.        |                          |
++--------+---------------------+--------------------------+
+
+: *Awesome* **Markdown** Table
+```
+
+running `pandoc -F pantable2csv -o output.md input.md`, it becomes
+
+```` markdown
+``` {.table}
+---
+alignment: DDD
+caption: '*Awesome* **Markdown** Table'
+header: true
+markdown: true
+table-width: 0.8055555555555556
+width: [0.125, 0.3055555555555556, 0.375]
+---
+First row,defaulted to be header row,can be disabled
+1,cell can contain **markdown**,"It can be aribrary block element:
+
+-   following standard markdown syntax
+-   like this
+"
+2,"Any markdown syntax, e.g.",$$E = mc^2$$
+```
+````
diff --git a/README.rst b/README.rst
@@ -1,6 +1,10 @@
 .. This README is auto-generated from `docs/README.md`. Do not edit this file directly.
 
-:Date:   November 22, 2016
+=====================================================
+CSV Tables in Markdown — Pandoc Filter for CSV Tables
+=====================================================
+
+:Date:   November 30, 2016
 
 .. role:: math(raw)
    :format: html latex
@@ -13,14 +17,35 @@
 |Build Status| |GitHub Releases| |PyPI version| |Development Status|
 |Python version| |License| |Coveralls|
 
-CSV Tables in Markdown: Pandoc Filter for CSV Tables
-====================================================
+The pantable package comes with 2 pandoc filters, ``pantable.py`` and
+``pantable2csv.py``. ``pantable`` is the main filter, introducing a
+syntax to include CSV table in markdown source. ``pantable2csv``
+complements ``pantable``, is the inverse of ``pantable``, which convert
+native pandoc tables into the CSV table format defined by ``pantable``.
+
+Some example uses are:
+
+#. You already have tables in CSV format.
+
+#. You feel that directly editing markdown table is troublesome. You
+   want a spreadsheet interface to edit, but want to convert it to
+   native pandoc table for higher readability. And this process might go
+   back and forth.
+
+#. You want lower-level control on the table and column widths.
+
+#. You want to use all table features supported by the pandoc’s internal
+   AST table format, which is not possible in markdown for pandoc <=
+   1.18. [1]_
+
+``pantable``
+============
 
 This allows CSV tables, optionally containing markdown syntax (disabled
 by default), to be put in markdown as a fenced code blocks.
 
 Example
-=======
+-------
 
 Also see the README in `GitHub
 Pages <https://ickc.github.io/pantable/>`__. There’s a `LaTeX
@@ -58,14 +83,15 @@ becomes
 +--------+---------------------+--------------------------+
 | 2      | Any markdown        | .. math:: E = mc^2       |
 |        | syntax, e.g.        |                          |
+
 +--------+---------------------+--------------------------+
 
 Table: *Awesome* **Markdown** Table
 
 (The equation might not work if you view this on PyPI.)
 
 Install and Use
-===============
+---------------
 
 Install:
 
@@ -80,7 +106,7 @@ Use:
     pandoc -F pantable -o README.html README.md
 
 Syntax
-======
+------
 
 Fenced code blocks is used, with a class ``table``. See
 `Example <#example>`__.
@@ -125,7 +151,7 @@ keys are recognized:
 When the metadata keys is invalid, the default will be used instead.
 
 Related Filters
-===============
+---------------
 
 The followings are pandoc filters written in Haskell that provide
 similar functionality. This filter is born after testing with theirs.
@@ -180,6 +206,63 @@ similar functionality. This filter is born after testing with theirs.
 |       |                     |            |           | d                          |
 +-------+---------------------+------------+-----------+----------------------------+
 
+``pantable2csv``
+================
+
+This one is the inverse of ``pantable``, a panflute filter to convert
+any native pandoc tables into the CSV table format used by pantable.
+
+Effectively, ``pantable`` forms a “CSV Reader”, and ``pantable2csv``
+forms a “CSV Writer”. It allows you to convert back and forth between
+these 2 formats.
+
+For example, in the markdown source:
+
+.. code:: markdown
+
+    +--------+---------------------+--------------------------+
+    | First  | defaulted to be     | can be disabled          |
+    | row    | header row          |                          |
+    +========+=====================+==========================+
+    | 1      | cell can contain    | It can be aribrary block |
+    |        | **markdown**        | element:                 |
+    |        |                     |                          |
+    |        |                     | -   following standard   |
+    |        |                     |     markdown syntax      |
+    |        |                     | -   like this            |
+    +--------+---------------------+--------------------------+
+    | 2      | Any markdown        | $$E = mc^2$$             |
+    |        | syntax, e.g.        |                          |
+    +--------+---------------------+--------------------------+
+
+    : *Awesome* **Markdown** Table
+
+running ``pandoc -F pantable2csv -o output.md input.md``, it becomes
+
+.. code:: markdown
+
+    ``` {.table}
+    ---
+    alignment: DDD
+    caption: '*Awesome* **Markdown** Table'
+    header: true
+    markdown: true
+    table-width: 0.8055555555555556
+    width: [0.125, 0.3055555555555556, 0.375]
+    ---
+    First row,defaulted to be header row,can be disabled
+    1,cell can contain **markdown**,"It can be aribrary block element:
+
+    -   following standard markdown syntax
+    -   like this
+    "
+    2,"Any markdown syntax, e.g.",$$E = mc^2$$
+    ```
+
+.. [1]
+   In pandoc 1.19, grid-tables is improved to support all features
+   available to the AST too.
+
 .. |Build Status| image:: https://travis-ci.org/ickc/pantable.svg?branch=master
    :target: https://travis-ci.org/ickc/pantable
 .. |GitHub Releases| image:: https://img.shields.io/github/tag/ickc/pantable.svg?label=github+release

diff --git a/docs/README.md b/docs/README.md
@@ -3,13 +3,26 @@ fontsize:	11pt
 documentclass:	memoir
 classoption: article
 geometry:	inner=1in, outer=1in, top=1in, bottom=1.25in
+title:	CSV Tables in Markdown --- Pandoc Filter for CSV Tables
 ...
 
-# CSV Tables in Markdown: Pandoc Filter for CSV Tables
+The pantable package comes with 2 pandoc filters, `pantable.py` and `pantable2csv.py`. `pantable` is the main filter, introducing a syntax to include CSV table in markdown source. `pantable2csv` complements `pantable`, is the inverse of `pantable`, which convert native pandoc tables into the CSV table format defined by `pantable`.
+
+Some example uses are:
+
+1. You already have tables in CSV format.
+
+2. You feel that directly editing markdown table is troublesome. You want a spreadsheet interface to edit, but want to convert it to native pandoc table for higher readability. And this process might go back and forth.
+
+3. You want lower-level control on the table and column widths.
+
+4. You want to use all table features supported by the pandoc's internal AST table format, which is not possible in markdown for pandoc \<= 1.18.^[In pandoc 1.19, grid-tables is improved to support all features available to the AST too.]
+
+# `pantable`
 
 This allows CSV tables, optionally containing markdown syntax (disabled by default), to be put in markdown as a fenced code blocks.
 
-# Example
+## Example
 
 Also see the README in [GitHub Pages](https://ickc.github.io/pantable/). There's a [LaTeX output](https://ickc.github.io/pantable/README.pdf) too.
 
@@ -49,7 +62,7 @@ First row,defaulted to be header row,can be disabled
 
 (The equation might not work if you view this on PyPI.)
 
-# Install and Use
+## Install and Use
 
 Install:
 
@@ -63,7 +76,7 @@ Use:
 pandoc -F pantable -o README.html README.md
 ```
 
-# Syntax
+## Syntax
 
 Fenced code blocks is used, with a class `table`. See [Example].
 
@@ -108,7 +121,7 @@ Optionally, YAML metadata block can be used within the fenced code block, follow
 
 When the metadata keys is invalid, the default will be used instead.
 
-# Related Filters
+## Related Filters
 
 The followings are pandoc filters written in Haskell that provide similar functionality. This filter is born after testing with theirs.
 
@@ -122,3 +135,52 @@ Caption: Comparison
 include: docs/comparison.csv
 ...
 ```
+
+# `pantable2csv`
+
+This one is the inverse of `pantable`, a panflute filter to convert any native pandoc tables into the CSV table format used by pantable.
+
+Effectively, `pantable` forms a "CSV Reader", and `pantable2csv` forms a "CSV Writer". It allows you to convert back and forth between these 2 formats.
+
+For example, in the markdown source:
+
+~~~markdown
++--------+---------------------+--------------------------+
+| First  | defaulted to be     | can be disabled          |
+| row    | header row          |                          |
++========+=====================+==========================+
+| 1      | cell can contain    | It can be aribrary block |
+|        | **markdown**        | element:                 |
+|        |                     |                          |
+|        |                     | -   following standard   |
+|        |                     |     markdown syntax      |
+|        |                     | -   like this            |
++--------+---------------------+--------------------------+
+| 2      | Any markdown        | $$E = mc^2$$             |
+|        | syntax, e.g.        |                          |
++--------+---------------------+--------------------------+
+
+: *Awesome* **Markdown** Table
+~~~
+
+running `pandoc -F pantable2csv -o output.md input.md`{.bash}, it becomes
+
+~~~markdown
+``` {.table}
+---
+alignment: DDD
+caption: '*Awesome* **Markdown** Table'
+header: true
+markdown: true
+table-width: 0.8055555555555556
+width: [0.125, 0.3055555555555556, 0.375]
+---
+First row,defaulted to be header row,can be disabled
+1,cell can contain **markdown**,"It can be aribrary block element:
+
+-   following standard markdown syntax
+-   like this
+"
+2,"Any markdown syntax, e.g.",$$E = mc^2$$
+```
+~~~
diff --git a/docs/README.pdf b/docs/README.pdf