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

None
closed-fixed
nobody
None
5
2016-11-16
2015-01-01
No

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

2 Attachments

Discussion

  • 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 ?

     
  • engelbert gruber

    • status: open --> closed-accepted
     
  • Günter Milde

    Günter Milde - 2015-02-23
    • status: closed-accepted --> open
     
  • Günter Milde

    Günter Milde - 2015-02-23

    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

    Günter Milde - 2016-08-05
    • status: open --> closed-fixed
     
  • Günter Milde

    Günter Milde - 2016-08-05

    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

    Brecht Machiels - 2016-11-16

    Thank you, Günther!

     

Log in to post a comment.

Get latest updates about Open Source Projects, Conferences and News.

Sign up for the SourceForge newsletter:





No, thanks