User discussion for the docutils project.

Felix Wiemann | 4 Sep 2005 00:23

Picon

Re: Images as tables

David Goodger wrote:

> Alan G Isaac wrote:
>
>> In LaTeX, tables and figures are specific examples of
>> floats, which support numbering.  Is this abstraction
>> relevant to docutils?
>
> Yes, it is, sort-of.  The "float"-ness of LaTeX tables and figures
> refers (IIRC) to the ability of the contents to float to one end or
> the other of the page, or to the next page, for good pagination.
> Docutils doesn't care about floating-vs-stationary; that's a back-end
> rendering issue.

It's normally not possible (unfortunately, maybe) to render figures as
"floating" (the LaTeX way) because the document author may assume that
the figure is rendered where it appears in the source.

> In Docutils, formal figures and tables and examples are all examples
> of sequences -- there's a sequence counter and title/caption
> embellishment associated.

BTW, for uniformity it would probably be a good idea to use the "title"
node for figures.

> The "image as table" that Dima described is a prime example of how the
> "formal table" directive should support arbitrary content.

-1.  Use the following construct instead::

(Continue reading)

David Goodger | 9 Sep 2005 14:56

Re: Re: Images as tables

[Felix Wiemann]
> BTW, for uniformity it would probably be a good idea to use the
> "title" node for figures.

Perhaps.  ISTR that suggestion coming up earlier.

[David Goodger]
>> The "image as table" that Dima described is a prime example of how
>> the "formal table" directive should support arbitrary content.

[Felix Wiemann]
> -1.  Use the following construct instead::
>
>     .. figure::
>        :sequence: table
>
>        .. image:: image_of_a_table.png
>
> The "table" directive creates a table.  It will grow table-specific
> options (like :widths:), and turning it into a partially generic
> directive would result in a mess.

IMO the example above is a mess too.  It's misusing one feature for
another.  I think the solution is a new set of directives for formal
objects (numbered & possibly titled), as in DocBook.

>> It cannot be implemented as a "figure" because that would result in
>> a "Figure 1." embellishment,
>
> Not when specifying ":sequence: table".

(Continue reading)

G. Milde | 6 Sep 2005 13:00

Picon

Re: Re: Images as tables

On  4.09.05, Felix Wiemann wrote:
> David Goodger wrote:
> 
> > Alan G Isaac wrote:
> >
> >> In LaTeX, tables and figures are specific examples of
> >> floats, which support numbering.  Is this abstraction
> >> relevant to docutils?
> >
> > Yes, it is, sort-of.  The "float"-ness of LaTeX tables and figures
> > refers (IIRC) to the ability of the contents to float to one end or
> > the other of the page, or to the next page, for good pagination.
> > Docutils doesn't care about floating-vs-stationary; that's a back-end
> > rendering issue.

However, other distinctive features of LaTeX floats are relevant to docutils
regardless of the output medium: 

  * Floats are numbered
  * Floats can be listed in a "list of ..."

I think this is what distinguishes docutil's "sequences":

> > In Docutils, formal figures and tables and examples are all examples
> > of sequences -- there's a sequence counter and title/caption
> > embellishment associated.

> It's normally not possible (unfortunately, maybe) to render figures as
> "floating" (the LaTeX way) because the document author may assume that
> the figure is rendered where it appears in the source.

(Continue reading)

David Goodger | 13 Sep 2005 14:11

Re: Re: Images as tables

[David Goodger]
>>> Yes, it is, sort-of.  The "float"-ness of LaTeX tables and figures
>>> refers (IIRC) to the ability of the contents to float to one end
>>> or the other of the page, or to the next page, for good
>>> pagination.  Docutils doesn't care about floating-vs-stationary;
>>> that's a back-end rendering issue.

[G. Milde]
> However, other distinctive features of LaTeX floats are relevant to
> docutils regardless of the output medium:
>
>   * Floats are numbered
>   * Floats can be listed in a "list of ..."
>
> I think this is what distinguishes docutil's "sequences":

Yes, exactly; that's what I meant.  That's why I'd rather use
"sequence" or "formal object", and not use the term "float", because
floating is a secondary issue that depends on the back-end renderer.

