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.
: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.
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