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

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

While trying to get some LaTeX output from text files [#]_, I've
stumbled over your first bug/feature, too.  This is what I found after
playing around a bit:

- Say you've got a document that starts with a title that uses a style
  unique to the document.  (David uses titles over- and underlined
  with ``=`` in this case.)  This title will be the document title::

    ---------------------------
    ================
     Document title
    ================

    The first paragraph
    ---------------------------

  results in::

    <document name="document title">
	<title>
	    Document title
	<paragraph>
	    The first paragraph

- Now add a title in the same style.  You've got two sections, and no
  document title anymore.  With ::

    ---------------------------
    ===============
     First section
    ===============

    The first paragraph

    ================
     Second section
    ================

    Where's the document title?
    ---------------------------

  you get this::

    <document>
	<section name="first section">
	    <title>
		First section
	    <paragraph>
		The first paragraph
	<section name="second section">
	    <title>
		Second section
	    <paragraph>
		Where's the document title?

- OR add some text before this paragraph.  Same result, no document
  title any more, just section titles.  Again an example::

    ---------------------------
    Where's the document title?

    ===============
     First section
    ===============

    ...
    ---------------------------

  produces::

    <document>
	<paragraph>
	    Where's the document title?
	<section name="first section">
	    <title>
		First section
	    <paragraph>
		...

This makes sense to me, so I consider it a feature.  I'm actually not
sure how I'd be able to give a title to the document as a whole if the
parser worked as you expected (unless you special-cased the first
section level!)  (Explicitly discriminating between a document title
and regular section titles doesn't count here.)

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.
- A document may have a subtitle, bibliographic elements, and an
  abstract.  A section has none of these.
- The rest of the content follows the same model.

Can thus sections be treated as simpler cases of documents (instead of
the other way round, which is how I understand your post)?  I'm not
sure how I would exploit this, though...

Hope I'm making sense here...

Ueli

.. [#] Not sure whether *that* is a good idea (me coding, not
       LaTeX ;-)  Anyway, when I have something useful, I may post it
       here -- but only if everybody promises not to laugh out loud...


"Tony J Ibbs (Tibs)" <to...@ls...> writes:

> Hi - two problem reports and an upload.
>
> First, I've uploaded a new pydps - it fixes some command line anomalies
> (so one can now pretty print a text file!), and the HTML output now
> makes a first pass at coping with references/footnotes/etc. (it doesn't
> yet fold in targets, because that's plainly a job for the transformer
> stage, and I don't have one of those yet!). Anyway, when run over
> reStructuredText.txt, the result is now something approaching useful.
>
> Now for the problems:
>
> 1. When trying to process reStructuredText.txt, the document produced
>    starts off like (output in "pretty mode")::
>
>       <document name="restructuredtext markup specification">
>         <title>
>           reStructuredText Markup Specification
>
>    This seems wrong to me - surely by the law of least surprise,
>    it should actually be:
>
>       <document name="restructuredtext markup specification">
>         <section>
>           <title>
>             reStructuredText Markup Specification
>
>    After all, the document starts with a title, and everywhere else
>    in the document, a title is a signal that one is starting a section.
>    (this isn't pure pedantry - it makes it a lot easier for me to
>    determine what is going on - I don't *particularly* want to special
>    case "document", and I *do* want to be able to cope well with
>    documents that *don't* start with a title...)
>

[...]