what's the deal with "user error" on fail?

[Alastair Reid]

> And how does one explicitly report an error? I would normally do it by
> implementing something functionally equivalent to fail.  Why not let fail
> serve this purpose?

There's several different needs in reporting errors.
One is to help with debugging which is what error, pattern match failure, etc. 
do.

A quite different one is to tell users of your application that they have done 
something wrong (e.g., file they specified doesn't exist, etc.)

The standard Haskell functions are primarily targetted at the first usage (we 
could argue about how well they do it).  For text-based applications, I find 
the following to be a good starting point.  

-- | 
-- Print an error message and exit program with a failure code
failWith :: Doc -> IO a
failWith msg = do
  printDoc PageMode stderr msg
  exitFailure

-- | 
-- Print an error message and exit program with a failure code
abortWith :: Doc -> a
abortWith msg = unsafePerformIO (failWith (text "" $$ text "Error:" <+> msg))

-- | 
-- Print message to stderr if condition holds
blurt :: Bool -> Doc -> IO ()
blurt False msg = return ()
blurt True  msg = printDoc PageMode stderr msg


For applications that use a GUI and for situations where the problem is not 
fatal, you would want different functions again.

Hope this helps,
--
Alastair Reid     www.haskell-consulting.com