[Doc-SIG] RE: David's Idea for Lazy Indentation

[Moore, Paul]

From: David Goodger [mailto:dgoodger@bigfoot.com]
>Moore, Paul <Paul.Moore@atosorigin.com> wrote on 2001-08-14
>06:44:
>
>> Excuse my butting in - I'm not a member of the doc-sig,
>> but I noticed this while browsing the web archives.
>
>Not at all; glad to have you, the more the merrier. Please
>join up! (It's free you know. :-)

No, it's not - the cost is yet *more* E-Mail in my inbox :-) But I probably
should. I care about having a documentation system. I worked with Perl for a
long time, and there are major benefits to POD. Not, I hasten to add,
because it is a *good* system (it sucks in many ways), but because it
*exists*. I have a strong interest in seeing Python have a standard
documentation system. Even if it's not perfect - it needs to exist SOON.
More and more people are learning Python, and there needs to be a culture of
seeing documentation (and testing - I was glad to see unittest get into the
core - and standard distribution methods - distutils ditto) as "just
something that you do". Perl module documentation may not always be good,
but it's always there, and always accessible by the same means (perldoc).
That makes a lot of difference.

<soapbox mode off>

>One very important thing was missing from the original
>post: mention of the context. In this case, the context is
>for applications like Wikis and email, where decent editors
>are not available, and a "shortcut" lazy indentation mode
>may be desirable. Rest assured, it will not infect the rest
>of reStructuredtext.

Hmm. So this is a context where the original plain text is never going to be
read "raw"? In that case, I can see the point (a bit). But that sounds like
a significantly different application area (markup-less markup, as it were,
rather than structured plaintext -- but maybe I'm taking the point too far).

>> PS As a check, did my enumerated list above work as
>> (re-)structured text?
>
>Yes, it looks fine, except that something (probably your
>email client) hard-wrapped a few words that stuck out a bit
>too far to the right, which would throw the parser for a
>loop. This is *exactly* the reason lazy indentation may be
>necessary in applications like email; thanks for providing
>an (unwitting) example! To see the problem, take a look at
>your message in the archive:

Yes, I saw that after I'd posted :-)

But I have some thoughts there. First, I can't imagine that sort of problem
*ever* being automatically fixable. I've seen enough quoted text mangled by
E-Mail systems to give up hope. It simply isn't *readable* -- let alone
automatically fixable. (I know quoting differs from structured constructs,
but if you think of a quote as a bulleted list with > as the bullet, you get
my point...)

Second, I was annoyed when I saw that post. I see it as a failure on my part
to not take into account the annoying tendencies of my E-Mail client to
re-wrap text, when posting. It's *my* job to communicate clearly. It's not
the recipient's job to struggle through mangled text in order to to perceive
the pearls of wisdom I impart :-) [Nor is it the job of some almost-magical
piece of software to allow both of us to be lazy - after all, the recipient
may not be able to *run* the software against the text - for example, while
reading the web archive!]

Finally, if someone *writes* text in that sort of lazy format (I'm thinking
here of dumb editors, rather than later mangling like E-Mail), I'd say that
they aren't taking enough care over the form of what they are saying, which
makes me wonder about the content. Maybe I'm over harsh, but I really do
believe that taking a little extra time to format clearly pays vastly in
terms of clarity of wording. And a system which bends over backwards to
allow people to format sloppily, is favouring form over content a little too
much. (Hmm, I hope that didn't come across as too dogmatic - it isn't meant
to be...)

Paul.