[Doc-SIG] Suggestions for reST "modes"

[David Goodger]

[Tony, Garth, Tony, Garth]
> > > > will be needed. I suspect that a means of marking
> > > > Chapter, Appendix, etc., explicitly may be needed [...]
> > >
> > > ``.. section::``, anyone?
> >
> > I suspect facetiousness (!) but it may come to that.
> 
> I'm not being facetious_. "Section" is the generic term most
> Microsoft Word users would use to describe a chapter or appendix. An
> application handling a "section" directive doesn't need to worry
> about having an insufficiently large list of words used in headings
> to describe a new section. Chapter and Appendix are obvious. `Fit
> the First` isn't.

You realize that section headers produce sections, which can be nested
indefinitely. I'm thinking of an option to the output formatter,
telling it what level of its native "tag" should correspond to the
document element (which is simply the outermost enclosing section). So
you could tell your book formatter to start at Chapter, or Section, or
Appendix, or Preface.

I'm pretty certain the parser doesn't need to know about any of this.

> .. _Fit the First: `The Hunting of the Snark: an Agony in Eight
>    Fits`_, by Lewis Carroll.

Note that this should be a footnote, not a hyperlink target.

-- 
David Goodger    dgoodger@bigfoot.com    Open-source projects:
 - Python Docstring Processing System: http://docstring.sourceforge.net
 - reStructuredText: http://structuredtext.sourceforge.net
 - The Go Tools Project: http://gotools.sourceforge.net