This document uses the Sphinx implementation of reStructured Text (RST). RST is
a flexible markup language with lots of options for laying out text. To keep
thinks simple, this file describes the conventions used by this project. As
much as possible, use these methods for markup.

Tables
======
Use the simplified markup for tables as shown below. Use the tabularcolumns
directive for controlling how tables are layed out in pdf output. For
consistency, tables in this document shoud be specified without internal
vertical columns separators are preferred. (ie. Only use the | specifier on the
outsides of the table, such as with ``.. tabularcolumns:: | l l J|`` instead of
``.. tabularcolumns:: | l | l | J |``. Column specifiers will be one of the
following.

When possible, use only ``l,c,r,L,R,C,J`` specifiers and the renderer will
automatically figure out the columns widths. However, if a table is longer than
a page, or has complex content, then you must manually specify each column
width with the ``p{width}`` specifier. Long tables must also include the
``:class: longtable`` directive as shown below.

=========== ======================================
Specifier   Behaviour
=========== ======================================
l           minimum width left-justified column
c           minimum width centered column
r           minimum width right-justified column
p{'width'}  paragraph column with text vertically aligned at the top
L           flush left column with automatic width
R           flush right column with automatic width
C           centered column with automatic width
J           justified column with automatic width
\|          Vertical line
||          Double vertical  line
=========== ======================================

Use ``:numref:`` to reference a table from the document text. For example:
``:numref:`table_example_simple```

.. tabluarcolumns:: l l J
.. _table_example_simple:
.. table:: Example of simple table

   ========== =============== ==========
   Heading 1  Heading 2       Heading 3
   ========== =============== ==========
   row 1      two row         cell 3
              entry
   row 2      data            more
   ========== =============== ==========

.. tabluarcolumns:: | p{3cm} p{1cm} p{10cm} |
.. _table_example_columns:
.. table:: Example of table needing explicit formatting

   ========== =============== ==========
   Heading 1  Heading 2       Heading 3
   ========== =============== ==========
   row 1      two row         cell 3
              entry
   row 2      data            more

              ::              * embedded
                              * list
                 code         * of
                 block        * items
   ========== =============== ==========

.. tabluarcolumns:: | p{3cm} p{1cm} p{10cm} |
.. _table_example_simple:
.. table:: Example of table that spans multiple pages
   :class: longtable

   ========== =============== ==========
   Heading 1  Heading 2       Heading 3
   ========== =============== ==========
   row 1      two row         cell 3
              entry
   row 2      data            more
   ========== =============== ==========

Add a writers guide document
Add a writers guide document

Start a simple writers guide for conventions used in this project. For
now it only talks about how tables should be marked up, but it will be
expanded on later.

Signed-off-by: Grant Likely <9069e6f5a2b566e2674a0ba1e2bf39c12c195fad@linaro.org>
