XSelection.hs: update docs w/r/t unicode

Ignore-this: 26042b8d27bed602c1844181036a9bb
see http://code.google.com/p/xmonad/issues/detail?id48

darcs-hash:20100615000902-f7719-6b0d996115b621c065b5ab8d4ff44ff1465bd84e.gz

1 files changed, 15 insertions, 23 deletions

diff --git a/XMonad/Util/XSelection.hs b/XMonad/Util/XSelection.hs
index 2dc68e6..330f2e8 100644
--- a/XMonad/Util/XSelection.hs
+++ b/XMonad/Util/XSelection.hs
@@ -39,23 +39,13 @@ import Codec.Binary.UTF8.String (decode)
 
    > , ((modm .|. shiftMask, xK_b), promptSelection "firefox")
 
-   There are a number of known problems with XSelection:
+   Future improvements for XSelection:
 
-    * Unicode handling is busted. But it's still better than calling
-      'chr' to translate to ASCII, at least.
-      As near as I can tell, the mangling happens when the String is
-      outputted somewhere, such as via promptSelection's passing through
-      the shell, or GHCi printing to the terminal. utf-string has IO functions
-      which can fix this, though I do not know have to use them here. It's
-      a complex issue; see
-      <http://www.haskell.org/pipermail/xmonad/2007-September/001967.html>
-      and <http://www.haskell.org/pipermail/xmonad/2007-September/001966.html>.
-
-    * Needs more elaborate functionality: Emacs' registers are nice; if you
+   * More elaborate functionality: Emacs' registers are nice; if you
       don't know what they are, see <http://www.gnu.org/software/emacs/manual/html_node/emacs/Registers.html#Registers> -}
 
--- | Returns a String corresponding to the current mouse selection in X; if there is none, an empty string is returned. Note that this is
--- really only reliable for ASCII text and currently escapes or otherwise mangles more complex UTF-8 characters.
+-- | Returns a String corresponding to the current mouse selection in X;
+--   if there is none, an empty string is returned.
 getSelection :: MonadIO m => m String
 getSelection = io $ do
   dpy <- openDisplay ""
@@ -79,22 +69,24 @@ getSelection = io $ do
        else destroyWindow dpy win >> return ""
 
 {- | A wrapper around 'getSelection'. Makes it convenient to run a program with the current selection as an argument.
-This is convenient for handling URLs, in particular. For example, in your Config.hs you could bind a key to
+  This is convenient for handling URLs, in particular. For example, in your Config.hs you could bind a key to
          @promptSelection \"firefox\"@;
-this would allow you to highlight a URL string and then immediately open it up in Firefox.
+  this would allow you to highlight a URL string and then immediately open it up in Firefox.
 
-'promptSelection' passes strings through the system shell, \/bin\/sh; if you do not wish your selected text
-to be interpreted or mangled by the shell, use 'safePromptSelection'. safePromptSelection will bypass the
-shell using 'safeSpawn' from "XMonad.Util.Run"; see its documentation for more
-details on the advantages and disadvantages of using safeSpawn. -}
+  'promptSelection' passes strings through the system shell, \/bin\/sh; if you do not wish your selected text
+  to be interpreted or mangled by the shell, use 'safePromptSelection'. safePromptSelection will bypass the
+  shell using 'safeSpawn' from "XMonad.Util.Run"; see its documentation for more
+  details on the advantages and disadvantages of using safeSpawn. -}
 promptSelection, safePromptSelection, unsafePromptSelection :: String -> X ()
 promptSelection = unsafePromptSelection
 safePromptSelection app = join $ io $ liftM (safeSpawn app . return) getSelection
 unsafePromptSelection app = join $ io $ liftM unsafeSpawn $ fmap (\x -> app ++ " " ++ x) getSelection
 
-{- | A wrapper around 'promptSelection' and its safe variant. They take two parameters, the first is a function that transforms strings, and the second is the application to run. The transformer essentially transforms the selection in X.
-One example is to wrap code, such as a command line action copied out of the browser to be run as @"sudo" ++ cmd@ or @"su - -c \""++ cmd ++"\""@.
--}
+{- | A wrapper around 'promptSelection' and its safe variant. They take two parameters, the 
+     first is a function that transforms strings, and the second is the application to run.
+     The transformer essentially transforms the selection in X.
+     One example is to wrap code, such as a command line action copied out of the browser
+     to be run as @"sudo" ++ cmd@ or @"su - -c \""++ cmd ++"\""@. -}
 transformPromptSelection, transformSafePromptSelection :: (String -> String) -> String -> X ()
 transformPromptSelection f app = join $ io $ liftM (safeSpawn app . return) (fmap f getSelection)
 transformSafePromptSelection f app = join $ io $ liftM unsafeSpawn $ fmap (\x -> app ++ " " ++ x) (fmap f getSelection)