From: Dima D. <dim...@gm...> - 2005-08-26 09:07:46
|
Dear all: I'd like to ask if, currently, something like this is possible with reST:: .. table:: This is a fake table... Actually it's an image! .. image:: images/foobar.png :scale: 75 :align: center I have some complex tables that I prefer to create/maintain in a spreadsheet, which I would export as images and link to from my document. But it is very important to me that these "fake" tables show up in the list of tables (not figures) in the LaTeX output. Does anybody recommend an workaround? --=20 /dima |
From: Felix W. <Fel...@gm...> - 2005-08-26 21:11:55
|
Dima Diall wrote: > I'd like to ask if, currently, something like this is possible with reST:: > > .. table:: This is a fake table... Actually it's an image! > > .. image:: images/foobar.png > :scale: 75 > :align: center No, something like that is not possible. > I have some complex tables that I prefer to create/maintain in a > spreadsheet, which I would export as images and link to from my > document. But it is very important to me that these "fake" tables show > up in the list of tables (not figures) in the LaTeX output. > > Does anybody recommend an workaround? I would recommend using the "raw" directive. -- For private mail please ensure that the header contains 'Felix Wiemann'. "the number of contributors [...] is strongly and inversely correlated with the number of hoops each project makes a contributing user go through." -- ESR |
From: David G. <go...@py...> - 2005-08-27 04:30:00
Attachments:
signature.asc
|
> Dima Diall wrote: >> I'd like to ask if, currently, something like this is possible with >> reST:: >> >> .. table:: This is a fake table... Actually it's an image! >> >> .. image:: images/foobar.png >> :scale: 75 >> :align: center [Felix Wiemann] > No, something like that is not possible. ... currently. If we generalize the "figure" directive as is being discussed in the "figure that is not an image" thread, we can (and should) generalize the "table" directive too. -- David Goodger <http://python.net/~goodger> |
From: Mikolaj M. <mi...@wp...> - 2005-08-27 10:54:38
|
David Goodger scripsit: > This is an OpenPGP/MIME signed message (RFC 2440 and 3156) > --------------enig855BE17D654A1C3889D40BA4 > Content-Type: text/plain; charset=ISO-8859-1 > Content-Transfer-Encoding: 7bit > >> Dima Diall wrote: >>> I'd like to ask if, currently, something like this is possible with >>> reST:: >>> >>> .. table:: This is a fake table... Actually it's an image! >>> >>> .. image:: images/foobar.png >>> :scale: 75 >>> :align: center > > [Felix Wiemann] >> No, something like that is not possible. > > ... currently. If we generalize the "figure" directive as is being > discussed in the "figure that is not an image" thread, we can (and > should) generalize the "table" directive too. I am not sure. Figure is very generous element while table is... just table. Of course it can contain more elements than just table but it won't be solution for problems of original poster. There are practical problems. In HTML you can probably use image as background of table (CSS) to create mock-up, but in LaTeX? m. -- LaTeX + Vim = http://vim-latex.sourceforge.net/ Vim Universal Templates: http://vim.sf.net/script.php?script_id=1078 vim.pl - http://skawina.eu.org/mikolaj CLEWN - http://clewn.sf.net |
From: Felix W. <Fel...@gm...> - 2005-08-27 13:38:00
|
David Goodger wrote: > Felix Wiemann wrote: > >> Dima Diall wrote: >> >>> .. table:: This is a fake table... Actually it's an image! >>> >>> .. image:: images/foobar.png >>> :scale: 75 >>> :align: center >> >> No, something like that is not possible. > > ... currently. If we generalize the "figure" directive as is being > discussed in the "figure that is not an image" thread, we can (and > should) generalize the "table" directive too. Nope, that's not a good idea: * It's not orthogonal -- we'd have two directives for one job. * It makes the "table" directive so generic that it cannot have table-specific options anymore. See also <http://docutils.sf.net/docs/dev/todo.html#unify-tables>. -- For private mail please ensure that the header contains 'Felix Wiemann'. "the number of contributors [...] is strongly and inversely correlated with the number of hoops each project makes a contributing user go through." -- ESR |
From: David G. <go...@py...> - 2005-09-09 12:56:48
Attachments:
signature.asc
|
[David Goodger] >> ... currently. If we generalize the "figure" directive as is being >> discussed in the "figure that is not an image" thread, we can (and >> should) generalize the "table" directive too. [Felix Wiemann] > Nope, that's not a good idea: > > * It's not orthogonal -- we'd have two directives for one job. I disagree. The "figure" and "table" directives would be associated with two different sequences, and the embellishment would be different. But read on. > * It makes the "table" directive so generic that it cannot have > table-specific options anymore. See also > <http://docutils.sf.net/docs/dev/todo.html#unify-tables>. That's too strong a statement. If a table directive had exclusively non-table content, *and* it had table-specific options, the result could be considered an error. But say the directive contained some non-table content, a table, some other stuff, and finally another table. Any table-specific options could apply to the first table and ignore the rest, by definition (i.e. it would be documented that way). But I'd much rather implement a new, clean, generic system than patch the existing directives. We should perhaps take a hint from the way DocBook handles these things. DocBook had both formal (with title & sequence numbering) and informal (no title, no number) elements for table, figure, example, equation, and paragraph. Implementing DocBook's solution would be overkill for Docutils, but we can adopt the kernel of the idea. I propose the following: 1. The current directives (table, figure) should remain "informal": no sequence numbering. They (and only they!) still handle table- and figure-specific options. They may have titles/captions, but that is orthogonal to numbering. 2. We implement a new directive, "sequence", that declares new object sequences, their high-level rendering (title or caption, embellishment style), and relationships to other sequences (i.e. what sequence triggers a reset). This has already been discussed in this thread. 3. The resulting sequence can be specified independently, by one or more new "formal" directives (perhaps "titled" and "captioned"; specific names and functionality TBD). These will handle sequence numbering and titles/captions. -- David Goodger <http://python.net/~goodger> |
From: G. M. <g....@we...> - 2005-09-20 10:44:50
|
On 9.09.05, David Goodger wrote: > But I'd much rather implement a new, clean, generic system than patch > the existing directives. > 1. The current directives (table, figure) should remain "informal": no > sequence numbering. They (and only they!) still handle table- and > figure-specific options. They may have titles/captions, but that > is orthogonal to numbering. I'd like to see a generic "numbered, listable object" directive. Name suggestion: "inset" This captures IMO the essence of something that: * relates to the main text but "tells its own story", * is numbered, so that it can be referenced by the main text * can be listed * can (but doesnot need to) "float" (be rendered at a place different from the appearance in the source). Alternatives: "sequence" # IMHO too generic "float" # LaTeX centristic, not correct "listable" "titled" "captioned" Figures, "formal tables", info-boxes, margin-notes, etc. will become special cases of this directive (similar to "attention" or "danger" being special cases of an "admonition"). > 2. We implement a new directive, "sequence", that declares new object > sequences, their high-level rendering (title or caption, > embellishment style), and relationships to other sequences > (i.e. what sequence triggers a reset). This has already been > discussed in this thread. In my scheme, this directive will both, * define a new specific "inset"-directive (and the related counter), or * modify the attributes of an existing "inset"-directive. As it is a "meta-directive" defining|modifying another directive, I would like its name to reflect this: Suggestion: "define-inset" Alternatives: "set-inset", "set-sequence", "new-inset", "new-sequence". > 3. The resulting sequence can be specified independently, by one or > more new "formal" directives (perhaps "titled" and "captioned"; > specific names and functionality TBD). These will handle sequence > numbering and titles/captions. There will be two syntax alternatives, the long form:: .. inset:: Title or caption :class: inset-sub-class content or the shortcut:: .. inset-sub-class:: Title or caption content Some frequently used special cases should be pre-defined Class Name suggestion Comment ----- --------------- ------- Figure: figure-inset once backwards compatibility is solved, also "figure" Table: table-inset Examples:: .. inset:: Gnus and Gnats :class: figure .. image:: gnus.jpg .. inset:: Gnu population :class: table-inset Year Numbers ---- ------- 2004 3 2005 23 equivalent to:: .. table-inset:: Gnu population Year Numbers ---- ------- 2004 3 2005 23 .. define-inset:: example :prefix: Example :counter:`example`: .. example:: A classical example :: print "Hello world!" Thanks Guenter -- G.Milde web.de |
From: Felix W. <Fel...@gm...> - 2005-09-22 21:16:52
|
David Goodger wrote: > I propose the following: > > 1. The current directives (table, figure) should remain "informal": no > sequence numbering. They (and only they!) still handle table- and > figure-specific options. They may have titles/captions, but that > is orthogonal to numbering. > > 2. We implement a new directive, "sequence", [...] > > 3. The resulting sequence can be specified independently, by one or > more new "formal" directives (perhaps "titled" and "captioned"; > specific names and functionality TBD). These will handle sequence > numbering and titles/captions. I don't feel that these directives ("titled" and "captioned") are a viable approach. The problem is that (if I understand you correctly) to create a numbered, titled table, you'd have to write: .. titled:: [argument and/or options] :sequence: table [grid table goes here] The title feature exists twice then, once in the "titled" directive and once in the "table" directive. Also I don't think that the functionality of "titled" and "captioned" for titling/captioning an object suffices -- we'd have to add things like :width: or :align:, essentially replicating "figure" functionality. (You cannot sensibly nest an :align:ed "figure" inside a "captioned" directive, for example. The outer directive must have the :align: option, not the inner one.) -- For private mail please ensure that the header contains 'Felix Wiemann'. "the number of contributors [...] is strongly and inversely correlated with the number of hoops each project makes a contributing user go through." -- ESR |
From: David G. <go...@py...> - 2005-09-29 02:25:13
Attachments:
signature.asc
|
> David Goodger wrote: >> I propose the following: >> >> 1. The current directives (table, figure) should remain "informal": >> no sequence numbering. They (and only they!) still handle >> table- and figure-specific options. They may have >> titles/captions, but that is orthogonal to numbering. >> >> 2. We implement a new directive, "sequence", [...] >> >> 3. The resulting sequence can be specified independently, by one or >> more new "formal" directives (perhaps "titled" and "captioned"; >> specific names and functionality TBD). These will handle >> sequence numbering and titles/captions. [Felix Wiemann] > I don't feel that these directives ("titled" and "captioned") are a > viable approach. > > The problem is that (if I understand you correctly) to create a > numbered, titled table, you'd have to write: > > .. titled:: [argument and/or options] > :sequence: table > > [grid table goes here] > > The title feature exists twice then, once in the "titled" directive > and once in the "table" directive. What "table" directive? I don't see one in your example. Or are you talking about the abstract? I don't see any problem in having both directives accept a title. OK, scratch #1 above; let's let tables & figures optionally be formal. They represent the bulk of the formal cases anyhow. So the simplest way to create a numbered, titled table would be: .. table:: title :formal: [grid table here] And a figure: .. figure:: title :formal: .. image:: fig1.png Rather than "titled" and "captioned", we could have just one directive for generic formal objects: "formal". An example of full usage could be like this: .. sequence:: examples Example :counter:`examples`: :formal-title:`examples` (other stuff...) .. formal:: Logical ``AND`` :sequence: examples ===== ===== ======= a b a AND b ===== ===== ======= True True True True False False False True False False False False ===== ===== ======= The argument to the sequence directive is the sequence name. Its content is the title/caption pattern. The default would be titled (i.e., above), but the "sequence" directive would have a ":caption:" option to allow for that variation. > Also I don't think that the functionality of "titled" and > "captioned" for titling/captioning an object suffices -- we'd have > to add things like :width: or :align:, essentially replicating > "figure" functionality. The "formal" directive would take on the alignment, width, and other functionality. That's OK, because "figure" would simply become the equivalent of "formal:: ... :sequence: figures". > (You cannot sensibly nest an :align:ed "figure" inside a "captioned" > directive, for example. The outer directive must have the :align: > option, not the inner one.) Sure you could (... nest aligned objects; I don't know about "sensibly" though). The outer formal object could be aligned right, and a separate image or even a figure defined within it could be aligned left. The result may be silly, but it should be possible. Yes, the outer directive must have an :align: option, but there's no reason the inner directive can't have one too. -- David Goodger <http://python.net/~goodger> |
From: Alan G I. <ai...@am...> - 2005-08-27 16:36:58
|
On Sat, 27 Aug 2005, David Goodger apparently wrote: > If we generalize the "figure" directive as is being > discussed in the "figure that is not an image" thread, we > can (and should) generalize the "table" directive too. In LaTeX, tables and figures are specific examples of floats, which support numbering. Is this abstraction relevant to docutils? Alan Isaac |
From: David G. <go...@py...> - 2005-08-30 16:24:25
Attachments:
signature.asc
|
[Alan G Isaac] > 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. In Docutils, formal figures and tables and examples are all examples of sequences -- there's a sequence counter and title/caption embellishment associated. The "image as table" that Dima described is a prime example of how the "formal table" directive should support arbitrary content. It cannot be implemented as a "figure" because that would result in a "Figure 1." embellishment, and a caption instead of a title (tables have titles [above], and figures have captions [below]). -- David Goodger <http://python.net/~goodger> |
From: Alan G I. <ai...@am...> - 2005-08-31 15:57:37
|
On Tue, 30 Aug 2005, David Goodger apparently wrote: > Docutils doesn't care about floating-vs-stationary; that's > a back-end rendering issue. Tangetially: I would think "caring" would be required to the extent that a back-end may need to be able to designate some objects as floatable, so these need to have a structure that allows that. (I'm just trying to understand, but am not really asking for a response here.) > In Docutils, formal figures and tables and examples are > all examples of sequences -- there's a sequence counter > and title/caption embellishment associated. That answers my core question. Thanks, Alan |
From: Felix W. <Fel...@gm...> - 2005-09-03 22:32:53
|
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:: .. 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. > It cannot be implemented as a "figure" because that would result in a > "Figure 1." embellishment, Not when specifying ":sequence: table". > and a caption instead of a title (tables have titles [above], and > figures have captions [below]). 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, if you think that table titles should be rendered atop the table, maybe it's really a good idea to make :sequence: only an option of the "figure" directive. Or do you actually find such inconsistent rendering in academic documents? I've never seen it before. -- For private mail please ensure that the header contains 'Felix Wiemann'. "the number of contributors [...] is strongly and inversely correlated with the number of hoops each project makes a contributing user go through." -- ESR |
From: G. M. <g....@we...> - 2005-09-06 08:31:55
|
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 it quite often, and I am told to use it in my phd thesis. (The "right" placement of table captions is the matter of never-ending debates. However, it looks a lot more "normal", if you let the sequences float to the beginning or end of a page.) The KOMA latex classes (quite popular in Germany) provide the commands \captionabove and \captionbelow as well as the options "tablecaptionsabove" and "tablecaptionsbelow". IMHO, it should be up to the output style to decide where table captions are placed. BTW: whether it is above or below, the numbered explanatory block of text is always called a "caption" in LaTeX, as "\title" is reserved for the document title. Günter -- G.Milde web.de |
From: G. M. <g....@we...> - 2005-09-07 13:02:27
|
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. In LaTeX, the positioning of the float is given as either class option, global document option or optional argument. Something similar could be useful for docutils too (with different defaults for different output media). If you want the float to appear "here", give the right option (or choose the right stylesheet). If you do not want a numbered caption, do not use a float. ................. > 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. 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". Currently, the "table" directive provides for a title (caption) like the LaTeX float environment. Maybe one could keep .. table:: a table with a numbered title .. image:: image_of_a_table.png as a nicer looking shortcut to > .. figure:: another table with a numbered title > :sequence: table > > .. image:: image_of_a_table.png and grow the table-specific options in a "tabular" directive, e.g. .. table:: a table with a numbered title .. tabular:: :width: 15cm ===== ===== A not A ===== ===== False True True False ===== ===== Guenter -- G.Milde web.de |
From: David G. <go...@py...> - 2005-09-13 14:07:07
Attachments:
signature.asc
|
[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". That distinction is useful, but the names are unfortunate. We won't be using those names in Docutils. > Currently, the "table" directive provides for a title (caption) like > the LaTeX float environment. Maybe one could keep > > .. table:: a table with a numbered title > > .. image:: image_of_a_table.png > ... > > and grow the table-specific options in a "tabular" directive, e.g. > > .. table:: a table with a numbered title > > .. tabular:: > :width: 15cm > > ===== ===== > A not A > ===== ===== > False True > True False > ===== ===== I'd keep "table" as the directive for real tabular tables (the latter case), perhaps with an option ":formal:". 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 or .. formal:: title of formal object :sequence: table .. image:: image-of-a-table.png This provides a clean distinction. A formal table containing only a table (the most common case) requires only one directive. A formal table containing arbitrary content requires one directive for the formal object itself, and whatever is necessary for the content. -- David Goodger <http://python.net/~goodger> |
From: Felix W. <Fel...@gm...> - 2005-09-22 20:50:22
|
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. > perhaps with an option ":formal:". Yes, or something similar. > 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 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). > 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" directive instead of "formal"? The only difference is "title" vs. "caption". I think that creating yet another directive just for representing this distinction is overkill. Please have a look at the following ideas: * Regarding the **document model**, I suggest the following:: <figure [align="..."]> <title> Figure title. Figure contents. <caption> Figure caption iff there is no title. So a figure must have either a title or a caption. We could also make the "caption" node the first child of the figure node (instead of the last child), so that we maintain the invariant :: isinstance(figure[0], (nodes.caption, nodes.title)) That does not represent the visual appearance very well, but it might be more convenient. * Regarding the **reStructuredText syntax** I suggest (ignoring compatibility issues for the moment) that we use the "figure" directive to create figures using the following syntax: :Directive Arguments: One, required (figure title or caption). :Directive Options: Possible. ``:captioned:`` : flag (empty) The figure has a caption. (Default.) ``:titled:`` : flag (empty) The figure has a title. (Mutually exclusive with :captioned:.) ``:sequence:`` : string The sequence to use. Default: "figure" Plus more options like :width:, :height:, :align:, etc. Furthermore, the "table" directive should be usable for implicitly creating a figure, e.g. by passing the option ``:sequence: table``. We need a yet-to-be-decided way for automatically numbering all figures and/or titled tables. The table should inherit not only :sequence: but all or most other options from the "figure" directive. It should default to :titled: instead of :captioned:, though. For example, :: .. table:: A test table. :sequence: table :align: right [grid table here] would result in :: <figure align="right"> <title> A test table. <table> [grid table here] And if we want an image instead of a real table, we'd use this:: .. figure:: A test table. :sequence: table :titled: :align: right .. image:: table.png -- For private mail please ensure that the header contains 'Felix Wiemann'. "the number of contributors [...] is strongly and inversely correlated with the number of hoops each project makes a contributing user go through." -- ESR |
From: G. M. <g....@we...> - 2005-09-27 11:41:25
|
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 :Directive Arguments: One, required (figure title). > :Directive Options: Possible. > ``:title-position:`` : "top" or "bottom" Default: top > ``:sequence:`` : string > The sequence to use. Default: "figure" > > Plus more options like :width:, :height:, :align:, etc. The "table" directive should be usable for creating a "formal" table, e.g. by creating a figure element passing it the option ``:sequence: table``. The table should inherit all options from the "figure" directive. It should default to sequence="table" and title-position="top". For example, :: .. table:: A test table. :align: right [grid table here] would result in :: <figure align="right"> <title sequence="table"> A test table. <table> [grid table here] And if we want an image instead of a real table, we'd simply use :: .. table:: Bitmap of a table. :align: right .. image:: table.png to get :: <figure align="right"> <title sequence="table"> Bitmap of a table. <image url="file:table.png"> I.e. the ".. table::" directive does not produce a <table> object but a <figure> object with the defaults sequence="table" and title-position="top". Within this special <figure> object, the "real" table is nested: a "grid table", an image, a csv-table, or actually any other block object. Guenter -- G.Milde web.de |
From: David G. <go...@py...> - 2005-10-05 03:30:28
Attachments:
signature.asc
|
> 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 > but a <figure> object with the defaults sequence="table" and > title-position="top". No. Figures aren't tables, nor vice-versa. See my other reply today (to Felix). > Within this special <figure> object, the "real" table is nested: > a "grid table", an image, a csv-table, or actually any other > block object. Rather than a special "figure" object, let's have a dedicated object -- "formal", unless someone comes up with a better name. We already have "figure" and "table" elements, and I don't think we need to change them significantly. Just extending them a bit is enough. -- David Goodger <http://python.net/~goodger> |
From: G. M. <g....@we...> - 2005-10-05 14:55:31
|
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. IMHO, there is no need to introduce (or keep) a "caption" element. > > 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``. > ... > No. Figures aren't tables, nor vice-versa. See my other reply today > (to Felix). ... > Rather than a special "figure" object, let's have a dedicated object > -- "formal", unless someone comes up with a better name. Agreed. 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. Thanks Guenter -- G.Milde web.de |
From: Aahz <aa...@py...> - 2005-10-06 17:58:01
|
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 (aa...@py...) <*> http://www.pythoncraft.com/ The way to build large Python applications is to componentize and loosely-couple the hell out of everything. |
From: David G. <go...@py...> - 2005-10-05 10:12:31
Attachments:
signature.asc
|
> 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" > 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. > I think that creating yet another directive just for > representing this distinction is overkill. I don't. A formal figure is an instance of a formal object, not the other way around. > Please have a look at the following ideas: > > * Regarding the **document model**, I suggest the following:: > > <figure [align="..."]> > <title> > Figure title. > Figure contents. > <caption> > Figure caption iff there is no title. > > So a figure must have either a title or a caption. I don't like this approach because it overloads the "figure" element & directive. A figure is not an example, nor is it a listing, etc. > We could also make the "caption" node the first child of the > figure node (instead of the last child), so that we maintain the > invariant :: > > isinstance(figure[0], (nodes.caption, nodes.title)) > > That does not represent the visual appearance very well, but it > might be more convenient. That's a possibility (for a more generic "formal" element), although it really doesn't gain us much. This is an example of the tail wagging the dog... gently, but still. > * Regarding the **reStructuredText syntax** I suggest (ignoring > compatibility issues for the moment) that we use the "figure" > directive to create figures using the following syntax: > > :Directive Arguments: One, required (figure title or caption). > :Directive Options: Possible. > > ``:captioned:`` : flag (empty) > The figure has a caption. (Default.) > ``:titled:`` : flag (empty) > The figure has a title. (Mutually exclusive with > :captioned:.) The captioned/titled attribute is bound to the sequence. Specifying the position should not be part of each individual formal object, but should be specified when the sequence is defined. > ``:sequence:`` : string > The sequence to use. Default: "figure" Perhaps. I'd say that ":formal:" is more relevant to the "figure" directive though: is it a formally enumerated object or not? The sequence can either be an argument of the :formal: option or a separate option, if required. But I'm thinking that it probably isn't required; figures use the "figure" sequence, and that's all. > Plus more options like :width:, :height:, :align:, etc. Sure. Although I wonder how we can support a height option if there's arbitrary content. Perhaps only width and alignment. > Furthermore, the "table" directive should be usable for implicitly > creating a figure, e.g. by passing the option ``:sequence: > table``. Is there a mistake in that sentence? Passing ":sequence: table" is not implicit, it's explicit. It's probable I don't follow. > We need a yet-to-be-decided way for automatically numbering all > figures and/or titled tables. Why just titled tables? A table doesn't have to be titled to be formal. Rather, tables in "table" directives. In any case, that's a simple matter to be dealt with once the hard stuff is done. > The table should inherit not only :sequence: but all or most other > options from the "figure" directive. Yes. > It should default to :titled: instead of :captioned:, though. Yes, the table sequence should default to titled. > For example, :: > > .. table:: A test table. > :sequence: table > :align: right > > [grid table here] It's too roundabout and repetetive to require saying both ".. table::" and ":sequence: table". The "table" directive should imply the "table" sequence, for formal tables anyhow. The most we should require is a ":formal:" flag option. > would result in :: > > <figure align="right"> > <title> > A test table. > <table> > [grid table here] > > And if we want an image instead of a real table, we'd use this:: > > .. figure:: A test table. > :sequence: table > :titled: > :align: right > > .. image:: table.png Again, too roundabout and indirect. Much better to say: .. table:: A test table :formal: :align: right .. image:: table.png ********** I've been uncertain which goal is most important: wanting a simple, clean, orthogonal implementation; and keeping backwards compatibility; and achieving a practical compromise. Here's my current thinking: 1. The "figure" directive could be used for all captioned formal objects, and the "table" directive could be used for all titled formal objects (using :sequence: & possibly :formal: options). :Pros: We wouldn't need a new directive or doctree element. :Cons: - Sequences other than "figure" and "table" would be cumbersome. - "figure" and "table" would be overloaded; smells bad. - We want to keep some table-specific options (column widths, stub columns, etc.), that won't apply to any other type of formal object. 2. We could scrap all pretense to formality in the "figure" & "table" directives, and require the use of an outer wrapper directive for all formal objects. :Pros: Clean, orthogonal implementation. :Cons: - Inconvenient; most cases of formal objects will be tables & figures, requiring extra directives. - Introduces a new directive & doctree element. 3. We could implement a hybrid system, where there is a "formal" directive for non-figures & -tables, but figures & tables themselves can be formal. :Pros: Most convenient alternative. :Cons: Introduces a new directive & doctree element. If people have alternate ideas, please summarize them like the above. I like option 3 the best. I don't consider introducing a new directive & doctree element to be much of a con. Here's a summary of the changes it would entail: ===================== ================================================== figure ------------------------------------------------------------------------- Current content model (image, ((caption, legend?) | legend)) New content model ((%body.elements;)+, caption?) New attributes formal Sequence "figure" (predefined, invariant) Caption pattern "Figure :counter:`figure`: :formal-title:`figure`" table ------------------------------------------------------------------------- Current content model (title?, tgroup+) > New content model (title?, (tgroup+ | (%body.elements;)+)) New attributes formal Sequence "table" (predefined, invariant) Title pattern "Table :counter:`table`: :formal-title:`table`" formal ------------------------------------------------------------------------- Current content model none (new element) New content model ( (title, (%body.elements;)+) | ((%body.elements;)+, caption?) ) Attributes sequence (which could be transferred to a "class" attribute value by writers) Sequence any (must already exist) Title/caption pattern defined with "sequence" directive ===================== ================================================== The "figure" and "table" elements, *with ":formal:" options*, can be thought of as specific instances of the generic "formal" element with pre-defined title/caption patterns. The "sequence" directive could be used to redefine the patterns though. I'm not sure about the content model of the "formal" element. A single "title" would probably suffice, rather than "title" or "caption" depending on the sequence. Any difficulty writers would have rearranging child nodes would probably be more than compensated by the simpler, more deterministic model. Here's an example of the "formal" directive: .. formal:: ********** It's conceivable that just as the "role" directive creates new role handlers (callables), a "sequence" directive could create new specialized directive handlers, and thus, new directives. These new directives would be convenient aliases for the generic "formal" directive, with implicit sequences. Here's a simple example of a "listing": .. sequence:: listing :title: Listing :counter:`example`: :formal-title:`example` .. example:: The "for" loop .. parsed-literal:: for *name* in *sequence or iterator*: *suite* [else: *suite*] This would be very handy since documents with custom formal object sequences will probably have many formal objects. The name of the directive could be derived implicitly from the sequence name, or specified explicitly with a :directive: option. Directive name conflicts would be possible; I don't know whether to simply ignore them (allow user-defined sequence directives to overwrite built-in ones) or to flag an error. Perhaps flag an INFO-level system message; then they can be ignored at users' discretion. ********** 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. -- David Goodger <http://python.net/~goodger> |
From: Aahz <aa...@py...> - 2005-10-08 23:22:09
|
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 (aa...@py...) <*> http://www.pythoncraft.com/ "If you think it's expensive to hire a professional to do the job, wait until you hire an amateur." --Red Adair |
From: David G. <go...@py...> - 2005-09-09 12:56:48
Attachments:
signature.asc
|
[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". It would still get the figure-style embellishment. Otherwise, it *would* be a mess. > I'm still not sure if it's a good idea to have non-uniform > captioning (above and below). I am. Proclamation: Docutils will have flexible positioning of formal objects' titles (above) and captions (below). > Would there be anything wrong with *always* rendering > captions/titles below the figure/table? Yes: captions go below, titles go above. In most academic documents I've seen, figures are captioned, and tables are titled. There are variations. Simply put, we should not be dictating style to the author. > Or, if you think that table titles should be rendered atop the > table, maybe it's really a good idea to make :sequence: only an > option of the "figure" directive. Or do you actually find such > inconsistent rendering in academic documents? It's not "inconsistent". Please avoid such biased language. Tables are textual and are read from the top down, so it makes sense to always put the title at the top. Figures are usually graphical and are seen at a glance; it may not matter whether they are titled or captioned. But graphs, for example, are read from the bottom up! It's sensibler to caption such figures. > I've never seen it before. Perhaps it's different in Germany, but in Canada & the US, in my experience, it's the norm. -- David Goodger <http://python.net/~goodger> |