Re: Document titles (was RE: [Docstring-develop] DPS - possible bugs/features)

[Ueli S. <u_s...@bl...>]

(Warning: Some of what follws may not be sorted out well enough -- I
	  don't have the time to write and rewrite as much as I
	  should, but I don't want to miss the opportunity to add my 2
	  cents worth before going off line for a couple days...)

[Tony]
> As to HTML. The normal convention in HTML is that the document title
> (that is, the thing in <title> ) be the same as the <h1> title, and that
> there be one (and only one) <h1> in a document. The <title> is then
[...]
> at the top, which is used for both <title> and <h1>, and the "section
> hierarchy" (if any) starts with an <h2>.

Thanks for the explanations!  I don't see how it would make HTML
easier, though, as the final output is


[...]

> 
> 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), so we have to be able to cope
> with:
> 
> 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.
> 
> 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).
> 

[...]

> 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!).
> 
> *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:
> 
> 1. The parser makes one up (yuck)
> 2. The application makes one up (yuck)
> 3. An error is generated (yuck)
> 
> I'd vote for 3, not least for ease of explanation (I cite "there are no
> complex rules about making up document titles" versus "well, if the
> document is one section, we'll use the section title as a title, and not
> have any sections, but if the document is zero sections we'll do XXX and
> if the document is two or more sections we'll do YYY" - sorry to harp on
> the point!).

You've a point here...  Still, I believe the promotion is a Good Thing
at least for standalone documents.  Let me try to reformulate:

  The first title becomes the document title if
 
  - it's at the very beginning of the document and 
  - it's the only title at this level.

Does that sound too complicated?  Once I realized how it worked, I
went "oh, cool!" and wouldn't miss this feature now.

> Ueli seems, to me, to be partially arguing for the case I want in his
> next message. He also writes:

I don't have a firm point of view yet, and I second your point that
it's not a trivial issue.

My current opinion is that it really depends on what input we're
processing -- what is good for docstring processing may be wrong for
standalone documents and vice versa.  Hence I believe that the
promotion of a lone first section title should be optional.
Similarly, specifying and enforcing whether a documents needs a title
or not should be left to the writer, as this depends on the output
format and possibly on the context the system is used in, and the
application, as it may also depend on contecxt entirely *outside* the
DPS.  Which obviously opens up a whole new discussion, namely on how
to pass such context information down to the DPS...

> > The source filename isn't known to the writer, is it?
> 
> Well, it is in the pysource/pydps case (and I don't see why it shouldn't
> be elsewhere) - I attach a "filename" attribute to the Package and
> Module elements (which later on will become appropriate DPS structures,
> of course).
> 
> > Still, say I want ``<title>filename.rtxt</title>`` in HTML, but I
> > definitely don't want ``\title{filename}`` in LaTeX.  How about
> > giving the title a "generated" attribute?  Then it's left to the
> > writer to use (or ignore) it, but any document could be required to
> > have a title.  (Which would mean to update the DTD.)
> 
> *If* David still really wants to produce a title of his own, then yes,
> that's a good distinction to make.

It's not enough, though -- the writer still needs to be told by the
application whether it may use it or not.  Again, a docstring
vs. standalone-document issue (the document title for a docstring
will probably be generated by the reader, but should be respected).

But I really have to go now...  Hope I was clear enough!

Ueli