[pmwiki-users] leading spaces switch for 2.2.0 (somewhat important)

[Patrick R. Michaud]

On Mon, Mar 26, 2007 at 06:48:05AM +0100, marc wrote:
> The Editor said...
> > I'd be interested again in hearing your reasons for keeping the
> > leading white space rule.  Is there actually some reason it shouldn't
> > be turned off by default?
>  
> The syntax exists; it's a very easy to use; it is used frequently. 

FWIW, I agree with many of marc's comments here.  I can name a very 
strong reason why the leading whitespace rule shouldn't be turned off 
by default -- there are a lot of existing sites (including most of my
own) that rely on the whitespace rule.  

Because of existing installations there's always a bias towards
not changing things in the core.  Thus in general we should change
an existing default only if there's an overwhelming reason to do so,
not because there might not be reasons not to do it.

> Perhaps, Dan, you might like to ask Patrick why he put it in in the 
> first place. 

...a great question, and I'll save Dan the trouble of asking.  :-)  

The leading whitespace -> preformatted markup has existed in PmWiki 
since its earliest incarnation (i.e., in 0.1).  It was put in for
at least several reasons:

1.  There's often a need to display preformatted text.
2.  Most wiki engines at the time used leading spaces to indicate
    preformatted text, so many authors were conditioned to expect it.
3.  Many other non-wiki markup languages also use leading whitespace to
    indicate preformatted text (e.g, Perl's POD format).
4.  On the sites I run, there is a need to display preformatted 
    text and it was natural to use leading spaces for this.

It's hardly an arbitrary markup -- as marc mentions, it exists for
a specific purpose and many people (myself included) find it quite useful.

> Turning it off by default is not a big deal in the grand scheme of 
> things. But it's one more additional thing to adjust during 
> installation. 

You're correct that it's an additional thing to adjust during 
installation... but with an either-or option such as this there will
always be some group for which the default (whatever it is) will
require adjusting.  When that happens, we want to pick the default
that will minimize overall pain in the future.  Thus, we need to examine

  - What causes the least amount of negative surprise for new people?
  - How easy will it be for an admin to locate the default setting and
    change it?
  - If a bunch of pages are created with a particular default, what
    will be the ramifications of switching it later?

In this particular case, there's a fair amount of negative surprise
associated with having the leading whitespace rule enabled by default.  
When enabled, authors and admins unaware of the rule see an effect 
(incredibly wide pages) that doesn't have an obvious relationship
to the cause (leading whitespace).  It's very hard for them
to get from the problem ("wide pages") to the solution ("remove
leading whitespace or disable the rule") without a lot of searching 
and potential dead ends.  Many will simply assume (and have assumed)
that the wiki is broken somehow and there's nothing they can do about
it.  (This latter point is very bad, because it tends to discourage 
people from using the wiki.)  And, once pages have been created with
leading whitespace enabled, it's a major chore to switch the site to
'disabled' because any existing pages have to be corrected.

However, the reverse situation appears to be a lot less painful
and produce less unexpected negative surprises.  If someone tries 
to use leading spaces to preformat text and it doesn't work, it's 
much easier to find answers for things like "How do I write
preformatted text" and "Can leading spaces be used to indicate
blocks of preformatted text?" Also, after pages are created with
the leading whitespace rule disabled, enabling it later doesn't
cause preformatted text to suddenly become un-preformatted.  There
*is* the potential that pages will suddenly become very wide, but
we can warn the admin of this potential problem at the point where
she is enabling the feature (instead of discovering an undesirable
default).

So, on balance, it looks like it's much easier for admins to start
with the feature disabled and explicitly enable it later than it
is to go in the other direction.

> In addition, removing very useful functions by default 
> seems a strange thing to do [...]

"Useful functions" for some can be "major annoyances" for others.  
The leading whitespace rule is incredibly useful to me personally,
but I can tell it is causing lots of grief for others.

So, in cases like these, PmWiki tends towards a more "minimalist"
approach, so that some features require explict enabling by an
admin, such that the admin isn't later surprised by a potentially
undesirable feature having been enabled by default for some time.

Hope this helps clear things up a bit...

Pm