From 39fea312dc6cae6a8e66ba0f16015cf9e856b887 Mon Sep 17 00:00:00 2001 From: Adrian Cochrane Date: Mon, 2 Jan 2023 20:54:26 +1300 Subject: [PATCH] Documentation-compilation fixes, release v1! --- Data/Text/Glyphize.hs | 9 +++++++-- Data/Text/Glyphize/Buffer.hs | 9 +++++---- Data/Text/Glyphize/Font.hs | 32 ++++++++++++++++---------------- harfbuzz-pure.cabal | 6 +++--- 4 files changed, 31 insertions(+), 25 deletions(-) diff --git a/Data/Text/Glyphize.hs b/Data/Text/Glyphize.hs index 987af14..3f04f3d 100644 --- a/Data/Text/Glyphize.hs +++ b/Data/Text/Glyphize.hs @@ -1,3 +1,8 @@ +-- | HarfBuzz is a text shaping library. +-- Using the HarfBuzz library allows programs to convert a sequence of +-- Unicode input into properly formatted and positioned glyph output — +-- for any writing system and language. +-- See `shape` for the central function all other datatypes serves to support. module Data.Text.Glyphize (shape, version, versionAtLeast, versionString, Buffer(..), ContentType(..), ClusterLevel(..), Direction(..), defaultBuffer, @@ -55,8 +60,8 @@ foreign import ccall "hb_shape" hb_shape :: Font_ -> Buffer' -> Ptr Feature -> W -- character in the buffer that has a script other than "common", "inherited", -- or "unknown". -- Next if the buffer direction is not set it will be set to the natural --- horizontal direction of the buffer script as returned by `scriptHorizontalDirection`. --- If `scriptHorizontalDirection` returns `Nothing`, then `DirLTR` is used. +-- horizontal direction of the buffer script as returned by `scriptHorizontalDir`. +-- If `scriptHorizontalDir` returns `Nothing`, then `DirLTR` is used. -- Finally if buffer language is not set, it will be set to the process's default -- language as returned by `languageDefault`. This may change in the future by -- taking buffer script into consideration when choosting a language. diff --git a/Data/Text/Glyphize/Buffer.hs b/Data/Text/Glyphize/Buffer.hs index f173d3e..9fb1ae3 100644 --- a/Data/Text/Glyphize/Buffer.hs +++ b/Data/Text/Glyphize/Buffer.hs @@ -2,7 +2,7 @@ module Data.Text.Glyphize.Buffer where import qualified Data.Text.Internal.Lazy as Lazy -import qualified Data.Text.Lazy as Lazy +import qualified Data.Text.Lazy as Lazy (Text, pack) import qualified Data.Text.Internal as Txt import Data.Char (toUpper, toLower) import Control.Monad (forM) @@ -34,6 +34,7 @@ import Foreign.Storable.Generic (GStorable(..)) data Buffer = Buffer { text :: Lazy.Text, -- ^ The Unicode text, in visual order, for HarfBuzz to convert into glyphs. + -- See https://hackage.haskell.org/package/text-2.0.1/docs/Data-Text-Internal-Lazy.html#t:Text for details. contentType :: Maybe ContentType, -- ^ What the bytes of the ByteString contents represents, -- namely unicode characters (before shaping) or glyphs (result of shaping). @@ -117,7 +118,7 @@ defaultBuffer = Buffer { -- | The direction of a text segment or buffer. data Direction = DirLTR | DirRTL | DirTTB | DirBTT deriving (Eq, Show, Read, Ord) --- | Converts a string to an hb_direction_t. +-- | Converts a string to an `Direction`. -- Matching is loose and applies only to the first letter. For examples, -- "LTR" and "left-to-right" will both return HB_DIRECTION_LTR. dirFromStr ('L':_) = Just DirLTR @@ -129,7 +130,7 @@ dirFromStr ('t':_) = Just DirTTB dirFromStr ('B':_) = Just DirBTT dirFromStr ('b':_) = Just DirBTT dirFromStr _ = Nothing --- | Converts an hb_direction_t to a string. +-- | Converts an `Direction` to a string. dirToStr DirLTR = "ltr" dirToStr DirRTL = "rtl" dirToStr DirTTB = "ttb" @@ -167,7 +168,7 @@ int2dir 6 = Just DirTTB int2dir 7 = Just DirBTT int2dir _ = Nothing --- | Fetches the hb_direction_t of a script when it is set horizontally. +-- | Fetches the `Direction` of a script when it is set horizontally. -- All right-to-left scripts will return `DirRTL`. -- All left-to-right scripts will return `DirLTR`. -- Scripts that can be written either horizontally or vertically will return `Nothing`. diff --git a/Data/Text/Glyphize/Font.hs b/Data/Text/Glyphize/Font.hs index 6b4c391..3349650 100644 --- a/Data/Text/Glyphize/Font.hs +++ b/Data/Text/Glyphize/Font.hs @@ -5,7 +5,7 @@ import Data.ByteString.Internal (ByteString(..)) import Data.ByteString (packCStringLen) import Data.Word (Word8, Word32) import Data.Int (Int32) -import FreeType.Core.Base (FT_Face) +import FreeType.Core.Base (FT_Face, frSize) import Data.Text.Glyphize.Buffer (tag_to_string, tag_from_string, Direction, dir2int) import Control.Monad (forM, unless) @@ -37,7 +37,7 @@ data Feature = Feature { featValue :: Word32, -- ^ The value of the feature. -- 0 disables the feature, non-zero (usually 1) enables the feature. - -- For features implemented as lookup type 3 (like 'salt') the value + -- For features implemented as lookup type 3 (like "salt") the value -- is a one based index into the alternates. featStart :: Word, -- ^ The cluster to start applying this feature setting (inclusive). @@ -47,7 +47,7 @@ data Feature = Feature { instance GStorable Feature -- | Parses a string into a hb_feature_t. -- The format for specifying feature strings follows. All valid CSS --- font-feature-settings values other than 'normal' and the global values +-- font-feature-settings values other than "normal" and the global values -- are also accepted. CSS string escapes are not supported. -- See https://harfbuzz.github.io/harfbuzz-hb-common.html#hb-feature-from-string -- for additional details. @@ -73,14 +73,14 @@ foreign import ccall "hb_feature_to_string" hb_feature_to_string -- [OpenType Axis Tag Registry](https://docs.microsoft.com/en-us/typography/opentype/spec/dvaraxisreg). data Variation = Variation { varTag' :: Word32, - -- ^ Tag of the variation-axis name. Use `verTag` to decode as an ASCII string. + -- ^ Tag of the variation-axis name. Use `varTag` to decode as an ASCII string. varValue :: Float -- ^ Value of the variation axis. } deriving (Read, Show, Generic) instance GStorable Variation -- | Parses a string into a hb_variation_t. -- The format for specifying variation settings follows. --- All valid CSS font-variation-settings values other than 'normal' and 'inherited' +-- All valid CSS font-variation-settings values other than "normal" and "inherited" -- are also accepted, though, not documented below. -- The format is a tag, optionally followed by an equals sign, followed by a number. -- For example wght=500, or slnt=-7.5. @@ -128,9 +128,9 @@ data Face' -- can contain more than one face. Face indices within such collections are zero-based. -- Note: If the blob font format is not a collection, index is ignored. Otherwise, -- only the lower 16-bits of index are used. The unmodified index can be accessed --- via hb_face_get_index(). --- Note: The high 16-bits of index, if non-zero, are used by hb_font_create() to --- load named-instances in variable fonts. See hb_font_create() for details. +-- via `faceIndex`. +-- Note: The high 16-bits of index, if non-zero, are used by `createFont` to +-- load named-instances in variable fonts. See `createFont` for details. createFace :: ByteString -> Word -> Face createFace bytes index = unsafePerformIO $ do blob <- bs2blob bytes @@ -320,10 +320,10 @@ foreign import ccall "hb_font_create" hb_font_create :: Face_ -> IO Font_ foreign import ccall "hb_font_make_immutable" hb_font_make_immutable :: Font_ -> IO () foreign import ccall "&hb_font_destroy" hb_font_destroy :: FunPtr (Font_ -> IO ()) --- | Creates an hb_font_t font object from the specified FT_Face. +-- | Creates an `Font` object from the specified FT_Face. -- Note: You must set the face size on ft_face before calling `ftCreateFont` on it. -- HarfBuzz assumes size is always set --- and will access `size` member of `FT_Face` unconditionally. +-- and will access `frSize`` member of `FT_Face` unconditionally. ftCreateFont :: FT_Face -> IO Font ftCreateFont fce = do font <- hb_ft_font_create_referenced fce @@ -353,8 +353,8 @@ fontFace font = unsafePerformIO $ withForeignPtr font $ \font' -> do newForeignPtr_ face' -- FIXME: Keep the font alive... foreign import ccall "hb_font_get_face" hb_font_get_face :: Font_ -> IO Face_ - -- | Fetches the glyph ID for a Unicode codepoint in the specified `Font`, - -- with an optional variation selector. +-- | Fetches the glyph ID for a Unicode codepoint in the specified `Font`, +-- with an optional variation selector. fontGlyph :: Font -> Char -> Maybe Char -> Maybe Word32 fontGlyph font char var = unsafePerformIO $ withForeignPtr font $ \font' -> alloca $ \ret -> do @@ -440,7 +440,7 @@ foreign import ccall "hb_font_get_glyph_extents" hb_font_get_glyph_extents -- | Fetches the `GlyphExtents` data for a glyph ID in the specified `Font`, -- with respect to the origin in a text segment in the specified direction. -- Calls the appropriate direction-specific variant (horizontal or vertical) --- depending on the value of `dir`. +-- depending on the value of given `Direction`. fontGlyphExtentsForOrigin :: Font -> Word32 -> Maybe Direction -> Maybe GlyphExtents fontGlyphExtentsForOrigin font glyph dir = unsafePerformIO $ withForeignPtr font $ \font' -> alloca $ \ret -> do @@ -517,7 +517,7 @@ foreign import ccall "hb_font_get_glyph_v_origin" hb_font_get_glyph_v_origin :: -- | Fetches the kerning-adjustment value for a glyph-pair in the specified `Font`. -- Calls the appropriate direction-specific variant (horizontal or vertical) --- depending on the value of `dir`. +-- depending on the value of given `Direction`. fontGlyphKerningForDir :: Font -> Word32 -> Word32 -> Maybe Direction -> (Int32, Int32) fontGlyphKerningForDir font a b dir = unsafePerformIO $ withForeignPtr font $ \font' -> alloca $ \x' -> alloca $ \y' -> do @@ -529,7 +529,7 @@ foreign import ccall "hb_font_get_glyph_kerning_for_direction" hb_font_get_glyph_kerning_for_direction :: Font_ -> Word32 -> Word32 -> Int -> Ptr Int32 -> Ptr Int32 -> IO () --- | Fetches the glyph-name string for a glyph ID in the specified `font`. +-- | Fetches the glyph-name string for a glyph ID in the specified `Font`. fontGlyphName :: Font -> Word32 -> Maybe String fontGlyphName a b = fontGlyphName_ a b 32 -- | Variant of `fontGlyphName` which lets you specify the maximum of the return value. @@ -546,7 +546,7 @@ foreign import ccall "hb_font_get_glyph_name" hb_font_get_glyph_name :: -- | Fetches the (X,Y) coordinates of the origin for a glyph in the specified `Font`. -- Calls the appropriate direction-specific variant (horizontal or vertical) --- depending on the value of `dir`. +-- depending on the value of given `Direction`. fontGlyphOriginForDir :: Font -> Word32 -> Maybe Direction -> (Int32, Int32) fontGlyphOriginForDir font glyph dir = unsafePerformIO $ withForeignPtr font $ \font' -> alloca $ \x' -> alloca $ \y' -> do diff --git a/harfbuzz-pure.cabal b/harfbuzz-pure.cabal index 47425b7..f4004ea 100644 --- a/harfbuzz-pure.cabal +++ b/harfbuzz-pure.cabal @@ -10,7 +10,7 @@ name: harfbuzz-pure -- PVP summary: +-+------- breaking API changes -- | | +----- non-breaking API additions -- | | | +--- code changes with no API change -version: 0.1.0.0 +version: 1.0.0.0 -- A short (one-line) description of the package. synopsis: Pure-functional Harfbuzz language bindings @@ -51,10 +51,10 @@ cabal-version: >=1.10 library -- Modules exported by the library. - exposed-modules: Data.Text.Glyphize, Data.Text.Glyphize.Buffer, Data.Text.Glyphize.Font + exposed-modules: Data.Text.Glyphize -- Modules included in this library but not exported. - -- other-modules: + other-modules: Data.Text.Glyphize.Buffer, Data.Text.Glyphize.Font -- LANGUAGE extensions used by modules in this package. -- other-extensions: -- 2.30.2