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

[Morten W. P. <mo...@ni...>]

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

Exactly.  Althought I appreciate your advice, I'd like to try
out a basic markup and see if it's enough.  The idea isn't
to teach them a basic set and later teach them the whole thing;
the idea is to find a basic set that's easy to teach, and
powerful enough for most (90%+) of the things they need
to markup.

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

And what happens when the user does something that's an error
according to RST but not part of the markup he/she has learned?

> > 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 believe so, yes.  :)

> I think back to when I learned Japanese.
[...]
> Of course, reStructuredText is a much simpler language, but I believe 
> the same principles apply.

Yes, the principles might apply if the intention is to learn them 
everything, starting with a basic markup.  It isn't the intention.

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

I'd like to play around with it;  if there's time, I will.  :)

Regards,

Morten W. Petersen

Technologies: Zope, Linux, Python, HTML, CSS, PHP
    Homepage: http://www.nidelven-it.no
Phone number: (+47) 45 44 00 69