docutils-users

[Docutils-users] auto-section numbering

[Brett g P. <bgp...@ac...>]

Is there any simple method to use auto-numbering, but to delay its start 
point?

F'r example, I'm writing a spec, and I'd like to have some introductory 
material that is NOT given a section number, and then have the body of 
the spec auto-numbered, something like:


Intro
======

handwaving and other filler text here...


Heading 1
---------

blah blah blah

detail 1
.........

detail 2
.........

(&c)

would get rendered out as:

Intro

1     Heading 1
1.1   detail 1
1.2   detail 2

Re: [Docutils-users] auto-section numbering

[David G. <go...@py...>]

Brett g Porter wrote:
> Is there any simple method to use auto-numbering, but to delay its start
> point?

Not currently, no.  But it wouldn't be difficult to add an option to the
"sectnum" directive, like the "contents" directive's "local" option --
except that there are some issues to be resolved first.  I see these
possibilities:

1. Limit the auto-numbering to the current branch of the document tree
   ("start here, and auto-number until the end of this section").

   What if another local "sectnum" directive appears in another branch?
   Are the sequences independent and contain duplicates, or should they
   know about each other and contain unique numbers?

2. Start auto-numbering at the directive, and continue to the end of the
   document.

   Should the auto-numbering include the section the directive appears
   within?

   What if the directive appears in a subsection?  We could get weird
   numbering, like::

        Intro
        One         <-- directive appears here
            1. A    <-- or here (depending on another answer)
            2. B
        Two         <-- should this be numbered?  How?

   Perhaps the auto-numbering should always begin with a topmost section
   ("One" above).

On a related note, I'm thinking of adding a feature to "sectnum" to create
implicit hyperlink targets based on the generated section numbers, so that
we can refer to FAQ entries etc. by number.
(<http://docutils.sf.net/FAQ.html#what-s-the-standard-abbreviation-for-restr
ucturedtext> would be replaced by <http://docutils.sf.net/FAQ.html#2-3>.)
Thus the question raised in #1 above becomes important here.

-- David Goodger    http://starship.python.net/~goodger

Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv

Re: [Docutils-users] auto-section numbering

[Brett g P. <bgp...@ac...>]

David Goodger wrote:
> Brett g Porter wrote:
>=20
>>Is there any simple method to use auto-numbering, but to delay its =
start
>>point?
>=20
>=20
> Not currently, no.  But it wouldn't be difficult to add an option t=
o the
> "sectnum" directive, like the "contents" directive's "local" option=
 --
> except that there are some issues to be resolved first.  I see thes=
e
> possibilities:
>=20
> 1. Limit the auto-numbering to the current branch of the document t=
ree
>    ("start here, and auto-number until the end of this section").
>=20
>    What if another local "sectnum" directive appears in another bra=
nch?
>    Are the sequences independent and contain duplicates, or should =
they
>    know about each other and contain unique numbers?
>=20
> 2. Start auto-numbering at the directive, and continue to the end o=
f the
>    document.

For my needs, this (#2) would be more than adequate.



--=20

//  Today's Oblique Strategy (=A9 Brian Eno/Peter Schmidt):
//  Are there sections? Consider transitions
//  Brett g Porter * BgP...@ac...