[Docstring-develop] Re: [Docstring-checkins] CVS: dps/spec gpdi.dtd,1.32,1.33

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

I checked dps/spec/gpdi.dtd in to CVS:
>> Log Message:
>>   - Made ``abstract`` a structural element, after ``docinfo``.

Richard Jones wrote:
> In my mind, the abstract forms a part of the docinfo.

I've revised my design, for three reasons. First, I think of the docinfo as
the "copyright page" metadata stuff, and the abstract doesn't belong there.
Second, because unlike all the other docinfo elements which contain only
text (%text.model;), abstracts may contain multiple body elements. Third, I
already had (artificial, in retrospect) limitations on abstracts: there
could be only one, and it had to be at the end of the docinfo.

Working on my HTML Writer forced me to think about the roles of the various
pieces. Abstracts work as a fixed-title mini section.

Over time you'll see that I continually evolve my designs, searching for a
sometimes-elusive ideal. Please bear with me, and consider *everything*
experimental until 1.0. It's a pain, I know. (Believe me, I know. It's
painful to *me* to rip out code sometimes.) But it's for the best.

If you notice anything that smells bad, please point it out. Debates on the
mailing lists have helped considerably.

> I was actually going to stuff the abstract into the html head as a meta
> description tag.

You can still do that. But what if the abstract is half a page long? Or
includes a bullet list or table? Besides, there's now a ``.. meta::``
directive specifically for HTML metadata.

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