Re: [Docutils-users] Removing certain elements from reSTX markup

[David G. <go...@py...>]

Morten W. Petersen wrote:
>> First, why?  What's your use case?  The simplest solution is, just
>> don't use that markup in your documents.  If it's important, make it
>> a policy decision in your organization.
> 
> I'm trying to find a mix of simplified RST that can be used straight
> away, and at most have 4-5 different markups (easily taught), for
> example emphasis, bullet lists, blockquotes and simple tables.

What do you do when the user needs one more construct, that isn't included
in your simplified set?  Personally, I'd rather begin educating with a small
number of core constructs, but using the full parser.  Simultaneously, give
references to the full docs for those who are interested in going further.

We don't teach programming languages or natural languages using limited
subsets.  We begin with simple concepts and build from there.

From PEP 287, Questions & Answers, #2:

   Is reStructuredText *too* rich?

   For specific applications or individuals, perhaps.  In general, no.

   Since the very beginning, whenever a docstring markup syntax has
   been proposed on the Doc-SIG_, someone has complained about the
   lack of support for some construct or other.  The reply was often
   something like, "These are docstrings we're talking about, and
   docstrings shouldn't have complex markup."  The problem is that a
   construct that seems superfluous to one person may be absolutely
   essential to another.

   reStructuredText takes the opposite approach: it provides a rich
   set of implicit markup constructs (plus a generic extension
   mechanism for explicit markup), allowing for all kinds of
   documents.  If the set of constructs is too rich for a particular
   application, the unused constructs can either be removed from the
   parser (via application-specific overrides) or simply omitted by
   convention.

I'd emphasize the final "or simply omitted by convention" as preferable.

> At the same time, I want to remove the ability to mess things up
> ... so that users can
> do whatever they want when not using the agreed upon markups.
>
>> Second, what should the parser do with the markup it ignores?
> 
> Don't touch it, 'pass it on' in other words.

Please consider carefully: would you really be doing your users a service
with this approach?

I think back to when I learned Japanese.  The class spent the first week
learning hiragana, the basic Japanese syllable characters (similar to an
alphabet), so we wouldn't get hooked on using "roma-ji" (roman letters, A-Z)
as a crutch.  When I lived in Japan, I found that people who had learned
Japanese with roma-ji reached a point -- learning written language -- beyond
which it was very difficult to progress, whereas those who learned with
hiragana had a much easier time.

Of course, reStructuredText is a much simpler language, but I believe the
same principles apply.

> (``'' is turned into some sort of hyperlink)

It's an error that's turned into a "problematic" element, with a link to the
diagnostic explanation.  It's an error because of unbalanced
double-backquotes.

>> The parser is not set up for this to be really easy to do, because it
>> hasn't been needed yet.
> 
> If there are more people out there like me, maybe it would be an idea
> to refactor a bit to make parts of docutils more like a 'markup
> parsing framework'?  Make it easier to mix-n-match different
> markups, which could lead to diverse markup 'dialects' of STX;
> diverse enough to be used by common people without screwing
> up, and diverse enough for the syntatic programmer.

I don't think encouraging dialects is a good idea.  It introduces
incompatibilities.  This use case doesn't sufficiently justify such changes
to me.  'Course, patches are always welcome.

-- David Goodger    http://starship.python.net/~goodger

Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv