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

[Moore, Paul]

From: David Goodger [mailto:goodger@users.sourceforge.net]
> 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.

"As simple as possible, but no simpler". Exactly. It's the "as possible" bit
that is generally the sticking point. What's one person's useless fluff is
another's impossible to live without. But the doc-sig is in the unenviable
position of having to make priority judgements.

Don't forget, we still haven't got a construct to allow words to be set in
24-point blinking script capitals. And please God, don't let us ever get one
:-) But I've seen plenty of web sites which provide evidence that *someone*
thinks it is appropriate :-(

> 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.

Again, it's a case of being aware of your target application. Not many
people quote poetry in technical documentation. But many would want to
include an address. On the other hand, the balance could be completely the
opposite in E-Mail postings (depending on the mailing list). It's still a
case of needing to understand the priorities.

> 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.

But in terms of probability of being needed, address blocks are more
significant (in my personal view of the target application). It's an 80-20
thing.

BTW, on the verse issue specifically, I'm convinced (see below), subject to
a decent name. The bulk of what I'm now saying is in terms of generalities.
I'm really arguing that we have now reached a stage where a more
conservative approach is called for. Specifically, no new syntax should be
added - directives form our extension mechanism, and we should concentrate
on consolidating the core, and if appropriate, building our "standard
library". And on *using* these things for real, in visible ways. It's
interesting and encouraging to be reminded that the docutils web pages are
all generated from reST. More such public examples would be nice - as well
as giving a real-life indication of which constructs are important in
practice...

> 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.

Ah, yes. When you put it like that, I see your point better. BTW,
significant indentation? That could be hard - input is monospaced font, but
output is proportional, so preserving the *appearance* of an indent won't be
that easy.

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

Yes. Given that my preferred use case is addresses, I'd argue for "address
blocks", and then note in the documentation that these will work for all
sorts of other things, like quoting verse... (And I'm not really joking
here, either!)

> 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.

OK. This is the point at which you have convinced me. There are significant
cases where line breaking denotes structure, but in a sufficiently
"unstructured" way (:-)) that the existing constructs such as lists, etc,
don't do what you want.

Maybe something like "multiline" blocks gives the flavor, without stressing
a particular usage...?

> I've rearranged the text of the directive definition to reflex this
> emphasis:
> 
>     http://docutils.sf.net/spec/rst/reStructuredText.html#directives

I'd add a bit more. "Directives which have been implemented and registered
in the reference reStructuredText parser are described in the
reStructuredText Directives document." Add after this "Document authors are
entitled to expect that all such standard directives are available. Any
other directives should be viewed as domain-specific, and may require
special action to make them available when processing the document."

Or something like that...

Paul.