[Doc-SIG] verse construct (was Re: [Docutils-develop] Parsing oddness)

[David Goodger]

Paul Moore wrote:
> The recent discussion on python-dev was lukewarm, and I got the
> sense that part of the issue was "why does it need to be so
> complicated?"

Because too simple is useless.  HappyDoc seems like a great tool, but
I don't use it because using StructuredText is like hitting my head
against a brick wall.  But it *is* enough for some.

I've found that many people, programmers especially, take a
condescending attitude toward documentation and related tools, which
results in computers being used as electronic pencils.  If we listened
to them, we'd still be using typewriters (nix that: clay tablets!).  I
saw it when I was working in Japan with SGML -- well-known
multinational companies (an RDBMS producer, a car manufacturer, and a
telcom giant) treated their documentation as garbage.  But I digress.

> > Richard Jones wanted a snailmail address in a document.
> 
> That's a valid case. Two points - first, with this use case in mind,
> "verse" is a dreadful name. I can't think of a good one, though.

Let me know if you do.  I'll be hitting the thesaurus myself.

> And the second point is why can't this be handled with a literal
> block? I can't imagine needing markup in an address. Is it just
> because literal blocks are displayed in a fixed-width font, and so
> don't "look right"?

Yes, that's right.  Markup may not be needed in address blocks, but it
would be in other applications.  The idea originally applied to
quoting verse: poetry, song lyrics, etc.  I pointed out to Richard at
the beginning of this thread that it was equally applicable to address
blocks.  So address blocks are a secondary use case, not the primary
one.

> I would ask again, what is the *logical* construct involved here?
> Logically, the gap in functionality is the lack of any way of
> including markup in a "literal" block. In other words, a
> linebreak-preserving construct where markup is still respected.

I approach it from the opposite side.  It's not the lack of markup in
literal blocks, but the lack of linebreak and indentation control in
paragraphs.  The "verse" construct permits significant linebreaks and
indentation in otherwise ordinary paragraphs.  Literal blocks have the
connotation of program input or output; this construct doesn't.
Literal blocks' use of a monospaced typeface is to emphasize this
connotation.

That gives me an idea for a name for this thing: "literary blocks"...
Probably too clever by far.  ;-)

> Word linebreaks and <br> tags are inherently formatting directives,
> not structural ones. That's the distinction I'm trying to make.

Hmm.  I think poets would differ.  The way a poem is broken up into
lines (whether there's a rhyming scheme or not) is *very* significant,
and conveys a large part of the poem's structure.  Similarly (but in a
much less interesting way) with the pedestrian address block: the line
itself is a unit of structure.

> And at least as importantly, if you use a directive, you're *forced*
> to think up a decent name for it!

Yes, explicit is good, especially for non-mainstream uses.  Please
keep the search for the right name running on low priority in the back
of your brain.

> If you make it clear that "library directives" are extensions, not
> part of "core" reST, then I have no problem with this.

I've rearranged the text of the directive definition to reflex this
emphasis:

    http://docutils.sf.net/spec/rst/reStructuredText.html#directives

> Thanks for listening - as I said, I'm not against the construct per
> se, but I would like to see a clearer picture of the logic behind
> it...

Sure.  Thank *you* for writing.  The feedback is valuable, as always.

-- 
David Goodger  <goodger@users.sourceforge.net>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/