1 From: "G. Milde" <g.milde@web.de>
2 To: docutils-users@lists.sourceforge.net
5 Subject: Re: [Docutils-users] Re: figure that is not an image
7 In-Reply-To: <4326DCE7.4010608@python.org>
9 On 13.09.05, David Goodger wrote:
10 > I suggest the following:
12 > 1. Rename the existing "figure" directive to "old-figure"
13 > 2. Create a new directive "new-figure", with the new syntax
14 > 3. Create a new "figure" directive, a wrapper
15 > 4. At some point in the future (0.5 or 0.6 or past a certain date),
16 > remove the wrapper from #3 and alias "figure" to "new-figure".
17 > Leave "old-figure" alone.
19 I would rather use a new name for a generic "numbered, listable piece of
20 document" (with the new syntax).
24 * "sequence" (with the now discussed use as definition of a new counter and
25 prefix renamed to e.g. "new-sequence" or "new-sequence-type")
29 * "float" (for the LaTeX inclined, even if it does not float in html)
31 * "listable" (as this is one of the main features)
37 .. inset:: Gnus and Gnats
43 .. inset:: Gnu population
52 .. inset-type:: examples
53 :prefix: Example :counter:`examples`:
56 .. inset:: A classical example
69 > .. sequence:: examples
70 > :prefix: Example :counter:`examples`:
72 > I'm using the :prefix: option for text to add before the caption text.
73 > We could also have a :suffix: option for text to add after the caption
74 > text, but that may be over-engineering at this point.
76 > I wouldn't put the "advance the counter" functionality in the counter
79 > .. sequence:: listings
80 > :prefix: Listing :counter:`chapters`.:counter:`examples`:
82 > The sequence-advancing functionality should be in the formal object
83 > itself. Otherwise, in the example above, the "chapters" sequence
84 > would advance every time there was a listing!
86 > The "sequence" directive could be made such that the default
87 > interpreted text role **in its context** is :counter:. Then we'd
90 > .. sequence:: listings
91 > :prefix: Listing `chapters`.`examples`:
94 > > :caption: Figure :counter:`figure name`: A biohazard.
98 > > See figure :counter-reference:`figure name` for details.
100 > > (Equivalent: See :cref:`figure name` for details.)
102 > > This would make the :counter: role parallel to the :cref: role,
103 > > i.e., they have the same syntax.
105 > Since the :counter: role could have a different interpretation inside
106 > a "sequence" directive than outside, we could also use :counter:
107 > instead of :counter-reference:/:cref:.
109 > > To add new counters, create a new role:
111 > > .. role:: figure(counter)
112 > > .. role:: table(counter)
114 > I'd rather that new counters be created as a direct result of the
115 > "sequence" directive.
117 > > Maybe those two could be built in for convenience.
119 > Yes, those two sequences would be built-in.
121 > > The naming may need improvement (maybe call it "number" instead of
122 > > "counter", etc.), but I think that this realization of
123 > > auto-numbering has several advantages:
125 > > * Parallel syntax (:counter:`figure name`, :cref:`figure name`).
127 > > * No cluttering of directive code -- the :counter: directive can be
128 > > used anywhere. That seems more orthogonal.
130 > Hmm. Is that an argument against using :counter: in both contexts? I
131 > suppose it is possible for a formal object *caption* to contain a
132 > counter reference. But I can't imagine a *sequence definition* (i.e.,
133 > :prefix: option) needing a counter reference.
135 > > * No internationalization required.
137 > > The only disadvantage is that the name of the sequence
138 > > (e.g. "Figure") has to be spelled out explicitly in the figure
141 > That's a big disadvantage. The overhead of having to write
143 > Figure :counter:`figures`: caption text
145 > is too much. We'll require the internationalization.
148 > David Goodger <http://python.net/~goodger>