sandbox/enhancement-proposals/docutils-sequences-idea.txt

   1 From: "G. Milde" <g.milde@web.de>
   2 To: docutils-users@lists.sourceforge.net
   3 Cc:
   4 Bcc:
   5 Subject: Re: [Docutils-users] Re: figure that is not an image
   6 Reply-To:
   7 In-Reply-To: <4326DCE7.4010608@python.org>
   8
   9 On 13.09.05, David Goodger wrote:
  10 > I suggest the following:
  11 >
  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.
  18
  19 I would rather use a new name for a generic "numbered, listable piece of
  20 document" (with the new syntax).
  21
  22 Suggestions would be
  23
  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")
  26
  27   * "inset"
  28
  29   * "float"     (for the LaTeX inclined, even if it does not float in html)
  30
  31   * "listable"  (as this is one of the main features)
  32
  33
  34
  35 Examples of use::
  36
  37   .. inset:: Gnus and Gnats
  38      :type: figure
  39
  40      .. image:: gnus.jpg
  41
  42
  43   .. inset:: Gnu population
  44      :type: table
  45
  46      Year   Numbers
  47      ----   -------
  48      2004      3
  49      2005     23
  50
  51
  52   .. inset-type:: examples
  53     :prefix: Example :counter:`examples`:
  54
  55
  56   .. inset:: A classical example
  57      :type: example
  58
  59      ::
  60
  61        print "Hello world!"
  62
  63
  64
  65
  66
  67
  68
  69 >     .. sequence:: examples
  70 >        :prefix: Example :counter:`examples`:
  71 >
  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.
  75 >
  76 > I wouldn't put the "advance the counter" functionality in the counter
  77 > role:
  78 >
  79 >     .. sequence:: listings
  80 >        :prefix: Listing :counter:`chapters`.:counter:`examples`:
  81 >
  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!
  85 >
  86 > The "sequence" directive could be made such that the default
  87 > interpreted text role **in its context** is :counter:.  Then we'd
  88 > have:
  89 >
  90 >     .. sequence:: listings
  91 >        :prefix: Listing `chapters`.`examples`:
  92 >
  93 > >     .. figure::
  94 > >        :caption: Figure :counter:`figure name`: A biohazard.
  95 > >
  96 > >        ... contents ...
  97 > >
  98 > >     See figure :counter-reference:`figure name` for details.
  99 > >
 100 > >     (Equivalent: See :cref:`figure name` for details.)
 101 > >
 102 > > This would make the :counter: role parallel to the :cref: role,
 103 > > i.e., they have the same syntax.
 104 >
 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:.
 108 >
 109 > > To add new counters, create a new role:
 110 > >
 111 > >     .. role:: figure(counter)
 112 > >     .. role:: table(counter)
 113 >
 114 > I'd rather that new counters be created as a direct result of the
 115 > "sequence" directive.
 116 >
 117 > > Maybe those two could be built in for convenience.
 118 >
 119 > Yes, those two sequences would be built-in.
 120 >
 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:
 124 > >
 125 > > * Parallel syntax (:counter:`figure name`, :cref:`figure name`).
 126 > >
 127 > > * No cluttering of directive code -- the :counter: directive can be
 128 > >   used anywhere.  That seems more orthogonal.
 129 >
 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.
 134 >
 135 > > * No internationalization required.
 136 > >
 137 > > The only disadvantage is that the name of the sequence
 138 > > (e.g. "Figure") has to be spelled out explicitly in the figure
 139 > > caption.
 140 >
 141 > That's a big disadvantage.  The overhead of having to write
 142 >
 143 >     Figure :counter:`figures`: caption text
 144 >
 145 > is too much.  We'll require the internationalization.
 146 >
 147 > --
 148 > David Goodger <http://python.net/~goodger>
 149
 150
 151
 152 --
 153 G.Milde web.de