[Doc-SIG] Re: Document titles (was RE: [Docstring-develop] DPS - possible
bugs/features)
David Goodger
goodger@users.sourceforge.net
Mon, 24 Sep 2001 22:37:28 -0400
[As it may be of more widespread interest, I'm moving this discussion over
to Doc-SIG.]
Tony J Ibbs (Tibs) wrote:
> Ueli Schl=E4pfer gave a good explanation of why David Goodger had chosen
> to do something I didn't understand - namely make a document with a
> title at the start have no section within it (except it was subtler than
> that).
For those new to this discussion, please see Tony's original post at
http://www.geocrawler.com/lists/3/SourceForge/12823/0/6666616/ (Ueli's
followup is http://www.geocrawler.com/lists/3/SourceForge/12823/0/6667890/)=
.
To begin, let me reiterate what I wrote on Friday (21 Sept):
... Perhaps this parser-specific transformation should be made
optional [#]_. Then you can treat everything as generic sections
until integration is complete.
.. [#] Along with bibliographic field list interpretation, RCS
keyword filtering, and whatever other conveniences we dream up.
I will make these transformations optional, or remove them altogether
and relocate them to a separate module. The only problem with this
separation is that these transformations are markup-specific; they may
not be necessary with another markup syntax.
I don't know the best way to handle this situation yet; suggestions
are welcome.
[Tony]
> By the way, I did check the documentation, and it seemed to me that
> the current documentation indicated that a title would cause a
> section to be started - so David, if you want to perform this
> promotion, then it needs to be documented (unless I've missed it
> *again*).
No, you haven't missed anything. It wasn't documented; I guess it was
just so obvious to me that I never thought to write it down.
I'll work on an explanation for the spec (taking into account this
discussion, of course).
> On the other hand, I don't actually see why the DPS system should
> have to do the promotion for the user, when it's not clear that it
> is always wanted (in other words, why is it up to the DPS system to
> decide that the case of a single section is special, and then have a
> sudden disjunction in its behaviour for two sections - that's my
> inner pedant objecting!).
True, there's some ambiguity here. But the user needs some way to
indicate the document title.
> Regardless, an immediate solution to resolve the docstring case (and
> possibly a useful thing to do anyway) would be to have an argument
> to the Parser that states upfront that we are working on a document
> *fragment*
That's one possibility, yes.
> Broadly, HTML common practise treats a document as having a single
> title at the top, which is used for both <title> and <h1>, and the
> "section hierarchy" (if any) starts with an <h2>.
That's a transformation the HTML writer will want to do to the
document: convert the document title to both <HEAD><TITLE> and <H1>.
> Maybe (horrors) we should reserve one specific markup form to mean
> "overall title"::
That won't fly.
> Or perhaps we'll have to resort to::
>=20
> :Title: Document title
PEPs use this, but I wouldn't want to use it in my documents.
> Somehow, I don't see David liking either of those...
You know me so well!
> My problem is that I'm trying to write formatters for *any* document
> that might come in (yes, I know I'm writing pydps/pysource, but I
> want the Writer to work for any document)
The "Writer" being an "HTML Writer"?
> so we have to be able to cope with:
>=20
> 1. Document with no titles at all
> 2. Document with one title (OK - David does that)
> 3. Document with more than one title (at the same level)
> - which in essence *really* resolves back to case 1.
1 & 3 merge to become "Document without exactly one title". I'd say
that warrants an error from the HTML writer since a title is a
prerequisite. Or the HTML writer can call that document "Untitled".
Or both. The TeX writer need not complain.
> I'm afraid that the only "perfect" solution I can see for that (in
> the sense of *predictable*) is to require the user to indicate that
> they *do* have a document title, and that it is *this* thing, here.
> That then makes them aware of the problem, also, which I think is a
> necessary thing (otherwise, surprise will eventuate).
I think, documented, the promotion of a single section to document
status is natural and predictable. However, it's not the parser's job.
Is there an alternative?
> David Goodger wrote:
> > It is actually intended that by the time the document tree gets to
> > the writer, it must have a title. The parser can't always
> > determine the title by itself, such as in PySource mode. The
> > PySource reader is expected to supply all the titles as
> > appropriate.
>=20
> Hmm. In PySource mode, the parser should not be trying to introduce
> titles - it is, after all, handling arbitrary document fragments,
> and can't know anything about their global scope (unless it is
> told!).
We'll turn off the transformations for PySource mode. The parser will
no longer introduce titles; that's the reader's job.
> *If* the final tree shall always have a title, where does it come
> from if the document author didn't provide one? Surely in that case
> it is not up to the *parser* to decide on what a title should be -
> that is up to the application. So one has three options:
>=20
> 1. The parser makes one up (yuck)
> 2. The application makes one up (yuck)
> 3. An error is generated (yuck)
>=20
> I'd vote for 3 ...
Probably me too, in those cases where it's necessary. If the writer
doesn't need a document title, it need not complain.
[Ueli]
> The source filename isn't known to the writer, is it?
[Tony]
> I think that the sourcefile as an optional attribute on the document
> is probably a useful thing, as well.
I've added an optional attribute 'source' (not just files!) to
'basic.atts', so all elements will get it. That way, each fragment of
a document can record its origin.
--=20
David Goodger goodger@users.sourceforge.net Open-source projects:
- Python Docstring Processing System: http://docstring.sourceforge.net
- reStructuredText: http://structuredtext.sourceforge.net
- The Go Tools Project: http://gotools.sourceforge.net