From: Martin B. <m....@gm...> - 2012-03-02 20:55:23
|
Hello everybody, I'm glad to be here back again. Please watch my question at the end. ================================================== 'field-list-table' implemented ================================================== Last december I presented an implementation of the 'field-list-table' directive: http://article.gmane.org/gmane.text.docutils.devel/5894/ It's an old idea from 2005 or so that otherwise never had been implemented. Please see this (!) demonstration and specification of the 'field-list-table' directive: http://mbless.de/4us/typo3-oo2rest/06-The-%5Bfield-list-table%5D-directive/1-demo.rst.html Source, README and files are here: http://mbless.de/4us/typo3-oo2rest/06-The-%5Bfield-list-table%5D-directive/ ================================================== This is where we need the 'field-list-table' directive ================================================== The TYPO3 community (http://typo3.org) currently has a lot of OpenOffice documents that make heavy use of tables. A "famous" document known for its complexity is the TSRef, which looks like this when saved as HTML: http://srv123.typo3.org/~mbless/2012-03-02/doc_core_tsref/100-manual-directly-from-OpenOffice.html With the 'field-list-table' directive it's possible to keep those tables!: http://srv123.typo3.org/~mbless/2012-03-02/doc_core_tsref/500-manual-made-by-rst2html.html The ReST file for this is: http://srv123.typo3.org/~mbless/2012-03-02/doc_core_tsref/400-manual-parsed-by-html2rst.rst.txt You may want to browse the files yourself: http://srv123.typo3.org/~mbless/2012-03-02/doc_core_tsref/ *Note:* I think the field-list-table directive vastly inhances Docutils table handling capabilities! ============================================================ A build chain to convert OpenOffice -> HTML -> XHTML -> ReST -> HTML ============================================================ What I wrote about the 'ooxhtml2rst' parser an build chain to go from OpenOffice to ReST is available here: http://lists.typo3.org/pipermail/typo3-project-documentation/2012-March/003578.html ============================================================ And here is my question ... ============================================================ I would very much like to have this directive in the Docutils core. Q: What exactly do I have to do to make this possible? Any help appreciated! Best greetings from Münster (Westf.) / Germany Martin -- http://mbless.de |
From: Martin B. <m....@gm...> - 2012-03-05 13:15:39
|
[Martin Bless] wrote & schrieb: >You may want to browse the files yourself: > >http://srv123.typo3.org/~mbless/2012-03-02/doc_core_tsref/ There's a much better result now at: http://srv123.typo3.org/~mbless/2012-03-03/ I'm not using html2xhtml anymore but a preprocessor of my own instead. Martin -- http://mbless.de |
From: Guenter M. <mi...@us...> - 2012-03-08 10:50:16
|
Dear Martin, On 2012-03-02, Martin Bless wrote: Thanks for sharing your work: > 'field-list-table' implemented ... > Please see this (!) demonstration and specification of the > 'field-list-table' directive: > http://mbless.de/4us/typo3-oo2rest/06-The-%5Bfield-list-table%5D-directive/1-demo.rst.html > Source, README and files are here: > http://mbless.de/4us/typo3-oo2rest/06-The-%5Bfield-list-table%5D-directive/ ... > I think the field-list-table directive vastly inhances Docutils table > handling capabilities! I see a use for "sparse tables" with lots of open cells and for "data display". > I would very much like to have this directive in the Docutils core. > Q: What exactly do I have to do to make this possible? * File a feature request at the docutils tracker so we have a permanent reminder. (Downside: it may be buried among all the other feature requests for a long time.) * Convince a Docutils developer that this is a valuable addition worth the effort. This might involve discussing (and compromising on) design and implementation details. * Have a look at the Guidelines http://docutils.sourceforge.net/docs/dev/policies.html for coding and documentation conventions. * Make sure that the standard writers can process the resulting document tree. * Make the addition fit. Look at the Docutils sources to see how other directives are implemented, learn to do it "the Docutils way". * Prepare test cases. This vastly helps when integrating new code. Test cases are also examples and showcases for new features. * Prepare the documentation as an addition to the existing documentation (e.g. a patch to directives.txt + parts to other places). Additional documentation might go to a "Tables in Docutils" howto. Günter |
From: Martin B. <m....@gm...> - 2012-03-08 15:05:29
|
[Guenter Milde] wrote & schrieb: >Thanks for sharing your work: :-) >I see a use for "sparse tables" with lots of open cells and for >"data display". Yes. At least it would be a "nice to have" there. But there's a real demand for it if you're dealing with really complex tables. Complex in the sense that cells contain **much** contents. As said in the Docutils docs: """Grid tables are complete but cumbersome to create. Simple tables are easy to create but limited (no row spans, etc.).""" The field-list-table directives offers a way to overcome these limitations in a very "Docutils like way". You can easily represent cells that span pages because it's just a matter of writing normal ReST text plus indentation an a :field-name: as lead in. >> Q: What exactly do I have to do to make this possible? [detailed list given] Great. That's what I was looking for. Thank you very much for taking the time to give that comprehensive answer. That tells me the right direction. "I'll do my very best [TM Dinner for One]". And when ready I'll file that feature request in the docutils tracker. Martin -- http://mbless.de |
From: Guenter M. <mi...@us...> - 2012-03-08 21:51:43
|
On 2012-03-08, Martin Bless wrote: > [Guenter Milde] wrote & schrieb: >>Thanks for sharing your work: >:-) >>I see a use for "sparse tables" with lots of open cells and for >>"data display". > Yes. > At least it would be a "nice to have" there. > But there's a real demand for it if you're dealing with really complex > tables. Complex in the sense that cells contain **much** contents. As > said in the Docutils docs: """Grid tables are complete but cumbersome > to create. Simple tables are easy to create but limited (no row spans, > etc.).""" The field-list-table directives offers a way to overcome > these limitations in a very "Docutils like way". You can easily > represent cells that span pages because it's just a matter of writing > normal ReST text plus indentation an a :field-name: as lead in. Playing the devils advocate: What is the advantage over csv-tables? >>> Q: What exactly do I have to do to make this possible? > [detailed list given] > Great. That's what I was looking for. Thank you very much for taking > the time to give that comprehensive answer. That tells me the right > direction. "I'll do my very best [TM Dinner for One]". And when ready > I'll file that feature request in the docutils tracker. Two little thoughts: I'd like to discuss the definition (options, content formatting) here on the list before everything is fixed and we get backwards compatibility issues (and also before you put too much work into details). Maybe you can post a short documentation in the style of directives.txt as a start. If you get yourself a Git clone the repository from git clone git://repo.or.cz/docutils.git, you can create a feature-branch for the integration work and file patches. If you want to commit yourself, you need developer access, and a copy via SVN or git-svn. Günter |
From: David G. <go...@py...> - 2012-03-08 23:50:31
|
On Fri, Mar 2, 2012 at 15:54, Martin Bless <m....@gm...> wrote: > Q: What exactly do I have to do to make this possible? In addition to what Günter said: be patient, and be persistent. None of us are paid to do this, it's all in our spare time -- which is precious and rare. I meant to respond to this proposal when you first posted it, but didn't have time. Sorry for the delay. > With the 'field-list-table' directive it's possible to keep those > tables!: > http://srv123.typo3.org/~mbless/2012-03-02/doc_core_tsref/500-manual-made-by-rst2html.html Which tables in particular are illustrative, and how? What features of these tables are not possible using another form of table (e.g. list-table)? > *Note:* > I think the field-list-table directive vastly inhances Docutils table > handling capabilities! I agree, modulo the comments below. > Please see this (!) demonstration and specification of the > 'field-list-table' directive: > http://mbless.de/4us/typo3-oo2rest/06-The-%5Bfield-list-table%5D-directive/1-demo.rst.html I have several issues with this, detailed below (relevant portions quoted with ">"). In general, I object to the creation of new "mini-syntax" within reStructuredText. reST already has plenty of explicit syntax that we can use, so let's not complicate it. Think "minimal". > * :year,10: Year I don't like the ",10" here. Instead of complicating the field name, why not put it in the field content, perhaps as a nested field list? E.g.: * :year: Year :width: 10 Alternatively, use a ":widths:" directive option, like the other data-driven list directives do. > * :a..c: This header cell in the first row of the table > spans the whole table row This span syntax seems reasonable. I think I'd prefer using an ellipsis mark, "..." (three periods). But ellipsis means "something is omitted here". Maybe a hyphen is better, since one of its meanings is "span": * :a - c: This header cell in the first row of the table spans the whole table row We could either forbid hyphens from field names, or we could require that the hyphen have spaces around around them (to allow for field names like "type-a"). The en-dash is really the proper character to indicate ranges, but it's hard to type. Two hyphens are often used to indicate an en-dash. Requiring two hyphens would obviate the need for spaces or forbidding hyphens (as above); just forbid double-hyphens in field names. * :type-a--type-c: This header cell in the first row of the table spans the whole table row I'd leave the option of using surrounding spaces though. Another option is to use a tilde ("~"), which also has the meaning of "range" in some languages. > We can have column spans. To make these possible even for > the first table row there is an option "definition-row" > working as a flag. It defaults to "no". This is clumsy. A table's columns always require an initial definition. How about defining the first row so that if there is no display content (definition field lists aren't display content), it acts only as a definition row? .. field-list-table:: Table with column spans. :header-rows: 2 * .. Definition rows are not displayed. :a: :b: :c: * :a -- c: This header cell in the first row of the table spans the whole table row * :a: Column A :b: Column B :c: Column C > :(a): I don't like this row span syntax. I'd much rather declare a row span where the actual cell content is, and omit that cell in later rows. (It would be an error not to omit a spanned cell.) We could indicate the number of rows to span, like this: * :a / 2: This cell will span two rows. The default would be equivalent to "/ 1". As with column spans, either forbid slashes ("/") from field names, or require spaces around them. Or, as with column spans earlier, we could require double-slashes for row spans: * :type-a -- 27b/6 // 3: Cell content here. Combining with column spans: * :a - c // 2: This cell will span three columns and two rows. Without this type of row span syntax, you'd have to explicitly omit (with ":(a):"-type syntax) N-1 cells for an N-row cell. That would get old very quickly! > Alignment for columns ... > * :0: > :1,,l m: left middle As with widths, I don't like putting this into the field names. And that ",," positional syntax (omitted width) is bad. Better to use the same syntax as the image directive: * :a: Column Title :width: 10 :align: top left > Alignment for individual table cells This wouldn't be possible with the above syntax, but I'm leaning toward calling YAGNI (you ain't gonna need it) on that. A while ago I began work on an extension to the "class" directive to apply to the container, to allow specifying a class for a table cell or row or column. That might work here too. One of these days I'll finish that extension. > 3.11 Comments within the source of a field-list-table > > If the field name consists of punctuation characters only the whole > field list item is treated as comment and removed before further > processing starts. No, absolutely not. ReST already has a comment syntax, "..", so let's use it. > .. field-list-table:: > :header-rows: 1 > > * :=========================================: > :---: This is comment only > :~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~: Why would we ever need a comment-only row? > * :---: comment. This is the definition row. > :firstrealcolumn: First > :second: Second Instead: * .. A comment. This is the definition row. :firstrealcolumn: First :second: Second Just have the directive code filter out comments from the parsed list. > The total width of a table row defaults to 100. It may be set to > another positive integer value using the 'total-width' option of the > field-list-table directive. > > The width of columns without explicit specification will be assigned > automatically. To what? How? > Any remaining free space in the row equally be distributed to those > columns. What if the total is more than 100? Let's avoid proliferation of directive options. If it isn't absolutely necessary, drop it. This one is not necessary. Instead, require that if you define any column widths you must define them all. Then instead of defaulting the total width to 100, make the total width the total of the individually specified widths. Alternatively, in a table where at least one width is specified, unspecified widths default to, say, 10. > option_spec = { > 'class' : directives.class_option, > 'name' : directives.unchanged, > 'header-rows' : directives.nonnegative_int, > 'stub-columns' : directives.nonnegative_int, > > 'definition-row' : yes_no_zero_one, > 'total-width' : directives.nonnegative_int, > 'allow-comments' : yes_no_zero_one, > 'debug-cellinfo' : yes_no_zero_one, > 'transformation' : yes_no_zero_one, > } With the above changes, we can drop all of the second group of options, leaving only the standard table directive options. 'definition-row', 'total-width', and 'allow-comments' become unnecessary as per the above. 'debug-cellinfo' is not useful to reST users (document authors), only to the directive developer. If necessary, it should be an option in the code and not exposed to users. > 'transformation' I have no idea why you think this is useful. Please explain, or drop it. -- David Goodger <http://python.net/~goodger> |
From: Guenter M. <mi...@us...> - 2012-03-09 11:18:09
|
On 2012-03-08, David Goodger wrote: > On Fri, Mar 2, 2012 at 15:54, Martin Bless <m....@gm...> wrote: >> Q: What exactly do I have to do to make this possible? > In addition to what Günter said: be patient, and be persistent. None > of us are paid to do this, it's all in our spare time -- which is > precious and rare. I'd like to put a "How to get a new feature into docutils" guide somewhere in the Docutils documentation. Where would it fit: * a chapter in the Policies__, * a separate document in docs/howto/, * or somewhere else? __ http://docutils.sourceforge.net/docs/dev/policies.html --------------------------------------------------------------------- >> Please see this (!) demonstration and specification of the >> 'field-list-table' directive: >> http://mbless.de/4us/typo3-oo2rest/06-The-%5Bfield-list-table%5D-directive/1-demo.rst.html > I have several issues with this, detailed below (relevant portions > quoted with ">"). In general, I object to the creation of new > "mini-syntax" within reStructuredText. reST already has plenty of > explicit syntax that we can use, so let's not complicate it. > Think "minimal". >> * :year,10: Year > I don't like the ",10" here. Instead of complicating the field name, > why not put it in the field content, perhaps as a nested field list? > E.g.: > * :year: Year > :width: 10 I do not like the idea to have the definition in the directive content. > The first field list always is the definition row. Instead, I propose a "column definition option", like:: .. field-list-table:: :columns: :a: :b: :c: The ``:comumns:`` option is used to specify * column order, * column widths, * column alignment if it is ommited, every new field name starts a new column with default values, so that e.g.:: .. field-list-table:: * :a: hallo :b: welt * :c: ! is equivalent to:: ===== ===== ===== hallo welt .. ! ===== ===== ===== > Alternatively, use a ":widths:" directive option, like the other > data-driven list directives do. As a "column alignment" option is useful for the other data-driven list directives as well, the alternative could be:: .. field-list-table:: :columns: :a:, :b:, :c: :widths: 10, 20, 30 :alignments: right, left, center Alternative syntax inside the :columns: option:: :columns: a, b, c (requires an agreement on the column name separator, here ``, `` with compulsory space). +1 separate :widths: and :alignments: options allow to specify column widths and alignment also without explicit column naming/ordering. +2 common options for data-driven tables +1 more compact >> * :a..c: This header cell in the first row of the table >> spans the whole table row > This span syntax seems reasonable. I think I'd prefer using an > ellipsis mark, "..." (three periods). or an HORIZONTAL ELLIPSIS (three dot leader) a…b (AltGr + , on my keyboard) > But ellipsis means "something is omitted here". > Maybe a hyphen is better, since one of its meanings > is "span": > * :a - c: This header cell in the first row of the table > spans the whole table row > We could either forbid hyphens from field names, or we could require > that the hyphen have spaces around around them (to allow for field > names like "type-a"). > The en-dash is really the proper character to indicate ranges, but > it's hard to type. Not only this, but this would also be an exception to the custom to give only ASCII characters a special meaning. > Two hyphens are often used to indicate an en-dash. > Requiring two hyphens would obviate the need for spaces or forbidding > hyphens (as above); just forbid double-hyphens in field names. > * :type-a--type-c: > This header cell in the first row of the table > spans the whole table row > I'd leave the option of using surrounding spaces though. > Another option is to use a tilde ("~"), which also has the meaning of > "range" in some languages. Lets compare the alternatives:: :a..c: :Augenfarbe..column 3: :a...c: :Augenfarbe...column 3: :a-c: :Augenfarbe-column 3: :a--c: :Augenfarbe--column 3: :a~c: :Augenfarbe~column 3: :a~~c: :Augenfarbe~~column 3: :a .. c: :Augenfarbe .. column 3: :a ... c: :Augenfarbe ... column 3: :a - c: :Augenfarbe - column 3: :a -- c: :Augenfarbe -- column 3: :a ~~ c: :Augenfarbe~~column 3: * A low separator (,.) leaves short names better visible as separate entities than a middle or high one (-~). * Spaces around the separator improve readability with long names. * A single delimiter char is easily overseen if spaces are allowed in column IDs * Using double chars for special means is custom in Docutils. My scores: `` -- ``: 0 -3 commonly used in compound words (in German even more than in English) +1 with compulsory whitespace +2 double char ``..``: 0 -2 used as comment start string in Docutils +1 used for spans in numpy. For my eyes, 2..5 is a clear indication of a span. +1 optional whitespace All other variants score less. >> We can have column spans. To make these possible even for >> the first table row there is an option "definition-row" >> working as a flag. It defaults to "no". > This is clumsy. A table's columns always require an initial > definition. How about defining the first row so that if there is no > display content (definition field lists aren't display content), > it acts only as a definition row? > .. field-list-table:: Table with column spans. > :header-rows: 2 > * .. Definition rows are not displayed. > :a: > :b: > :c: > * :a -- c: This header cell in the first row of the table > spans the whole table row > * :a: Column A > :b: Column B > :c: Column C This is not a problem with a :columns: directive option:: .. field-list-table:: Table with column spans. :header-rows: 1 :columns: a | b | c * :a -- c: This header cell in the first row of the table spans the whole table row * :a: Column A :c: Column C >> :(a): > I don't like this row span syntax. I'd much rather declare a row span > where the actual cell content is, and omit that cell in later rows. > (It would be an error not to omit a spanned cell.) > We could indicate the number of rows to span, like this: > * :a / 2: This cell will span two rows. > The default would be equivalent to "/ 1". As with column spans, > either forbid slashes ("/") from field names, or require spaces around > them. > Or, as with column spans earlier, we could require double-slashes for > row spans: > * :type-a -- 27b/6 // 3: Cell content here. > Combining with column spans: > * :a - c // 2: This cell will span three columns and two rows. I'd use `` //[0-9]+`` without a space between // and the number:: * :type-a -- 27b/6 //3: Still not optimal but rare. * :a -- c //2: This cell will span three columns and two rows. >> Alignment for columns > ... >> * :0: >> :1,,l m: left middle > As with widths, I don't like putting this into the field names. And > that ",," positional syntax (omitted width) is bad. I vote for a common :alignments: option for the data driven table directives (see above). >> 3.11 Comments within the source of a field-list-table >> If the field name consists of punctuation characters only the whole >> field list item is treated as comment and removed before further >> processing starts. > No, absolutely not. ReST already has a comment syntax, "..", so let's > use it. ... > Just have the directive code filter out comments from the parsed list. seconded. >> The total width of a table row defaults to 100. It may be set to >> another positive integer value using the 'total-width' option of the >> field-list-table directive. We could consider to give all table directive a :width: option with the same meaning as in image and figure: 'width' : length or percentage of the current line width >> The width of columns without explicit specification will be assigned >> automatically. > To what? How? Similar to the way this is done in CSV and List tables? A comma- or space-separated list of relative column widths. The default is equal-width columns (100%/#columns). However, I propose to allow "length" valuse in the :widths: directive for all data driven tables. >> Any remaining free space in the row equally be distributed to those >> columns. > What if the total is more than 100? With my proposal, this would mean the table is wider than "textwidth", just like in case of an image. > Let's avoid proliferation of directive options. If it isn't > absolutely necessary, drop it. This one is not necessary. > Instead, require that if you define any column widths you must define > them all. Then instead of defaulting the total width to 100, make the > total width the total of the individually specified widths. > Alternatively, in a table where at least one width is specified, > unspecified widths default to, say, 10. We could also define an 'auto' and/or 'fit' keyword for column width specification, e.g. :widths: 2cm, auto, auto would leave the determination of the width of the last two columns to some algorightm or the backend. :widths: 2cm, fit, fit would make the last two colums as wide as required for the content (adapting the table width). > With the above changes, we can drop all of the second group of > options, leaving only the standard table directive options. I prefer one additional option (:columns:) over the definition line in the content. Günter |
From: David G. <go...@py...> - 2012-03-10 18:33:26
|
On Fri, Mar 9, 2012 at 06:17, Guenter Milde <mi...@us...> wrote: > On 2012-03-08, David Goodger wrote: >> On Fri, Mar 2, 2012 at 15:54, Martin Bless <m....@gm...> wrote: > >>> Q: What exactly do I have to do to make this possible? > >> In addition to what Günter said: be patient, and be persistent. None >> of us are paid to do this, it's all in our spare time -- which is >> precious and rare. > > I'd like to put a "How to get a new feature into docutils" guide somewhere > in the Docutils documentation. Where would it fit: > > * a chapter in the Policies__, > * a separate document in docs/howto/, > * or somewhere else? > > __ http://docutils.sourceforge.net/docs/dev/policies.html A short section would fit in the Policies doc. Something longer should probably be a separate doc (but add a link to and from Policies, since there is relevant material there). docs/howto/ seems like a good place. Feel free to move material around if it makes sense. Just leave links behind! >>> Please see this (!) demonstration and specification of the >>> 'field-list-table' directive: >>> http://mbless.de/4us/typo3-oo2rest/06-The-%5Bfield-list-table%5D-directive/1-demo.rst.html > >> I have several issues with this, detailed below (relevant portions >> quoted with ">"). In general, I object to the creation of new >> "mini-syntax" within reStructuredText. reST already has plenty of >> explicit syntax that we can use, so let's not complicate it. >> Think "minimal". > >>> * :year,10: Year > >> I don't like the ",10" here. Instead of complicating the field name, >> why not put it in the field content, perhaps as a nested field list? >> E.g.: > >> * :year: Year > >> :width: 10 > > > I do not like the idea to have the definition in the directive content. > > > The first field list always is the definition row. > > Instead, I propose a "column definition option", like:: > > .. field-list-table:: > :columns: :a: > :b: > :c: I'm a bit wary of an option that perhaps shouldn't be optional. > The ``:comumns:`` option is used to specify > > * column order, > * column widths, > * column alignment Other than the order, how? Please show an example. > if it is ommited, every new field name starts a new column with default > values... That makes sense to me. >> Alternatively, use a ":widths:" directive option, like the other >> data-driven list directives do. > > As a "column alignment" option is useful for the other data-driven list > directives as well, the alternative could be:: > > .. field-list-table:: > :columns: :a:, :b:, :c: > :widths: 10, 20, 30 > :alignments: right, left, center > > Alternative syntax inside the :columns: option:: > > :columns: a, b, c > > (requires an agreement on the column name separator, here ``, `` with > compulsory space). That's fine. We could restrict the column names to the simple "Reference Names" syntax (http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#reference-names), or simply forbid commas in names. I like ":columns: a, b, c" much better than " :columns: :a:, :b:, :c:" or ":columns: :a: :b: :c:" (the latter two may make parsing difficult, and there are just too many colons). > +1 separate :widths: and :alignments: options allow to specify column > widths and alignment also without explicit column naming/ordering. > > +2 common options for data-driven tables > > +1 more compact > >>> * :a..c: This header cell in the first row of the table >>> spans the whole table row > >> This span syntax seems reasonable. I think I'd prefer using an >> ellipsis mark, "..." (three periods). > > or an HORIZONTAL ELLIPSIS (three dot leader) a…b (AltGr + , on my keyboard) That could be an alternative, but I wouldn't make it the only choice, since it's hard to enter (non-ASCII). >> But ellipsis means "something is omitted here". > >> Maybe a hyphen is better, since one of its meanings >> is "span": > >> * :a - c: This header cell in the first row of the table >> spans the whole table row > >> We could either forbid hyphens from field names, or we could require >> that the hyphen have spaces around around them (to allow for field >> names like "type-a"). > >> The en-dash is really the proper character to indicate ranges, but >> it's hard to type. > > Not only this, but this would also be an exception to the custom to give > only ASCII characters a special meaning. > >> Two hyphens are often used to indicate an en-dash. >> Requiring two hyphens would obviate the need for spaces or forbidding >> hyphens (as above); just forbid double-hyphens in field names. > >> * :type-a--type-c: >> This header cell in the first row of the table >> spans the whole table row > >> I'd leave the option of using surrounding spaces though. > >> Another option is to use a tilde ("~"), which also has the meaning of >> "range" in some languages. > > Lets compare the alternatives:: > > :a..c: :Augenfarbe..column 3: > :a...c: :Augenfarbe...column 3: > :a-c: :Augenfarbe-column 3: > :a--c: :Augenfarbe--column 3: > :a~c: :Augenfarbe~column 3: > :a~~c: :Augenfarbe~~column 3: > :a .. c: :Augenfarbe .. column 3: > :a ... c: :Augenfarbe ... column 3: > :a - c: :Augenfarbe - column 3: > :a -- c: :Augenfarbe -- column 3: > :a ~~ c: :Augenfarbe~~column 3: > > * A low separator (,.) leaves short names better visible as separate > entities than a middle or high one (-~). > > * Spaces around the separator improve readability with long names. > > * A single delimiter char is easily overseen if spaces are allowed in > column IDs > > * Using double chars for special means is custom in Docutils. > > My scores: > > `` -- ``: 0 > > -3 commonly used in compound words (in German even more than in > English) > +1 with compulsory whitespace > +2 double char > > ``..``: 0 > > -2 used as comment start string in Docutils > +1 used for spans in numpy. > For my eyes, 2..5 is a clear indication of a span. > +1 optional whitespace > > All other variants score less. I like "--" & spaces the best. If we restrict names to reST simple reference names, they couldn't have spaces, so here are some real examples: :column-a -- column-c: :type.a -- type.c: >>> We can have column spans. To make these possible even for >>> the first table row there is an option "definition-row" >>> working as a flag. It defaults to "no". > >> This is clumsy. A table's columns always require an initial >> definition. How about defining the first row so that if there is no >> display content (definition field lists aren't display content), >> it acts only as a definition row? > >> .. field-list-table:: Table with column spans. >> :header-rows: 2 > >> * .. Definition rows are not displayed. > >> :a: >> :b: >> :c: > >> * :a -- c: This header cell in the first row of the table >> spans the whole table row > >> * :a: Column A >> :b: Column B >> :c: Column C > > This is not a problem with a :columns: directive option:: > > .. field-list-table:: Table with column spans. > :header-rows: 1 > :columns: a | b | c > > * :a -- c: This header cell in the first row of the table > spans the whole table row > > * :a: Column A > :c: Column C > > > >>> :(a): > >> I don't like this row span syntax. I'd much rather declare a row span >> where the actual cell content is, and omit that cell in later rows. >> (It would be an error not to omit a spanned cell.) > >> We could indicate the number of rows to span, like this: > >> * :a / 2: This cell will span two rows. > >> The default would be equivalent to "/ 1". As with column spans, >> either forbid slashes ("/") from field names, or require spaces around >> them. > >> Or, as with column spans earlier, we could require double-slashes for >> row spans: > >> * :type-a -- 27b/6 // 3: Cell content here. > >> Combining with column spans: > >> * :a - c // 2: This cell will span three columns and two rows. > > I'd use `` //[0-9]+`` without a space between // and the number:: > > * :type-a -- 27b/6 //3: Still not optimal but rare. > > * :a -- c //2: This cell will span three columns and two rows. I don't see much of a difference, aesthetically. But it's easier to parse (both for humans and software) if spaces are required. >>> Alignment for columns >> ... >>> * :0: >>> :1,,l m: left middle > >> As with widths, I don't like putting this into the field names. And >> that ",," positional syntax (omitted width) is bad. > > I vote for a common :alignments: option for the data driven table > directives (see above). > > >>> 3.11 Comments within the source of a field-list-table > >>> If the field name consists of punctuation characters only the whole >>> field list item is treated as comment and removed before further >>> processing starts. > >> No, absolutely not. ReST already has a comment syntax, "..", so let's >> use it. > > ... > >> Just have the directive code filter out comments from the parsed list. > > seconded. > > >>> The total width of a table row defaults to 100. It may be set to >>> another positive integer value using the 'total-width' option of the >>> field-list-table directive. > > We could consider to give all table directive a :width: option with the same > meaning as in image and figure: > > 'width' : length or percentage of the current line width +0 >>> The width of columns without explicit specification will be assigned >>> automatically. > >> To what? How? > > Similar to the way this is done in CSV and List tables? > > A comma- or space-separated list of relative column widths. The default > is equal-width columns (100%/#columns). > > However, I propose to allow "length" valuse in the :widths: directive for > all data driven tables. +0 >>> Any remaining free space in the row equally be distributed to those >>> columns. > >> What if the total is more than 100? > > With my proposal, this would mean the table is wider than "textwidth", just > like in case of an image. > >> Let's avoid proliferation of directive options. If it isn't >> absolutely necessary, drop it. This one is not necessary. > >> Instead, require that if you define any column widths you must define >> them all. Then instead of defaulting the total width to 100, make the >> total width the total of the individually specified widths. > >> Alternatively, in a table where at least one width is specified, >> unspecified widths default to, say, 10. > > We could also define an 'auto' and/or 'fit' keyword for column width > specification, e.g. > > :widths: 2cm, auto, auto > > would leave the determination of the width of the last two columns to > some algorightm or the backend. > > :widths: 2cm, fit, fit > > would make the last two colums as wide as required for the content (adapting > the table width). -0: this seems to be getting too complicated. I'd rather leave it off and add it later if it proves necessary. >> With the above changes, we can drop all of the second group of >> options, leaving only the standard table directive options. > > I prefer one additional option (:columns:) over the definition line in the > content. No objection. -- David Goodger <http://python.net/~goodger> |
From: Martin B. <m....@gm...> - 2012-03-12 10:57:38
|
Hello David, hallo Günter, [David Goodger] wrote & schrieb: >be patient, and be persistent. None >of us are paid to do this, it's all in our spare time -- which is >precious and rare. yes, yes. Same with me: I know. I'm a volunteer as well! Thank you both very much for your considerations and comments in this thread. I'll think it over and try to improve the proposal. And then I'll show it here. All the best! Martin -- http://mbless.de |
From: Guenter M. <mi...@us...> - 2012-03-23 08:09:47
|
On 2012-03-10, David Goodger wrote: > On Fri, Mar 9, 2012 at 06:17, Guenter Milde <mi...@us...> wrote: >> On 2012-03-08, David Goodger wrote: >>> On Fri, Mar 2, 2012 at 15:54, Martin Bless <m....@gm...> wrote: Dear David and Martin, here is a usage example and one more idea for the :columns: directive option. >>>> Please see this (!) demonstration and specification of the >>>> 'field-list-table' directive: >>>> http://mbless.de/4us/typo3-oo2rest/06-The-%5Bfield-list-table%5D-directive/1-demo.rst.html ... >> I do not like the idea to have the definition in the directive content. >> > The first field list always is the definition row. >> Instead, I propose a "column definition option" Examples:: 1. field-list table without options .. field-list-table:: * :a: :b: first row specifies just two columns * :c: second row specifies the third column -> 2 columns (a, b, c), 2 rows 2. field-list table with "colums" specification: .. field-list-table:: :columns: a, c, d, b * :a: first row, first column :b: first row, last column * :c: second row, second column -> 4 columns (a,c,d,b), column d empty ... >> ... syntax inside the :columns: option:: >> :columns: a, b, c >> (requires an agreement on the column name separator, here ``, `` with >> compulsory space). > That's fine. We could restrict the column names to the simple > "Reference Names" syntax > (http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#reference-names), > or simply forbid commas in names. > I like ":columns: a, b, c" much better than " :columns: :a:, :b:, :c:" > or ":columns: :a: :b: :c:" (the latter two may make parsing > difficult, and there are just too many colons). Agreed. However, I don't like a restriction on column names that goes beyond the restrictions already placed on field-list names. Reason: without this restriction, the field-list-table can be used for an alternative representation of a field-list:: .. field-list-table:: .. include:: file-with-field-list.txt Alternatives: a) whitespace as separator, optional colons around column names, (required for complex field/column names):: .. field-list-table:: :columns: a b c:1 :c 2: b) comma as separator, optional whitespace, optional colons (required for comma-escaping):: .. field-list-table:: :columns: a, b, c:1, :c,2: +1 colons only if required, +1 wrapping complex field-list names in colons does not place additional restrictions on valid names (as ``: `` needs escaping in a field-list name, too), +1 for b) because the comma indicates a listing. Günter |