#120 Extend and unify the table directives' :widths: option

[Brecht Machiels]

See the "Table suggestions" thread on the docutils develop mailing list [1]. A summary of the patches:

• The table directive (for simple and grid tables) now accepts a :widths: option, accepting a list of integers for manually specifying the column widths (analogous to csv and list tables).
• The :widths: option for all table directives (table, csv-table and list-table) will now also accept an 'auto' value to instruct the backend to automatically size the columns based on their contents.
• For all tables (so also simple/grid tables without table directive), :widths: is assumed to be 'auto' when the :widths: option is not specified, so that :widths: behavior is uniform across the table directives. I believe the choice for ":widths: auto" is obvious for csv and list tables. For simple/grid tables, this is debatable, but I'd go for consistency across the different table formats.
• The column widths (based on the ASCII grid, or equal widths for csv/list tables) are passed as a colspec attribute as before. A tgroup attribute 'colwidths' instructs the backend to automatically size the columns or use the supplied widths. This allows backends with limited means of automatically sizing the columns (such as LaTeX) to fall back to the supplied column widths.
• The (simple/grid) table directive additionally accepts a 'grid' value for :widths: to instruct the backend to use the column widths as determined from the ASCII column widths (this is the current behavior).

As discussed in the "Table suggestions" thread, I initially planned to remove the colwidth attributes from the colspec doctree nodes for :widths: auto, but this would be problematic for the LaTeX backend. I believe the patches provide a pragmatic solution to this.

All backend should continue to work as before, as in the doctree, the tgroup will only have the extra 'colwidths' attribute. I can adjust the HTML backend to automatically size columns if these patches are accepted. I suggest leaving the LaTeX backend as-is for now.

[1] http://thread.gmane.org/gmane.text.docutils.devel/6884

[engelbert gruber]

(sorry for slow reaction)

And I have a question does the width need some unit ?
Is it always "%" ?

If so should we make it explicit "widths: 15%, 25%" ?
Or at least optional ?

[Günter Milde]

We still need a documentation update for this change.
(Description of the new options in docs/ref/rst/directives.txt)

Also, IMV an explicitely set option ":with: auto" should enable auto-sizing of column widths in LaTeX.

(Actually, I'd like a more fine-grained approach where for each column a length value or "auto" could be given.)

[Günter Milde]

A modified version of the patch(es) is now applied, tested and documented:

The table directive (for simple and grid tables) now accepts a :widths:
option, accepting a list of integers for manually specifying the column
widths (analogous to csv and list tables).

The :widths: option for all table directives (table, csv-table and
list-table) will now also accept an 'auto' value

For all tables (so also simple/grid tables without table directive),
:widths: is assumed to be 'auto' when the :widths: option is not
specified, so that :widths: behavior is uniform across the table
directives. I believe the choice for ":widths: auto" is obvious for csv
and list tables. For simple/grid tables, this is debatable, but I'd go
for consistency across the different table formats.

Changed:
For backards compatibility, the default value is kept as-is, writers
may use a sensible default. For the "html5" and "latex" writers, the
default can be set with the "table-style" configuration option.

The column widths (based on the ASCII grid, or equal widths for
csv/list tables) are passed as a colspec attribute as before.

A tgroup attribute 'colwidths' instructs the backend to automatically
size the columns or use the supplied widths. This allows backends with
limited means of automatically sizing the columns (such as LaTeX) to
fall back to the supplied column widths.

The (simple/grid) table directive additionally accepts a 'grid' value
for :widths: to instruct the backend to use the column widths as
determined from the ASCII column widths (this is the current behavior).

Changed:

the special class values "colwidths-auto" and "colwidths-given",
recommend the writer to let the renderer (HTML-browser, LaTeX) size
the columns based on their contents or use the colspec values respectively.

• A new tgroup attribute requires a change in the Docutils DTD

• Class values are already defined in the rST specs for carrying
  additional info that may be ignored by some writers.
  http://docutils.sourceforge.net/docs/ref/doctree.html#classes

  The specification says, the classes attribute "should not be used to
  carry formatting instructions or arbitrary content."

  OTOH, "It can be used to carry context forward between a Docutils
  Reader and Writer, when a custom structure is reduced to a
  standardized document tree. One common use is ... to add selection
  criteria."

• The "table-style" option for HTML and LaTeX writers to
  set default class values can be used to support configurable defaults
  without the need for yet another configuration setting.

I can also live with an addition to the DTD if someone provides a complete
solution.

Thanks for your contribution.

[Brecht Machiels]

Thank you, Günther!