From 78af4a329e8d368e2aa0b7ba44990876ae257c09 Mon Sep 17 00:00:00 2001 From: Alec Theriault Date: Wed, 13 Feb 2019 08:43:35 -0500 Subject: Properly escape character literals in Haddocks Character literals in Haddock should not be written as plain `'\n'` since single quotes are for linking identifiers. Besides, since we want the character literal to be monospaced, we really should use `@\'\\n\'@`. [skip ci] --- compiler/basicTypes/Literal.hs | 2 +- compiler/utils/StringBuffer.hs | 8 ++++---- libraries/base/GHC/IO/Device.hs | 2 +- libraries/base/GHC/IO/Encoding.hs | 2 +- libraries/base/GHC/IO/Handle/Types.hs | 12 ++++++------ libraries/base/GHC/ResponseFile.hs | 2 +- libraries/base/System/IO.hs | 10 +++++----- 7 files changed, 19 insertions(+), 19 deletions(-) diff --git a/compiler/basicTypes/Literal.hs b/compiler/basicTypes/Literal.hs index 7e49816d1f..b3644ee6d3 100644 --- a/compiler/basicTypes/Literal.hs +++ b/compiler/basicTypes/Literal.hs @@ -114,7 +114,7 @@ data Literal | LitString ByteString -- ^ A string-literal: stored and emitted -- UTF-8 encoded, we'll arrange to decode it - -- at runtime. Also emitted with a @'\0'@ + -- at runtime. Also emitted with a @\'\\0\'@ -- terminator. Create with 'mkLitString' | LitNullAddr -- ^ The @NULL@ pointer, the only pointer value diff --git a/compiler/utils/StringBuffer.hs b/compiler/utils/StringBuffer.hs index a5fc4e7f12..64578bffde 100644 --- a/compiler/utils/StringBuffer.hs +++ b/compiler/utils/StringBuffer.hs @@ -81,7 +81,7 @@ data StringBuffer cur :: {-# UNPACK #-} !Int -- current pos } -- The buffer is assumed to be UTF-8 encoded, and furthermore - -- we add three '\0' bytes to the end as sentinels so that the + -- we add three @\'\\0\'@ bytes to the end as sentinels so that the -- decoder doesn't have to check for overflow at every single byte -- of a multibyte sequence. @@ -187,7 +187,7 @@ stringToStringBuffer str = -- the remaining portion (analogous to 'Data.List.uncons'). __Warning:__ The -- behavior is undefined if the 'StringBuffer' is empty. The result shares -- the same buffer as the original. Similar to 'utf8DecodeChar', if the --- character cannot be decoded as UTF-8, '\0' is returned. +-- character cannot be decoded as UTF-8, @\'\\0\'@ is returned. {-# INLINE nextChar #-} nextChar :: StringBuffer -> (Char,StringBuffer) nextChar (StringBuffer buf len (I# cur#)) = @@ -202,7 +202,7 @@ nextChar (StringBuffer buf len (I# cur#)) = -- | Return the first UTF-8 character of a nonempty 'StringBuffer' (analogous -- to 'Data.List.head'). __Warning:__ The behavior is undefined if the -- 'StringBuffer' is empty. Similar to 'utf8DecodeChar', if the character --- cannot be decoded as UTF-8, '\0' is returned. +-- cannot be decoded as UTF-8, @\'\\0\'@ is returned. currentChar :: StringBuffer -> Char currentChar = fst . nextChar @@ -285,7 +285,7 @@ skipToLine !line !len !op0 = go 1 op0 -- | Decode the first @n@ bytes of a 'StringBuffer' as UTF-8 into a 'String'. -- Similar to 'utf8DecodeChar', if the character cannot be decoded as UTF-8, --- they will be replaced with '\0'. +-- they will be replaced with @\'\\0\'@. lexemeToString :: StringBuffer -> Int -- ^ @n@, the number of bytes -> String diff --git a/libraries/base/GHC/IO/Device.hs b/libraries/base/GHC/IO/Device.hs index e33dcd02b1..024ff7bbbb 100644 --- a/libraries/base/GHC/IO/Device.hs +++ b/libraries/base/GHC/IO/Device.hs @@ -139,7 +139,7 @@ data IODeviceType = Directory -- ^ The standard libraries do not have direct support -- for this device type, but a user implementation is -- expected to provide a list of file names in - -- the directory, in any order, separated by @'\0'@ + -- the directory, in any order, separated by @\'\\0\'@ -- characters, excluding the @"."@ and @".."@ names. See -- also 'System.Directory.getDirectoryContents'. Seek -- operations are not supported on directories (other diff --git a/libraries/base/GHC/IO/Encoding.hs b/libraries/base/GHC/IO/Encoding.hs index b734f00f5b..735c1b0a37 100644 --- a/libraries/base/GHC/IO/Encoding.hs +++ b/libraries/base/GHC/IO/Encoding.hs @@ -57,7 +57,7 @@ import System.IO.Unsafe (unsafePerformIO) -- | The Latin1 (ISO8859-1) encoding. This encoding maps bytes -- directly to the first 256 Unicode code points, and is thus not a -- complete Unicode encoding. An attempt to write a character greater than --- '\255' to a 'System.IO.Handle' using the 'latin1' encoding will result in an +-- @\'\\255\'@ to a 'System.IO.Handle' using the 'latin1' encoding will result in an -- error. latin1 :: TextEncoding latin1 = Latin1.latin1_checked diff --git a/libraries/base/GHC/IO/Handle/Types.hs b/libraries/base/GHC/IO/Handle/Types.hs index f994e92b97..aeb72af847 100644 --- a/libraries/base/GHC/IO/Handle/Types.hs +++ b/libraries/base/GHC/IO/Handle/Types.hs @@ -351,8 +351,8 @@ and hence it is only possible on a seekable Handle. -- Newline translation -- | The representation of a newline in the external file or stream. -data Newline = LF -- ^ '\n' - | CRLF -- ^ '\r\n' +data Newline = LF -- ^ @\'\\n\'@ + | CRLF -- ^ @\'\\r\\n\'@ deriving ( Eq -- ^ @since 4.2.0.0 , Ord -- ^ @since 4.3.0.0 , Read -- ^ @since 4.3.0.0 @@ -361,9 +361,9 @@ data Newline = LF -- ^ '\n' -- | Specifies the translation, if any, of newline characters between -- internal Strings and the external file or stream. Haskell Strings --- are assumed to represent newlines with the '\n' character; the --- newline mode specifies how to translate '\n' on output, and what to --- translate into '\n' on input. +-- are assumed to represent newlines with the @\'\\n\'@ character; the +-- newline mode specifies how to translate @\'\\n\'@ on output, and what to +-- translate into @\'\\n\'@ on input. data NewlineMode = NewlineMode { inputNL :: Newline, -- ^ the representation of newlines on input @@ -385,7 +385,7 @@ nativeNewline = CRLF nativeNewline = LF #endif --- | Map '\r\n' into '\n' on input, and '\n' to the native newline +-- | Map @\'\\r\\n\'@ into @\'\\n\'@ on input, and @\'\\n\'@ to the native newline -- represetnation on output. This mode can be used on any platform, and -- works with text files using any newline convention. The downside is -- that @readFile >>= writeFile@ might yield a different file. diff --git a/libraries/base/GHC/ResponseFile.hs b/libraries/base/GHC/ResponseFile.hs index 804bd44ff7..1b6c2b8647 100644 --- a/libraries/base/GHC/ResponseFile.hs +++ b/libraries/base/GHC/ResponseFile.hs @@ -100,7 +100,7 @@ unescapeArgs = filter (not . null) . unescape escapeArgs :: [String] -> String escapeArgs = unlines . map escapeArg --- | Arguments which look like '@foo' will be replaced with the +-- | Arguments which look like @\@foo@ will be replaced with the -- contents of file @foo@. A gcc-like syntax for response files arguments -- is expected. This must re-constitute the argument list by doing an -- inverse of the escaping mechanism done by the calling-program side. diff --git a/libraries/base/System/IO.hs b/libraries/base/System/IO.hs index 900963a045..1fc39bed25 100644 --- a/libraries/base/System/IO.hs +++ b/libraries/base/System/IO.hs @@ -197,19 +197,19 @@ module System.IO ( -- * Newline conversion -- | In Haskell, a newline is always represented by the character - -- '\n'. However, in files and external character streams, a + -- @\'\\n\'@. However, in files and external character streams, a -- newline may be represented by another character sequence, such - -- as '\r\n'. + -- as @\'\\r\\n\'@. -- -- A text-mode 'Handle' has an associated 'NewlineMode' that -- specifies how to transate newline characters. The -- 'NewlineMode' specifies the input and output translation - -- separately, so that for instance you can translate '\r\n' - -- to '\n' on input, but leave newlines as '\n' on output. + -- separately, so that for instance you can translate @\'\\r\\n\'@ + -- to @\'\\n\'@ on input, but leave newlines as @\'\\n\'@ on output. -- -- The default 'NewlineMode' for a 'Handle' is -- 'nativeNewlineMode', which does no translation on Unix systems, - -- but translates '\r\n' to '\n' and back on Windows. + -- but translates @\'\\r\\n\'@ to @\'\\n\'@ and back on Windows. -- -- Binary-mode 'Handle's do no newline translation at all. -- -- cgit v1.2.1