Re: [Docstring-develop] DPS - possible bugs/features

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

[David]
> [Ueli]
> > Now, it seems to me that the structures of documents and sections
> > are close relatives:
> > 
> > - A document may or may not have a title, a section always has one.
> 
> 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.

For PySource mode, this is certainly how it should work.  However, I'm
not sure whether it is always the desired behaviour.  I believe that
standalone rtxt files will often not have a formal document title,
just a few sections.  The reader/linker can't make up a sensible guess
in this case, and IIRC one important goal is to not try to outsmart
the user.  What would be a sensible default title, anyway?  Which
leads me to believe that the document title should be left optional
(but see filename_).  BTW, that's what dps/spec/gpdi.dtd says, too::

  <!-- Optional elements may be generated by internal processing. -->
  <!ELEMENT document
      ((title, subtitle?)?, (%bibliographic.elements;)*, abstract?,
       %structure.model;)>
  <!ATTLIST document %basic.atts;>

[David]
> Basically, yes, sections are simple sub-documents. The top-level
> document does need to be special-cased in the end however. HTML pages
> need their titles!

... and other types of output can merrily do without them.  LaTeX
vs. HTML seems to be a good example here!

In LaTeX, I'd definitley use the document title as an argument to
``\title{...}`` and leave the ``\title{...}`` out if the document had
none.  In HTML, though, <title>...</title> elements aren't displayed
(AFAIK, I'm not fluent in HTML).  Not knowing what they're meant for,
I'd be perfectly comfortable with something generated in this case,
like the [filename]_ or something along the lines of "Document
generated by pydps" (which is what my pydps/html.py does).

.. [filename] The source filename isn't known to the writer, is it?
   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.)

   (BTW, my first idea was to add a "sourcefile=filename.rtxt"
   attribute to the document.  I like the "generated" much better,
   though!)

Ueli