From: Martin B. <mar...@gm...> - 2005-07-16 14:07:33
|
Hello Is it possible to create a figure that does not consist of an image? =20 For example, can I create a literal block with code but that gets parsed as a figure, with numbering? Hmm, I just noticed... the figures don't seem to have automatic numbering either (like in LaTeX). cheers, |
From: Felix W. <Fel...@gm...> - 2005-07-17 22:39:05
|
Martin Blais wrote: > Is it possible to create a figure that does not consist of an image? Not currently. The document model allows that *almost* (just a change to the DTD and probably to the writers). In my opinion the current syntax of the figure directive is overly specific to images and too complicated (width and figwidth, etc.); and it's too much duplication with the image directive. The document model looks pleasantly generic, though. :-) I propose the following new syntax for a figure directive [1]_: * If there is an argument to the figure directive, use the current syntax, but raise a deprecation warning. * If there is no argument to the figure directive, create a figure node and insert the directive contents into the figure node. Recognize the following options: :width: Figure width (as opposed to :figwidth: before). :class: Figure class (as opposed to :figclass: before). :align: Figure alignment. :caption: Figure caption. The caption node, if the caption option is given, is inserted as the last child of the figure node. No support for a legend is added. I've never seen a legend below the caption in a real figure. I.e., the legend is always part of the figure contents. .. [1] David, please handle this with low priority; the todo branch is more important at the moment because I want to add items without causing conflicts. > with numbering? Hmm, I just noticed... the figures don't seem to have > automatic numbering either (like in LaTeX). No, sorry. It's on the to-do list; see <http://docutils.sf.net/docs/dev/todo.html#object-numbering-and-object-references>. I think a generic figure directive could be a first step into the right direction. Since ``figure`` is the only element that supports captions at the moment and you can only place numbers inside a caption, we might only have to implement numbering for figures. So this :: .. figure:: :name: test figure <--- This causes numbering. :caption: This is a test figure. Figure contents. would be rendered like this:: Figure contents. Figure 1: This is a test figure. Numbering tables would mean nesting the table inside a figure:: .. figure:: :name: some table :caption: A test table. +----------+ | A table. | +----------+ Rendered as:: +----------+ | A table. | +----------+ Figure 2: A test table. We might end up with nested directives here, but I think it's worth the genericness. After all, we might want to mix directives and text in one figure, or have multiple images inside one figure. * Make :caption: mandatory for numbered figures? * Besides i18n, what if the user wants to use a different term than "Figure", e.g. "Image", "Table", or "Diagram"? * We could defer this issue and add support for it later. * We could also add a special "figname" role to be used only inside figures:: .. figure:: :caption: <--- This has become a boolean option. +----------+ | A table. | +----------+ This paragraph is part of the figure. The following paragraph is automatically recognized as the caption of the figure: Table :figname:`some table`: A test table. The caption is "Table 1: A test table." and it can be referenced as "table :figref:`some table`". Recognizing the last paragraph is a bit magical, but OTOH it's less complex than the other examples above (e.g. no i18n required), and it's more WYSIWYG. -- 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: Alan G I. <ai...@am...> - 2005-07-17 23:07:04
|
On Mon, 18 Jul 2005, Felix Wiemann apparently wrote:=20 > Since ``figure`` is the only element that supports=20 > captions at the moment and you can only place numbers=20 > inside a caption, we might only have to implement=20 > numbering for figures.=20 It seems like a "figure" will become more like the idea of a "float" in LaTeX, in which case it will be nice and natural for there to be different kinds (e.g., LaTeX tables and LaTeX figures) each numbered separated. If caption is necessary for numbering (seems reasonable), then it should be allowed to be empty. Cheers, Alan Isaac |
From: David G. <go...@py...> - 2005-07-29 00:41:36
Attachments:
signature.asc
|
(catching up on backlogged email -- sorry for the delay) [Martin Blais] >> Is it possible to create a figure that does not consist of an image? [Felix Wiemann] > Not currently. > > The document model allows that *almost* (just a change to the DTD > and probably to the writers). > > In my opinion the current syntax of the figure directive is overly > specific to images and too complicated (width and figwidth, etc.); > and it's too much duplication with the image directive. No wonder... the "figure" code calls "image" to do most of its work! > The document model looks pleasantly generic, though. :-) > > I propose the following new syntax for a figure directive [1]_: > > * If there is an argument to the figure directive, use the current > syntax, but raise a deprecation warning. > > * If there is no argument to the figure directive, create a figure > node and insert the directive contents into the figure node. > Recognize the following options: > > :width: Figure width (as opposed to :figwidth: before). > :class: Figure class (as opposed to :figclass: before). > :align: Figure alignment. > :caption: Figure caption. > > The caption node, if the caption option is given, is inserted as > the last child of the figure node. I think the ideal syntax would be: .. figure:: [caption] [options] content The caption and options are all optional. The blank line before the content is required. > No support for a legend is added. I've never seen a legend below > the caption in a real figure. I.e., the legend is always part of > the figure contents. That sounds fine to me. The content model would look like this: <!ELEMENT figure (caption?, (%body.elements;)+) > I think the caption is better up front, as a title equivalent. Heck, we could even use the "title" element. Writers can re-order the elements such that the caption comes after the content. >> with numbering? Hmm, I just noticed... the figures don't seem to >> have automatic numbering either (like in LaTeX). > > No, sorry. It's on the to-do list; see > <http://docutils.sf.net/docs/dev/todo.html#object-numbering-and-object-references>. > > I think a generic figure directive could be a first step into the > right direction. Since ``figure`` is the only element that supports > captions at the moment Tables can have a title, which is just like a caption (except before the table). > and you can only place numbers inside a caption, ? Not following you. > we might only have to implement numbering for figures. > > So this :: > > .. figure:: > :name: test figure <--- This causes numbering. > :caption: This is a test figure. > > Figure contents. > > would be rendered like this:: > > Figure contents. > > Figure 1: This is a test figure. I don't think the figure name should cause numbering. The name should just be a name, to refer to. Instead, an explicit option should cause numbering, such as ":numbered:" and/or ":sequence: name" (which implies ":numbered:"; the name allows for multiple independent sequences). Without a ":name:" option, the default name of a figure should be taken from its caption. > Numbering tables would mean nesting the table inside a figure:: There's a table directive which should also allow numbering & sequences. Formal documents often have independent "figure" and "table" sequences. Of course, a figure's content may be a table. > We might end up with nested directives here, but I think it's worth > the genericness. After all, we might want to mix directives and > text in one figure, or have multiple images inside one figure. Yes, nested directives are not a problem. > * Make :caption: mandatory for numbered figures? No. In any case, "mandatory options" is an oxymoron! > * Besides i18n, what if the user wants to use a different term than > "Figure", e.g. "Image", "Table", or "Diagram"? I think providing two directives, "figure" and "table", will suffice for most users. For example, a new "sequence" directive could be added for user-defined a terms or patterns, and "figure" could be extended to support it. For example:: .. sequence:: diagram :pattern: Diagram #. "sequence" could also allow for arbitrary initial values, enumerations (1/a/A/i/I), and relationships (figure sequence depends on chapter sequence, restarting at 1 whenever chapter changes, and rendered as <chapter>.<figure>). > * We could defer this issue and add support for it later. Yes. > * We could also add a special "figname" role to be used only > inside figures:: ... > The caption is "Table 1: A test table." No, too much magic. > and it can be referenced as "table :figref:`some table`". That's fine though. -- David Goodger <http://python.net/~goodger> |
From: G. M. <g....@we...> - 2005-07-29 08:10:10
|
On 28.07.05, David Goodger wrote: > [Martin Blais] > >> Is it possible to create a figure that does not consist of an image? > I don't think the figure name should cause numbering. The name should > just be a name, to refer to. Instead, an explicit option should cause > numbering, such as ":numbered:" and/or ":sequence: name" (which > implies ":numbered:"; the name allows for multiple independent > sequences). I would propose an auto-numbering similar to the foonotes, e.g. with .. figure:: Figure #: auto-numbered figure [options] content the caption label is "Figure" and auto-numbering is on. > > * Besides i18n, what if the user wants to use a different term than > > "Figure", e.g. "Image", "Table", or "Diagram"? > > I think providing two directives, "figure" and "table", will suffice > for most users. For example, a new "sequence" directive could be > added for user-defined a terms or patterns, and "figure" could be > extended to support it. For example:: > > .. sequence:: diagram > :pattern: Diagram #. > "sequence" could also allow for arbitrary initial values, enumerations > (1/a/A/i/I), and relationships (figure sequence depends on chapter > sequence, restarting at 1 whenever chapter changes, and rendered as > <chapter>.<figure>). So, "figure" and "table" would become special cases of "sequence"? Another option would be to use "figure" as generic 'sequence directive' (with "table" as special case). :pattern: defaults to "Figure #." Every different :pattern: starts a separate counter. Combined with my above proposal this becomes:: .. figure:: Diagram #: auto-numbered diagramm .. image:: diagram.eps The syntax for the pattern specification needs carefull consideration. Some thoughts:: .. figure:: Figure #: title + simple + close to appearance in the output ? should the colon be part of :pattern:? .. figure:: Figure #. title + close to appearance in the output - maybe ambiguous (Where does the :pattern: end and the title start?) .. figure:: Figure #.: title + explicit - ugly .. figure:: [Figure #.] title + explicit + precedence case: optional labels in LaTeX - square brackets are hard to type on German keyboards .. figure:: title + standard rst directive syntax :pattern: Figure #. - does not resemble final appearance Sincerely Guenter -- G.Milde web.de |
From: Alan G I. <ai...@am...> - 2005-07-29 16:06:56
|
On Fri, 29 Jul 2005, "G. Milde" apparently wrote: > "figure" and "table" would become special cases of "sequence"? This sounds useful to me, and it reminds me of LaTeX where figure and table are special kinds of 'float'. For example, I often have figures, tables, and "listings" in a single document, and I want them all numbered separately. Cheers, Alan Isaac |
From: David G. <go...@py...> - 2005-07-30 02:31:40
Attachments:
signature.asc
|
[Guenter Milde] > I would propose an auto-numbering similar to the foonotes, e.g. with > > .. figure:: Figure #: auto-numbered figure > [options] > > content > > the caption label is "Figure" and auto-numbering is on. Yes, except the "Figure #: " part would be auto-generated. > So, "figure" and "table" would become special cases of "sequence"? Yes, sort of. The "figure" and "table" directives would use implicit pre-defined sequences, unless an explicitly named sequence is given. > Another option would be to use "figure" as generic 'sequence > directive' (with "table" as special case). The "sequence" directive would define a named sequence, nothing more. Specifically, it wouldn't generate any doctree elements. The "sequence" directive is *not* a generic form of the "figure" and "table" directives. > :pattern: defaults to "Figure #." Every different :pattern: > starts a separate counter. > > Combined with my above proposal this becomes:: > > .. figure:: Diagram #: auto-numbered diagramm > > .. image:: diagram.eps Too verbose (repetition required), fragile (a misspelled caption would start a new sequence), and implicit/magic (caption parsing required) for my taste. > .. figure:: title + standard rst directive syntax > :pattern: Figure #. - does not resemble final appearance This last example is the closest to what I envisage, although I would not put the pattern directive in the figure directive. And actually, it *does* resemble the final appearance: ".. figure:: title" looks a lot like "Figure 1. title". Here are some concrete examples of what I'd like to see: .. figure:: Caption .. image:: figure.png This results in "Figure 1. Caption". The sequence and pattern are implicit and pre-defined. .. sequence:: screenshot :pattern: Screenshot ${value}. $title .. figure:: Input dialog :sequence: screenshot .. image:: input.png Here, the ":pattern:" value uses string.Template syntax (new in Python 2.4). The explicit ":sequence:" specified in the "figure" directive overrides the default implicit sequence and pattern. -- David Goodger <http://python.net/~goodger> |
From: Felix W. <Fel...@gm...> - 2005-08-15 21:11:01
|
David Goodger wrote: > .. sequence:: screenshot > :pattern: Screenshot ${value}. $title > > .. figure:: Input dialog > :sequence: screenshot > > .. image:: input.png I'm not sure if we need $title (or call it "$caption"?) in the sequence definition. Maybe we can assume that the title always follows the name. And the caption ("Input dialog") would have to be moved to a separate option for compatibility. How do we refer to the number then? Should the "sequence" directive automatically create a role ("screenshot" in this case)? -- 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-16 00:47:17
Attachments:
signature.asc
|
> David Goodger wrote: >> .. sequence:: screenshot >> :pattern: Screenshot ${value}. $title >> >> .. figure:: Input dialog >> :sequence: screenshot >> >> .. image:: input.png [Felix Wiemann] > I'm not sure if we need $title (or call it "$caption"?) in the > sequence definition. Maybe we can assume that the title always > follows the name. Sure. > And the caption ("Input dialog") would have to be moved to a > separate option for compatibility. Being debated elsewhere. > How do we refer to the number then? Should the "sequence" directive > automatically create a role ("screenshot" in this case)? No. Refer to it by name. Use :figref:`Input dialog` or something. -- David Goodger <http://python.net/~goodger> |
From: Dima D. <dim...@gm...> - 2005-08-18 17:09:39
|
Hello list: On 8/16/05, David Goodger <go...@py...> wrote: [...] > No. Refer to it by name. Use :figref:`Input dialog` or something. This snippet reminded me of a use case I need and would like to know if is possible to accomplish in the current version or is to be expected in the future. Can I cross-reference (numbered) figures and tables implicitly, like with headings? Internal hyperlinks are the closest thing I found in the docs, but I am mostly worried about conversion to PDF, so the reference should be replaced with something like "Figure #.#". Cheers, --=20 /dima |
From: Felix W. <Fel...@gm...> - 2005-08-18 16:38:43
|
Dima Diall wrote: > David Goodger wrote: > >> No. Refer to it by name. Use :figref:`Input dialog` or something. > > This snippet reminded me of a use case I need and would like to know > if is possible to accomplish in the current version or is to be > expected in the future. Can I cross-reference (numbered) figures and > tables implicitly, like with headings? No, not currently. > Internal hyperlinks are the closest thing I found in the docs, but I > am mostly worried about conversion to PDF, so the reference should be > replaced with something like "Figure #.#". That's exactly what the :figref: role will be used for. You'd type something like :: See figure :figref:`figure name`. and get :: See figure 4. -- Felix Wiemann -- http://www.ososo.de/ |
From: Dima D. <dim...@gm...> - 2005-08-22 15:26:30
|
On 17/08/05, Felix Wiemann <Fel...@gm...> wrote: [...] > That's exactly what the :figref: role will be used for. You'd type > something like :: >=20 > See figure :figref:`figure name`. >=20 > and get :: >=20 > See figure 4. =20 Any ideas about when this might become reality? Would a markup option be available to refer to the figure's or table's page number, too? And, btw, how about all this for chapter/section cross-references (I am aware of the implicit hyperlink target trick). --=20 /dima |
From: David G. <go...@py...> - 2005-08-22 22:56:23
Attachments:
signature.asc
|
[Dima Diall] > Any ideas about when this might become reality? It's on the to-do list, but there's no schedule. It will be done when someone who needs it, implements it. > Would a markup option be available to refer to the figure's or table's > page number, too? That depends on the back-end. Docutils doesn't know anything about pages. For HTML, it doesn't make sense. For LaTeX, it's possible, but may not be easy to implement. > And, btw, how about all this for chapter/section > cross-references (I am aware of the implicit hyperlink target trick). Yes, they're noted too. See http://docutils.sf.net/docs/dev/todo.html#object-numbering-and-object-references -- David Goodger <http://python.net/~goodger> |
From: Mikolaj M. <mi...@wp...> - 2005-08-23 11:14:06
|
David Goodger scripsit: > This is an OpenPGP/MIME signed message (RFC 2440 and 3156) > --------------enig2D95FFF59B43F917ED66EA56 > Content-Type: text/plain; charset=ISO-8859-1 > Content-Transfer-Encoding: 7bit > > [Dima Diall] >> Any ideas about when this might become reality? > > It's on the to-do list, but there's no schedule. It will be done when > someone who needs it, implements it. > >> Would a markup option be available to refer to the figure's or table's >> page number, too? > > That depends on the back-end. Docutils doesn't know anything about pages. > For HTML, it doesn't make sense. For LaTeX, it's possible, but may not be > easy to implement. It is very easy. Expand :figref:`asdf` to \pageref{asdf}, not \ref{asdf} (or combine both of them). 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-15 20:49:48
|
David Goodger wrote: > I think the ideal syntax would be: > > .. figure:: [caption] > [options] > > content Specifying the caption as the directive argument is not possible. That would break compatibility to the current syntax. We must keep the current behavior when an argument is specified. So we'll have to move the caption to a separate :caption: option. I'm not entirely sure what we should do about the current behavior with an image URI as directive argument. Maybe place a "deprecated" note in the docs, later also deprecate by issuing a warning, and again later remove the feature? Not sure... > The content model would look like this: > > <!ELEMENT figure (caption?, (%body.elements;)+) > > > I think the caption is better up front, as a title equivalent. Heck, > we could even use the "title" element. I think we should either use "caption" as last element or "title" as first element. I'd rather vote on keeping "caption". A caption is still a bit different from a title. So the content model would be this: <!ELEMENT figure ((%body.elements;)+, caption?) > >> I think a generic figure directive could be a first step into the >> right direction. Since ``figure`` is the only element that supports >> captions at the moment > > Tables can have a title, which is just like a caption (except before > the table). That's different, I think. I can imagine use cases where a table has both a title and a caption. (In terms of Docutils' document model, this could become a table [with title] inside a figure [with caption].) >> and you can only place numbers inside a caption, > > ? Not following you. If you want to (auto-)number an object, you have to place the number in its caption. There's no other reasonable place to put a number. -- 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-15 23:58:13
Attachments:
signature.asc
|
[Felix Wiemann] > David Goodger wrote: >> I think the ideal syntax would be: >> >> .. figure:: [caption] >> [options] >> >> content > > Specifying the caption as the directive argument is not possible. > That would break compatibility to the current syntax. Note I wrote "the *ideal* syntax". I know it's not backwards-compatible. But if the reason is good enough, we can break backwards compatibility (with deprecation warnings & sufficient time). > We must keep the current behavior when an argument is specified. Not at the expense of something as butt-ugly as the alternative. > So we'll have to move the caption to a separate :caption: option. Yuck. Since the caption is such a commonly needed feature, and there's no other general-purpose use for the argument, they're a natural fit. Besides, in this case: .. figure:: picture.png :caption: My picture .. image:: another.png What's the order of the images & caption? Specifying the caption in the middle is inelegant. (And yes, I know that the current syntax does this. It's inelegant too!-) > I'm not entirely sure what we should do about the current behavior > with an image URI as directive argument. Deprecate & remove. It was a mistake. >>> I think a generic figure directive could be a first step into the >>> right direction. Since ``figure`` is the only element that >>> supports captions at the moment >> >> Tables can have a title, which is just like a caption (except >> before the table). > > That's different, I think. The only differences are the position of the title vs. the caption, and the sequence used. > I can imagine use cases where a table has both a title and a > caption. (In terms of Docutils' document model, this could become a > table [with title] inside a figure [with caption].) You've just invalidated your own argument ;-) -- David Goodger <http://python.net/~goodger> |
From: Felix W. <Fel...@gm...> - 2005-08-16 20:16:03
|
David Goodger wrote: > Felix Wiemann wrote: > >> David Goodger wrote: >> >>> I think the ideal syntax would be: >>> >>> .. figure:: [caption] >>> [options] >>> >>> content >> >> Specifying the caption as the directive argument is not possible. >> That would break compatibility to the current syntax. > > Note I wrote "the *ideal* syntax". I know it's not > backwards-compatible. But if the reason is good enough, we can break > backwards compatibility (with deprecation warnings & sufficient time). I don't think we necessarily have to break backwards compatibility. We can "branch" the syntax: * **With argument**, use exactly the current syntax. * **Without argument**, use the new syntax. Some options can have a different meaning, e.g. :width: should probably specify the figure width, and :figwidth: shouldn't exist. Furthermore, the directive contents aren't interpreted as caption and legend but as figure contents. In the documentation, the current syntax (with argument) should probably be documented inside a footnote, with a deprecation note, so as not to confuse the reader. So the following example wouldn't work at all because it mixes old and new syntax: > .. figure:: picture.png > :caption: My picture > > .. image:: another.png >> I'm not entirely sure what we should do about the current behavior >> with an image URI as directive argument. > > Deprecate & remove. It was a mistake. Why? The two syntax variants can co-exist. >>>> I think a generic figure directive could be a first step into the >>>> right direction. Since ``figure`` is the only element that >>>> supports captions at the moment >>> >>> Tables can have a title, which is just like a caption (except >>> before the table). >> >> That's different, I think. > > The only differences are the position of the title vs. the caption, > and the sequence used. My point is: Tables shouldn't support sequences because a table title shouldn't contain a table's number. The title is a different thing than the caption. If you want a numbered table, do as with any other object, put it into a figure:: .. figure:: :caption: Some table :sequence: table +----------+----------+ |The |table | +----------+----------+ |goes |here. | +----------+----------+ -- 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-19 01:25:54
Attachments:
signature.asc
|
[Felix Wiemann] [Felix Wiemann] > I don't think we necessarily have to break backwards compatibility. > > We can "branch" the syntax: > > * **With argument**, use exactly the current syntax. > > * **Without argument**, use the new syntax. Too complicated. The result would be a mess. For one thing, the existing directive handling code can't handle such variants, and I don't want it to. Again, it would be the tail wagging the dog. We can either break backwards compatibility completely, or introduce a new directive, but overloading the syntax like that won't work. We could perhaps introduce an equivalent of Python's "from __future__ import" trick. First, write a new directive, like "newfigure". Then a "use-new-figures" directive could have the effect of replacing the "figure" directive function with "newfigure". > Some options can have a different meaning, e.g. :width: should > probably specify the figure width, and :figwidth: shouldn't exist. Once "figure" doesn't imply "image" but requires an "image" directive as contents, the options become orthogonal. So yes, :figwidth: etc will go away. > The two syntax variants can co-exist. Perhaps they can, but they **should not**. It would complicate things enormously. For one thing, look at the directive code. You'd have to allow for all possible options, and deal with it in a spaghetti mess. No thanks. > My point is: Tables shouldn't support sequences There are plenty of documents which number their tables. > because a table title shouldn't contain a table's number. Why not? Of course it can. Look at any academic document and you're likely to find examples like this: Table 1. Table title text here +----------+----------+ |The |table | +----------+----------+ |goes |here. | +----------+----------+ > The title is a different thing than the caption. The only difference is the position. Titles come before the object, captions come after. That's **all**! > If you want a numbered table, do as with any other object, put it > into a figure:: > > .. figure:: > :caption: Some table > :sequence: table > > +----------+----------+ > |The |table | > +----------+----------+ > |goes |here. | > +----------+----------+ Why make things so complicated? -- David Goodger <http://python.net/~goodger> |
From: Felix W. <Fel...@gm...> - 2005-08-26 21:05:11
|
David Goodger wrote: > Felix Wiemann wrote: > >> I don't think we necessarily have to break backwards compatibility. >> >> We can "branch" the syntax: > > Too complicated. The result would be a mess. Then we'll have to break things... Maybe we can, however, still accept an argument (though issuing a warning) and insert an image. > We can either break backwards compatibility completely, or introduce a > new directive, I thought about that, but I have no idea for a name. "fig" won't work because it isn't properly internationalizable. > We could perhaps introduce an equivalent of Python's "from __future__ > import" trick. First, write a new directive, like "newfigure". Then > a "use-new-figures" directive could have the effect of replacing the > "figure" directive function with "newfigure". Now this is too complicated to *me* because it means juggling with different directive names, and adding a __future__-like thing. >> My point is: Tables shouldn't support sequences because a table title >> shouldn't contain a table's number. > > Why not? Of course it can. Look at any academic document and you're > likely to find examples like this: Since I'm not even an undergraduate, I'm just gonna believe this now. ;-) So we number tables as well. I just had another idea popping into my mind: The "sequence" directive would contain a :pattern: option which would need to be internationalized at least for the built-in sequences (e.g. "figure"). Also, several directives ("figure", "table", maybe more?) need to support sequences in different places (caption, title). That's all a bit complicated. Maybe it would be simpler to use a pattern-less "counter" role which just inserts a number and advances the counter. .. figure:: :caption: Figure :counter:`figure name`: A biohazard. ... contents ... See figure :counter-reference:`figure name` for details. (Equivalent: See :cref:`figure name` for details.) This would make the :counter: role parallel to the :cref: role, i.e., they have the same syntax. To add new counters, create a new role: .. role:: figure(counter) .. role:: table(counter) Maybe those two could be built in for convenience. The naming may need improvement (maybe call it "number" instead of "counter", etc.), but I think that this realization of auto-numbering has several advantages: * Parallel syntax (:counter:`figure name`, :cref:`figure name`). * No cluttering of directive code -- the :counter: directive can be used anywhere. That seems more orthogonal. * No internationalization required. The only disadvantage is that the name of the sequence (e.g. "Figure") has to be spelled out explicitly in the figure caption. Comments? -- 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-13 14:07:08
Attachments:
signature.asc
|
I suggest the following: 1. Rename the existing "figure" directive to "old-figure", which uses the old syntax, with no warnings. 2. Create a new directive "new-figure", with the new syntax (caption as directive argument, arbitrary contents). 3. Create a new "figure" directive, a wrapper that checks the syntax. For old syntax, it issues a deprecation warning and passes control to "old-figure". For new syntax, it passes control to "new-figure". 4. At some point in the future (0.5 or 0.6 or past a certain date), remove the wrapper from #3 and alias "figure" to "new-figure". Leave "old-figure" alone. [Felix Wiemann] > I just had another idea popping into my mind: > > The "sequence" directive would contain a :pattern: option which > would need to be internationalized at least for the built-in > sequences (e.g. "figure"). Also, several directives ("figure", > "table", maybe more?) need to support sequences in different places > (caption, title). That's all a bit complicated. > > Maybe it would be simpler to use a pattern-less "counter" role which > just inserts a number and advances the counter. The :counter: role idea is good, but not in each and every formal object. That's too much overhead. We could implement it such that it has a special interpretation within the sequence definition itself: .. sequence:: examples :prefix: Example :counter:`examples`: I'm using the :prefix: option for text to add before the caption text. We could also have a :suffix: option for text to add after the caption text, but that may be over-engineering at this point. I wouldn't put the "advance the counter" functionality in the counter role: .. sequence:: listings :prefix: Listing :counter:`chapters`.:counter:`examples`: The sequence-advancing functionality should be in the formal object itself. Otherwise, in the example above, the "chapters" sequence would advance every time there was a listing! The "sequence" directive could be made such that the default interpreted text role **in its context** is :counter:. Then we'd have: .. sequence:: listings :prefix: Listing `chapters`.`examples`: > .. figure:: > :caption: Figure :counter:`figure name`: A biohazard. > > ... contents ... > > See figure :counter-reference:`figure name` for details. > > (Equivalent: See :cref:`figure name` for details.) > > This would make the :counter: role parallel to the :cref: role, > i.e., they have the same syntax. Since the :counter: role could have a different interpretation inside a "sequence" directive than outside, we could also use :counter: instead of :counter-reference:/:cref:. > To add new counters, create a new role: > > .. role:: figure(counter) > .. role:: table(counter) I'd rather that new counters be created as a direct result of the "sequence" directive. > Maybe those two could be built in for convenience. Yes, those two sequences would be built-in. > The naming may need improvement (maybe call it "number" instead of > "counter", etc.), but I think that this realization of > auto-numbering has several advantages: > > * Parallel syntax (:counter:`figure name`, :cref:`figure name`). > > * No cluttering of directive code -- the :counter: directive can be > used anywhere. That seems more orthogonal. Hmm. Is that an argument against using :counter: in both contexts? I suppose it is possible for a formal object *caption* to contain a counter reference. But I can't imagine a *sequence definition* (i.e., :prefix: option) needing a counter reference. > * No internationalization required. > > The only disadvantage is that the name of the sequence > (e.g. "Figure") has to be spelled out explicitly in the figure > caption. That's a big disadvantage. The overhead of having to write Figure :counter:`figures`: caption text is too much. We'll require the internationalization. -- David Goodger <http://python.net/~goodger> |
From: Felix W. <Fel...@gm...> - 2005-09-18 14:56:00
|
David Goodger wrote: > I suggest the following: > > 1. Rename the existing "figure" directive to "old-figure", which uses > the old syntax, with no warnings. > > 2. Create a new directive "new-figure", with the new syntax (caption > as directive argument, arbitrary contents). > > 3. Create a new "figure" directive, a wrapper that checks the syntax. Are you suggesting "argument -> old-figure, no argument -> new-figure"? Or some more elaborate image-URI recognition logic (period followed by non-whitespace [as in "image.png"] -> old-figure)? In the former case, we'd have to support the caption for the new figure both as directive argument (with "new-figure") and as :caption: option (with "figure"). That's a little complicated. The latter case is inherently complicated. > For old syntax, it issues a deprecation warning and passes control > to "old-figure". For new syntax, it passes control to "new-figure". > > 4. At some point in the future (0.5 or 0.6 or past a certain date), > remove the wrapper from #3 and alias "figure" to "new-figure". > Leave "old-figure" alone. The problem with leaving "old-figure" alone is that this complicates the document tree because we'd have to keep the "legend" element. I'd like to drop the legend element at some point though. I'm still not entirely content with the solution, but I assume it will improve in the course of this discussion. > The :counter: role idea is good, but not in each and every formal > object. That's too much overhead. We could implement it such that it > has a special interpretation within the sequence definition itself: > > .. sequence:: examples > :prefix: Example :counter:`examples`: Looks good. > I wouldn't put the "advance the counter" functionality in the counter > role: Agreed. > The "sequence" directive could be made such that the default > interpreted text role **in its context** is :counter:. > > .. sequence:: listings > :prefix: Listing `chapters`.`examples`: Yup. > Since the :counter: role could have a different interpretation inside > a "sequence" directive than outside, we could also use :counter: > instead of :counter-reference:/:cref:. This is not entirely clean because it means that the :counter: role would have similar-looking yet different semantics inside and outside a sequence directive: * Inside: :counter:`name-of-sequence` * Outside: :counter:`name-of-numbered-object` But I don't see a better solution, so I'm fine with that for now. -- 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-18 16:19:17
Attachments:
signature.asc
|
> David Goodger wrote: >> I suggest the following: >> >> 1. Rename the existing "figure" directive to "old-figure", which uses >> the old syntax, with no warnings. >> >> 2. Create a new directive "new-figure", with the new syntax (caption >> as directive argument, arbitrary contents). >> >> 3. Create a new "figure" directive, a wrapper that checks the syntax. [Felix Wiemann] > Are you suggesting "argument -> old-figure, no argument -> > new-figure"? No. Argument is image-URI => old-figure; argument is caption => new-figure. > Or some more elaborate image-URI recognition logic (period followed > by non-whitespace [as in "image.png"] -> old-figure)? Yes. There are other clues available though, like the directive options used, and captions containing whitespace. > The latter case is inherently complicated. Yes, but that's the price that must be paid. >> For old syntax, it issues a deprecation warning and passes control >> to "old-figure". For new syntax, it passes control to "new-figure". An alternative occurred to me: simply assume the new figure directive syntax for "figure", and process normally. If there's an error, catch it and try the old syntax. If that works, use it, and issue a deprecation warning. This may need some infrastructure support. >> 4. At some point in the future (0.5 or 0.6 or past a certain date), >> remove the wrapper from #3 and alias "figure" to "new-figure". >> Leave "old-figure" alone. > > The problem with leaving "old-figure" alone is that this complicates > the document tree because we'd have to keep the "legend" element. > I'd like to drop the legend element at some point though. Of course, we'd be redefining the figure model in the DTD/doctree. This was omitted from the description but implied. We simply redefine the old-figure directive in terms of the new model. The legend just becomes body elements in the figure; perhaps inside a topic. >> Since the :counter: role could have a different interpretation >> inside a "sequence" directive than outside, we could also use >> :counter: instead of :counter-reference:/:cref:. > > This is not entirely clean because it means that the :counter: role > would have similar-looking yet different semantics inside and > outside a sequence directive: > > * Inside: :counter:`name-of-sequence` > * Outside: :counter:`name-of-numbered-object` That's true. If it's confusing, we could use :sequence:`name` within the directive and :counter:`name` outside. -- David Goodger <http://python.net/~goodger> |
From: Felix W. <Fel...@gm...> - 2005-08-16 20:22:21
|
David Goodger wrote: > Here are some concrete examples of what I'd like to see: > > .. figure:: Caption > > .. image:: figure.png > > This results in "Figure 1. Caption". The sequence and pattern are > implicit and pre-defined. I think they shouldn't be implicit, since sometimes unnumbered figures may be desired. The fact that something is a "figure" doesn't imply that it's numbered. So, also taking compatibility considerations regarding the caption into account, your example would look like this:: .. figure:: :caption: Caption :sequence: figure .. image:: figure.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: Felix W. <Fel...@gm...> - 2005-08-30 17:26:41
|
Felix Wiemann wrote: > I just had another idea popping into my mind: > > Maybe it would be simpler to use a pattern-less "counter" role which > just inserts a number and advances the counter. This, however, has the disadvantage that we cannot generate a "list of figures", "list of tables", or "list of whatever", because the numbers are not associated with captions. Which is really bad. So the :sequence: syntax seems to be the better solution. The fact that the proposed :sequence: syntax needs i18n still bothers me a bit, though. Maybe we should come up with some modification to simplify the logic and remove the need for i18n. I'll think about it; if/when I have an idea, I'll post it here. -- 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-19 01:30:58
Attachments:
signature.asc
|
> David Goodger wrote: >> Here are some concrete examples of what I'd like to see: >> >> .. figure:: Caption >> >> .. image:: figure.png >> >> This results in "Figure 1. Caption". The sequence and pattern are >> implicit and pre-defined. [Felix Wiemann] > I think they shouldn't be implicit, since sometimes unnumbered > figures may be desired. The fact that something is a "figure" > doesn't imply that it's numbered. True. In most documents I've seen, if any figures are numbered (& labeled!), they all are. This should perhaps be a document setting, like the sectnum directive (perhaps "fignum" and/or "figure-numbering"). We could introduce an "nolabel" directive option (or "plain" or something), to disable the default labeling for that figure. Symmetrically, if the default in a document is not to label, a "label" option could turn it on (and use the default sequence). > So, also taking compatibility considerations regarding the caption > into account, Please, let's not. It's a dead horse, stop flogging it. > your example would look like this:: > > .. figure:: > :caption: Caption > :sequence: figure > > .. image:: figure.png Adding ":sequence: figure" umpteen times in a document would soon become redundant and tiring. No thanks. -- David Goodger <http://python.net/~goodger> |