> In LaTeX, there is a distinction between the float environment and
> the containing block:
>
>  \tabular: environment for "grid data" (commonly also called
>            "table") Similar to the <table> element in html.
>
>  \table: float that appears in "list of tables" and normally
>          contains a \tabular block but could also hold pictures or
>          "anything".

(Continue reading)

Felix Wiemann | 22 Sep 2005 22:47

Picon

Re: Images as tables

David Goodger wrote:

> G. Milde wrote:
>
>> However, other distinctive features of LaTeX floats are relevant to
>> docutils regardless of the output medium:
>>
>>   * Floats are numbered
>>   * Floats can be listed in a "list of ..."
>>
>> I think this is what distinguishes docutil's "sequences":
>
> Yes, exactly; that's what I meant.  That's why I'd rather use
> "sequence" or "formal object", and not use the term "float", because
> floating is a secondary issue that depends on the back-end renderer.

Looks like we agree on this.

>>  [\tabular, \table]
>
> That distinction is useful, but the names are unfortunate.  We won't
> be using those names in Docutils.

No, definitely not.

> I'd keep "table" as the directive for real tabular tables (the latter
> case),

Yes.

(Continue reading)

David Goodger | 4 Oct 2005 23:55

Re: Re: Images as tables

> David Goodger wrote:
>> For the former case (arbitrary content) I'd create a new directive,
>> perhaps
>>
>>     .. table-sequence:: title of "table", whatever that may be
>>
>>        .. image:: image-of-a-table.png

[Felix Wiemann]
> This looks really bad because it represents semantics, not
> structure.  I think directives and doctree nodes should be used to
> represent the *structure* of a document, not the semantics.
> Examples of what I do *not* want to have are the DocBook model, or
> HTML (which contains *four* different elements for representing
> monospaced text).

We have a real use case for images-as-tables.  It's just as valid as
the use case for tables-as-figures, or not-images-as-figures in
general.

Do you have a counter-suggestion?

>> or
>>
>>     .. formal:: title of formal object
>>        :sequence: table
>>
>>        .. image:: image-of-a-table.png
>
> That looks better, but what's wrong with using the "figure"

(Continue reading)

Aahz | 9 Oct 2005 01:22

Re: Re: Images as tables

On Tue, Oct 04, 2005, David Goodger wrote:
> [Felix Wiemann]
>>
>> That looks better, but what's wrong with using the "figure"
>> directive instead of "formal"?  The only difference is "title"
>> vs. "caption".
> 
> No, the difference is "Figure 1:" vs. "Table 1:" as well (sequence and
> pattern).  It's overloading the "figure" directive to do something it
> wasn't meant to do.

Re-reading this, I'm starting to really hate "formal".  (Then again, I
haven't been playing close attention to this discussion, which has been
long-winded and nitpicky -- I'd really appreciate a summary similar to a
PEP, though not as, er, formal.)  Let's use "sequenced" or "enumerated"
instead.  Another idea: borrow from HTML and call them ordered/unordered.

> Here's a thought: we could apply the "container" element to the
> problem.  "Container" could begin with an optional "title" element,
> and have a "sequence" attribute.  It could be used for both generic
> formal *and* informal container elements.

This appeals to me.

Another comment: I don't know how many people on docutils-develop don't
read -users; that's another good reason for writing a summary.
--

-- 
Aahz (aahz <at> pythoncraft.com)           <*>         http://www.pythoncraft.com/

"If you think it's expensive to hire a professional to do the job, wait

(Continue reading)

G. Milde | 27 Sep 2005 13:56

Picon

Re: Re: Images as tables

On 22.09.05, Felix Wiemann wrote:
> David Goodger wrote:

> Please have a look at the following ideas:
> 
> * Regarding the **document model**, I suggest the following::
... 
>   So a figure must have either a title or a caption.

Why not use "title" with a "placement" argument::

    <figure [align="..."]>
        <title [placement="top|bottom"]>     # or [placement="above|below"]
            Figure title.
        Figure contents.

or let simply the position on the tree decide::

    <figure [align="..."]>
        <title>                        	     # top title ("captionabove")
            Figure title.
        Figure contents.

    <figure [align="..."]>
        Figure contents.
        <title>                        	     # bottom title ("captionbelow")
            Figure title.

  With the corresponding **reStructuredText syntax** I

(Continue reading)

David Goodger | 5 Oct 2005 03:40

Re: Re: Images as tables

