Re: [Docutils-users] Specification Documentation

[John F M. Jr <jo...@jo...>]

> Nothing wrong with that.  I noticed you limited section levels to 10
> (``self._section_number = [0]*10``), which may never be exceeded, but
> there's always the chance it will.  A stack or dictionary-based
> storage would be better.
>
Well, I switched the stack levels to a stack. I kept the list format, I 
just pop on a new entry every time I increment the section, and pop off 
one when I go back up. I get the same output, and it will grow as big as 
it needs to.

> > I keep track of what enumerations I'm nested in, along with what
> > the section counter is, (otherwise you have to set --use-latex-toc,
> > because section* doesn't increment the section counter).
>
> > How would you like the result?
>
> Normally, a SourceForge patch is best.  But we're small and informal
> here, so sending it to the list is no biggie.  Next time, you can post
> it directly to CVS: either directly to the core codebase, or to a
> sandbox directory if the change is potentially controversial.  What's
> your SourceForge user name?

My SourceForge ID is: jfmeinel

Is this okay to put in the core codebase?

>
> Let's say you have the following input:
>
>     (1) item one
>
>         a) subitem
>
>            (1) subsubitem
>
>         b) subitem
>
> How should the compound enumerators act?  Output could be any of
> these (or others):
>
> * (1) (1)a) (1)a)(1) (1)b)
> * (1) (1.a) (1.a.1) (1.b)
> * 1. 1.a. 1.a.1. 1.b.
> * (1.) (1.a.) (1.a.1.) (1.b.)
>
> Which does the code produce now?  Which way should it work?

To extend your example slightly:

(1) item one

    a) subitem

       (1) subsubitem

    b) subitem

        i. subsubitem
        ii. subsubitem2 

         

I chose
(1) 1.a) (1.a.1) 1.b) 1.b.i. 1.b.ii.

It always delimits with '.' except for the prefix and suffix, which is 
determined by the current enum. What is the 'correct' way? I'm not 
really sure. I think the suffix should be determined by the current 
enum, because the person chose that level to look a certain way. 
However, 1)a)2) doesn't look as good as 1-a.2) as the ')' has no feeling 
of joining. To me, the '.' and '-' work very well.

The only other *nice* option to me is to either *always* use a prefix 
[so (1) (1.a) (1.a.1) (1.b) (1.b.i) (1.b.ii)] or never use a prefix [ 1) 
1.a) 1.a.1) 1.b) 1.b.i) 1.b.ii)]

Notice that I also allow the user to determine whatever the suffix is. 
This lets them be consistent if they so choose, or change it.

> The flag names are OK as-is, but perhaps these would be better:
>
> * instead of --use-compound-enumerations, how about
>   --compound-enumerators?
> * --use-section-in-enumerations => --section-enumerator-prefix
> * --section-enumeration-char => --section-enumerator-separator
>
I chose --use* because there was --use-latex-toc, but some of the others 
don't have 'use',  so I switched to your recommendations. I wonder about 
--prefix-with-section, though.

> I don't know.  Open for discussion.
>
> I thought the help text for --section-enumeration-char was excessive.
> Something like "Set the separator between section number and
> enumerator for compound enumerated lists. (default: "=")".  The rest
> should go into the docs.
>
I agree, the help was a little verbose. But I was also trying to convey 
the idea to you.

> Other than that, the patch looks fine to me.  Engelbert Gruber should
> sign off on it.
>
Sounds good.
John
=:->