Run.hs: improve haddock

This module too was causing horizontal scrolling because of the shell command. I managed to discover that you only need to specify 'png:' *or* "foo.png", not both, which trimmed off enough characters.
Also, I improved the docs for my functions.

darcs-hash:20080316223219-f7719-0accbb96dc6a14bbb5ba302a2dbae65c1a78fedd.gz

1 files changed, 26 insertions, 25 deletions

diff --git a/XMonad/Util/Run.hs b/XMonad/Util/Run.hs
index 165513b..3c5fb0c 100644
--- a/XMonad/Util/Run.hs
+++ b/XMonad/Util/Run.hs
@@ -85,41 +85,42 @@ runProcessWithInputAndWait cmd args input timeout = do
 seconds :: Rational -> Int
 seconds = fromEnum . (* 1000000)
 
--- | safeSpawn bypasses XMonad's 'spawn' command, because 'spawn' passes
--- strings to \/bin\/sh to be interpreted as shell commands. This is
--- often what one wants, but in many cases the passed string will contain
--- shell metacharacters which one does not want interpreted as such (URLs
--- particularly often have shell metacharacters like \'&\' in them). In
--- this case, it is more useful to specify a file or program to be run
--- and a string to give it as an argument so as to bypass the shell and
--- be certain the program will receive the string as you typed it.
--- unsafeSpawn is an alias for XMonad's 'spawn', to remind one that use
--- of it can be, well, unsafe.
--- Examples:
---
--- >     , ((modMask, xK_Print), unsafeSpawn "import -window root png:$HOME/xwd-$(date +%s)$$.png")
--- >     , ((modMask, xK_d    ), safeSpawn "firefox" "")
---
--- Note that the unsafeSpawn example must be unsafe and not safe because
--- it makes use of shell interpretation by relying on @$HOME@ and
--- interpolation, whereas the safeSpawn example can be safe because
--- Firefox doesn't need any arguments if it is just being started.
+{- | 'safeSpawn' bypasses "XMonad.Core"'s 'spawn' command, because spawn passes
+strings to \/bin\/sh to be interpreted as shell commands. This is
+often what one wants, but in many cases the passed string will contain
+shell metacharacters which one does not want interpreted as such (URLs
+particularly often have shell metacharacters like \'&\' in them). In
+this case, it is more useful to specify a file or program to be run
+and a string to give it as an argument so as to bypass the shell and
+be certain the program will receive the string as you typed it.
+unsafeSpawn is internally an alias for XMonad's 'spawn', to remind one that use
+of it can be, well, unsafe.
+Examples:
+
+> , ((modMask, xK_Print), unsafeSpawn "import -window root $HOME/xwd-$(date +%s)$$.png")
+> , ((modMask, xK_d    ), safeSpawn "firefox" "")
+
+Note that the unsafeSpawn example must be unsafe and not safe because
+it makes use of shell interpretation by relying on @$HOME@ and
+interpolation, whereas the safeSpawn example can be safe because
+Firefox doesn't need any arguments if it is just being started. -}
 safeSpawn :: MonadIO m => FilePath -> String -> m ()
 safeSpawn prog arg = liftIO (try (doubleFork $ executeFile prog True [arg] Nothing) >> return ())
 
 unsafeSpawn :: MonadIO m => String -> m ()
 unsafeSpawn = spawn
 
--- | Run a given program in the preferred terminal emulator. This uses
--- 'safeSpawn'.
-safeRunInTerm :: String -> String -> X ()
-safeRunInTerm options command = asks (terminal . config) >>= \t -> safeSpawn t (options ++ " -e " ++ command)
-
+-- | Open a terminal emulator. The terminal emulator is specified in @defaultConfig@ as xterm by default. It is then
+-- asked to pass the shell a command with certain options. This is unsafe in the sense of 'unsafeSpawn'
 unsafeRunInTerm, runInTerm :: String -> String -> X ()
 unsafeRunInTerm options command = asks (terminal . config) >>= \t -> unsafeSpawn $ t ++ " " ++ options ++ " -e " ++ command
 runInTerm = unsafeRunInTerm
 
--- | Launch an external application and return a 'Handle' to its standard input.
+-- | Run a given program in the preferred terminal emulator; see 'runInTerm'. This makes use of 'safeSpawn'.
+safeRunInTerm :: String -> String -> X ()
+safeRunInTerm options command = asks (terminal . config) >>= \t -> safeSpawn t (options ++ " -e " ++ command)
+
+-- | Launch an external application through the system shell and return a @Handle@ to its standard input.
 spawnPipe :: String -> IO Handle
 spawnPipe x = do
     (rd, wr) <- createPipe