> On 22.09.05, Felix Wiemann wrote:
>> Please have a look at the following ideas:
>>
>> * Regarding the **document model**, I suggest the following::
> ...
>>   So a figure must have either a title or a caption.

[G. Milde]
> Why not use "title" with a "placement" argument::

Because all "title" elements in all doctrees would then have that
attribute.  Better to put the attribute on the parent element
("figure" in this case).  The title doesn't care where it is, but the
figure cares where the title is!

But I wouldn't go that route.  Rather, ...

> or let simply the position on the tree decide::

Then we might as well keep "caption" elements.

>   The "table" directive should be usable for creating a "formal"
>   table,

Yes.

>   e.g. by creating a figure element passing it the option
>   ``:sequence: table``.
...
> I.e. the ".. table::" directive does not produce a <table> object

(Continue reading)

G. Milde | 5 Oct 2005 17:10

Picon

Re: Re: Images as tables

Dear David,

On  4.10.05, David Goodger wrote:
> > On 22.09.05, Felix Wiemann wrote:
> >> Please have a look at the following ideas:
> >>
> >> * Regarding the **document model**, I suggest the following::
> > ...
> >>   So a figure must have either a title or a caption.
> 
> [G. Milde]
> > Why not use "title" with a "placement" argument::
> 
> Because all "title" elements in all doctrees would then have that
> attribute.  Better to put the attribute on the parent element
> ("figure" in this case).  The title doesn't care where it is, but the
> figure cares where the title is!

This makes sense. Agreed.

> But I wouldn't go that route.  Rather, ...
> 
> > or let simply the position on the tree decide::

OTOH, if the placement (above vs. below) is given as argument to the
parent element, it could be (in a truly "separating content from layout"
manner) changed for the whole document with just one setting.

> Then we might as well keep "caption" elements.

(Continue reading)

Aahz | 6 Oct 2005 19:57

Re: Re: Images as tables

On Wed, Oct 05, 2005, G. Milde wrote:
>
> My name suggestion is *inset* which IMHO conveys the meaning that this is
> (mostly) something out of the main flow of the document (therefore the
> numbering and referencing) and is sufficiently generic to comprise
> figures, tables, examples, info-boxes and maybe even foot- and
> margin-notes.
> 
> I'd also define a generic "inset" directive for less often used cases,
> for example::
> 
>    .. inset:: <title of inset>
>       :sequence: example
>       
>       This is a small example. It will get a number. It might get some
>       coloring by a custom stylesheet.

This looks good to me.  I was thinking of ``object``, but I like ``inset``
better.  Another option that came to mind was using ``sequence`` for the
inset and ``create-sequence`` for creating a sequence.
--

-- 
Aahz (aahz <at> pythoncraft.com)           <*>         http://www.pythoncraft.com/

The way to build large Python applications is to componentize and
loosely-couple the hell out of everything.

-------------------------------------------------------
This SF.Net email is sponsored by:
Power Architecture Resource Center: Free content, downloads, discussions,
and more. http://solutions.newsforge.com/ibmarch.tmpl

(Continue reading)

G. Milde | 6 Sep 2005 10:45

Picon

Re: Re: Images as tables

On  4.09.05, Felix Wiemann wrote:

> I'm still not sure if it's a good idea to have non-uniform captioning
> (above and below).  Would there be anything wrong with *always*
> rendering captions/titles below the figure/table?  That would result in
> uniform rendering of numbered objects.
> 
> I just imagine that it looks weird when you have something like this in
> the output::
> 
>     Some text...
> 
>         <AN IMAGE>
> 
>         Figure 1: An image.
> 
>     Some text...
> 
>         Table 1: A table.
> 
>         +---------+
>         | A TABLE |
>         +---------+
> 
>     Some text...
> 
>  Or do you actually find such inconsistent rendering
> in academic documents?  I've never seen it before.

This is a traditional layout variant in European academic writing. I see

(Continue reading)

Return

Return to gmane.text.docutils.user.

Advertisement

Project Web Page

User discussion for the docutils project.

Search Archive

Language

Change language

Options

Current view: Threads only / Showing only 20 lines / Not hiding cited text.
Change to All messages, whole messages, or hide cited text.

Post a message
NNTP Newsgroup
Classic Gmane web interface
XML

XML

RSS Feed
List Information

About Gmane