packages feed

wumpus-core 0.34.0 → 0.35.0

raw patch · 8 files changed

+121/−86 lines, 8 filesPVP ok

version bump matches the API change (PVP)

API changes (from Hackage documentation)

Files

CHANGES view
@@ -1,4 +1,25 @@ +0.34.0 to 0.35.0:++  * Bug fix - PostScript output - when more than one stroke +    property changed the changes were concatenated without +    a separator. This generated invalid PostScript. Now fixed.++  * Documentation updates to the guide and the Haddock docs.++0.33.0 to 0.34.0:++  * Clipping paths fixed. Previously they did not work for SVG or+    PostScript.++  * @picOver@ fixed. Drawing order was changed in version 0.33.0, +    but @picOver@ was not updated accordingly (so it actually +    started drawing pictures /under/). It now works correctly.++  * The lexer for escape characters embedded in label strings has +    been rewritten. It now supports octal and hexadecimal codes.+  + 0.32.0 to 0.33.0:    * Major change - reworked support for text encoding. Encoding
doc-src/Guide.lhs view
@@ -23,6 +23,8 @@ \section{About \wumpuscore}
 %-----------------------------------------------------------------
 
+This guide was last updated for \wumpuscore version 0.35.0.
+
 \wumpuscore is a Haskell library for generating 2D vector 
 pictures. It was written with portability as a priority, so it has 
 no dependencies on foreign C libraries. Output to PostScript and 
@@ -30,8 +32,9 @@ 
 \wumpuscore is rather primitive, the basic drawing objects are 
 paths and text labels. A second library \texttt{wumpus-basic}
-contains code for higher level drawing but it is still missing 
-main functionalities e.g. connectors, arrowheads.
+contains code for higher level drawing but it experimental and the 
+APIs are a long way from stable (it should probably be considered 
+a \emph{technology preview}).
 
 Although \wumpuscore is heavily inspired by PostScript it avoids 
 PostScript's notion of an (implicit) current point and the 
@@ -63,32 +66,43 @@ \item[\texttt{Wumpus.Core.BoundingBox.}]
 Data type representing bounding boxes and operations on them. 
 Bounding boxes are important for Pictures and they support the 
-definition of \emph{Picture composition operators}.
+definition of \emph{picture composition} operators.
 
 \item[\texttt{Wumpus.Core.Colour.}]
 A single colour type \texttt{RGBi} is supported. This type defines 
-colour as a triple of integers (Word8) - black is 0, 0, 0; white 
-is 255, 255, 255.  Some named colours are defined, although they 
-are hidden by the top level shim module to avoid name clashes. 
+colour as a triple of integers (Word8) - black is (0, 0, 0); white 
+is (255, 255, 255). Some named colours are defined, although they 
+are hidden by the top level shim module to avoid name clashes with
+libraries providing more extensive lists of colours. 
 \texttt{Wumpus.Core.Colour} can be imported directly if the named 
 colours are required.
 
 \item[\texttt{Wumpus.Core.FontSize.}]
-Various calculations for font size metrics. Generally not useful 
-to a user but exposed so that variations of the standard Label 
-type are possible.
+Various calculations for font size metrics. \wumpuscore has 
+limited handling of font / character size as it cannot interpret
+the metrics within font files (doing so would be a huge task).
+Instead this module provides some metrics based on the Courier
+mono-spaced font that can be used for rudimentary size
+calculations on text labels.
 
 \item[\texttt{Wumpus.Core.Geometry.}]
-Usual types an operations from affine geometry - points, vectors 
-and frames. The \texttt{Pointwise} type class which is essential
-for defining transformable drawable types. 
+The usual types an operations from affine geometry - points, 
+vectors and 3x3 matrices. Also the \texttt{DUnit} type family - 
+essentially this type family is a trick used heavily within 
+\wumpuscore to avoid annotating class declarations with 
+constraints on the unit, class constraints like 
+\texttt{Fractional u} can then be shifted to the instance 
+declaration rather than the class declaration.
 
 \item[\texttt{Wumpus.Core.GraphicsState.}]
 Data types modelling the attributes of PostScript's graphics 
-state (stroke style, dash pattern, etc.). Note \wumpuscore 
-annotates primitives - paths, text labels - with their rendering 
-style. PostScript has a mutable graphics state, changing via 
-inheritance how the curent object is drawn.
+state (stroke style, dash pattern, etc.). Note that 
+\wumpuscore annotates all primitives - paths, text labels - with 
+their rendering style, the \texttt{GraphicsState} here is an 
+internal detail used to generate more efficient PostScript and 
+SVG. The \emph{smaller} types in this module such as 
+\texttt{StrokeAttr} are the only ones relevant for the public 
+API.
 
 \item[\texttt{Wumpus.Core.OutputPostScript.}]
 Functions to write PostScript or encapsulated PostScript files.
@@ -110,8 +124,14 @@ type to represent them.
 
 \item[\texttt{Wumpus.Core.TextEncoder.}]
-Types for handling non-ASCII character codes. This module is
-perhaps under-cooked although it appears adequate for Latin-1.
+Types for handling extended character codes e.g. for accented 
+characters or the Symbol font. Special characters generally have 
+to be escaped in the PostScript and SVG output, this module 
+provides data types for lookup tables between the escaped 
+character code and its PostScript or SVG representation. 
+Text encoders are associated with fonts - glyphs within a font 
+are located by their character name / code. Currently 
+\wumpuscore has encoders for Latin1 and the Symbol font. 
 
 \item[\texttt{Wumpus.Core.TextLatin1.}]
 A instance of the TextEncoder type for mapping Latin 1 characters
@@ -120,7 +140,10 @@ Times-Roman.
 
 \item[\texttt{Wumpus.Core.TextSymbol.}]
-A instance of the TextEncoder type for the Symbol font.
+A instance of the TextEncoder type for the Symbol font. Note, 
+unfortunately escape codes for the Symbol font seem to cause
+problems for some SVG renderers. Chrome appears fine, but Safari 
+and Firefox currently have problems.
 
 \item[\texttt{Wumpus.Core.VersionNumber.}]
 Current version number of \wumpuscore.
@@ -147,14 +170,16 @@ 
 Primitives are attributed with drawing styles - font name and 
 size for labels; line width, colour, etc. for paths. Drawing 
-Primitives is unfortunately complicated due to the need to 
+\emph{primitives} is unfortunately complicated due to the need to 
 support hyperlinks in SVG output. Primitives have to be lifted 
 to a \texttt{PrimElement} before they can be placed within a 
-\texttt{Picture} - using the shorthand constructors in 
-\texttt{Wumpus.Core.Picture} does this lifting automatically.
-The function \texttt{frame} assembles a list of primitives 
-into a \texttt{Picture} with a standard affine frame where the 
-origin is at (0,0) and the X and Y axes have the unit bases. 
+\texttt{Picture} - in practive this lifting is done automatically 
+by using the shorthand constructors in 
+\texttt{Wumpus.Core.Picture}. The function \texttt{frame} 
+assembles a list of primitives into a \texttt{Picture} with the 
+standard affine frame where the origin is at (0,0) and the X and 
+Y axes have the unit bases (i.e. they have a \emph{scaling} value 
+of 1). 
 
 \begin{figure}
 \centering
@@ -165,7 +190,7 @@ \wumpuscore uses the same picture frame as PostScript where 
 the origin at the bottom left, see Figure 1. This contrasts to SVG 
 where the origin at the top-left. When \wumpuscore generates SVG, 
-the whole picture is produced within a matrix transformation 
+the whole picture is generated within a matrix transformation 
 [ 1.0, 0.0, 0.0, -1.0, 0.0, 0.0 ] that changes the picture to use 
 PostScript coordinates. This has the side-effect that text is 
 otherwise drawn upside down, so \wumpuscore adds a rectifying 
@@ -175,14 +200,15 @@ transformable with the usual affine transformations (scaling, 
 rotation, translation).
 
-Once assembled into pictures graphics properties (e.g. colour) 
-are opaque - it is not possible to write a transformation function
-that turns a picture blue. In some ways this is a limitation - 
-for instance, the \texttt{Diagrams} library appears to support 
-some notion of attribute overriding; however it does keep 
-\wumpuscore conceptually simple. If one wanted to draw blue or red 
-arrows with \wumpuscore, one would make drawing colour a parameter 
-of the arrow creation function.
+Graphics properties (e.g colour) are opaque once primitives are
+assembled into pictures - it is not possible to write a 
+transformation function that turns elements in a picture blue. 
+In some ways this is a limitation - for instance, the 
+\texttt{Diagrams} library appears to support some notion of 
+attribute overriding; however avoiding mutable attributes does 
+keep this part of \wumpuscore conceptually simple. If one wanted 
+to draw blue or red arrows with \wumpuscore, one would make the 
+drawing colour a parameter of the arrow creation function.
 
 %-----------------------------------------------------------------
 \section{Affine transformations}
@@ -224,9 +250,10 @@ SVG. This means transformations can generally be located in the 
 output if a picture needs to be debugged, though as this might 
 not be very helpful in practice. Internally \wumpuscore only 
-performs the transformation on the pictures bounding box - it 
-needs to do this so transformed pictures can still be composed 
-with the \texttt{picBeside} combinator.
+performs the transformation on the bounding box of a picture - it 
+needs to do this to maintain the size metrics of a picture 
+allowing transformed pictures to be composed with picture 
+composition operators like the \texttt{picBeside} combinator.
 
 PostScript uses column-major form and uses a six element matrix
 rather than a nine element one. The translation matrix above 
@@ -265,7 +292,7 @@ a significant development effort, probably larger than the effort 
 put into \wumpuscore itself; for \wumpuscore's intended use - 
 producing diagrams and pictures rather than high quality text - 
-its primitive font handling is not such a draw back.
+the primitive font handling is not such a draw back.
 
 
 In both PostScript and SVG mis-named fonts can cause somewhat
@@ -273,16 +300,13 @@ font but not always. At worst, PostScript may do no subsequent 
 drawing after a font load error. \wumpuscore uses @scalefont@ in 
 the generated PostScript, this semingly works for any integer size 
-and not just the regular font sizes (10, 12, 18, 24, 36). Older 
-versions of \wumpuscore mention that using non-standard sizes may 
-cause font loading problems, however this does not appear to be 
-the case.
+and not just the regular font sizes (10, 12, 18, 24, 36). 
 
 
 The following table lists PostScript fonts and their SVG 
 equivalents, the package \texttt{wumpus-basic} includes a module 
 \texttt{Wumpus.Basic.SafeFonts} encoding the fonts in this list 
-to avoid typographical slips.
+and matching them to their appropriate \texttt{TextEncoder}.
 
 
 \begin{tabular}{ l l }
doc/Guide.pdf view

binary file changed (57051 → 59489 bytes)

src/Wumpus/Core/OutputPostScript.hs view
@@ -461,7 +461,7 @@  deltaStrokeAttrs :: StrokeAttr -> PsMonad Doc deltaStrokeAttrs sa = -    (\d1 d2 d3 d4 d5 -> hcat $ catMaybes [d1,d2,d3,d4,d5])  +    (\d1 d2 d3 d4 d5 -> vcat $ catMaybes [d1,d2,d3,d4,d5])         <$> lw <*> ml <*> lc <*> lj <*> dp   where     lw = let d = line_width sa in
src/Wumpus/Core/Picture.hs view
@@ -343,6 +343,12 @@ -- -- The supplied point is the left baseline. --+-- \*\* CAUTION \*\* - @hkernlabel@ generates a coordinate list +-- for X-positions rather than a single start point. This is +-- perfectly valid SVG, but it is not universally supported by +-- renderers. Chrome support is fine, but Firefox and Safari +-- currently seem lacking. +-- hkernlabel :: Num u              => RGBi -> FontAttr -> [KerningChar u] -> Point2 u              -> PrimElement u@@ -371,6 +377,12 @@ -- The charcters should not contain newline or tab characters. -- -- The supplied point is the left baseline of the top character.+--+-- \*\* CAUTION \*\* - @vkernlabel@ generates a coordinate list +-- for Y-positions rather than a single start point. This is +-- perfectly valid SVG, but it is not universally supported by +-- renderers. Chrome support is fine, but Firefox and Safari +-- currently seem lacking.  -- vkernlabel :: Num u              => RGBi -> FontAttr -> [KerningChar u] -> Point2 u
src/Wumpus/Core/TextEncoder.hs view
@@ -23,6 +23,13 @@ -- In Wumpus both character names and character codes can -- be embedded in strings - (e.g. @ &\#egrave; or &\#232; @). --+-- Character codes can be also be expressed as octal or +-- hexadecimal:+--+-- > myst&#0o350;re+--+-- > myst&#0xE8;re+-- -- In the generated PostScript, Wumpus uses the character name,  -- e.g.:   --
src/Wumpus/Core/VersionNumber.hs view
@@ -22,7 +22,7 @@  -- | Version number. ----- > (0,34,0)+-- > (0,35,0) -- wumpus_core_version :: (Int,Int,Int)-wumpus_core_version = (0,34,0)+wumpus_core_version = (0,35,0)
wumpus-core.cabal view
@@ -1,5 +1,5 @@ name:             wumpus-core-version:          0.34.0+version:          0.35.0 license:          BSD3 license-file:     LICENSE copyright:        Stephen Tetley <stephen.tetley@gmail.com>@@ -16,8 +16,8 @@   efficient as the use of stack operations, i.e @gsave@ and    @grestore@, is minimized.   .-  Pictures in Wumpus are made from /paths/ and text /labels/. -  Paths themselves are made from points. The usual affine +  Wumpus makes pictures from /paths/ and text /labels/. Paths +  themselves are made from points. The usual affine    transformations (rotations, scaling, translations) can be   applied to Pictures. Unlike PostScript there is no    notion of a current point, Wumpus builds pictures in a@@ -26,12 +26,12 @@   GENERAL DRAWBACKS...   .   For actually drawing pictures, diagrams, etc. Wumpus is very -  low level. There is a supplemantary package @wumpus-basic@ +  low-level. There is a supplemantary package @wumpus-basic@    available that helps create certain types of diagram, but it is   experimental - functionality is added and dropped between -  releases.+  releases, it has no stable API.   .-  Some of the design decisions made for Wumpus-core are not +  Some of the design decisions made for @wumpus-core@ are not    sophisticated (e.g. how attributes like colour are handled,    and how the bounding boxes of text labels are calculated), so    Wumpus might be limited compared to other systems. However, @@ -46,42 +46,13 @@   .   Changelog:   .-  0.33.0 to 0.34.0:-  .-  * Clipping paths fixed. Previously they did not work for SVG or-    PostScript.-  .-  * @picOver@ fixed. Drawing order was changed in version 0.33.0, -    but @picOver@ was not updated accordingly (so it actually -    started drawing pictures /under/). It now works correctly.-  .-  * The lexer for escape characters embedded in label strings has -    been rewritten. It now supports octal and hexadecimal codes.-  .  -  0.32.0 to 0.33.0:-  .-  * Major change - reworked support for text encoding. Encoding -    maps are now linked with fonts - it was spotted that the -    Symbol font does not use the Latin1 names. The @TextEncoder@ -    data type has been changed and there is a new @FontEncoder@ -    data type. There are also new modules for the Symbol Font -    encoder table and for the /Default Encoder/ which -    accommodates both Latin1 and the Symbol font. This has also -    mandated changes to the @FontFace@ data type.-  . -  * Major change - the printing order has been changed. The first -    element in a @frame@ of Prims is draw first. This means it -    appears first in the output file (this makes sense) - it also -    means it is at the back in the Z-Order. This latter point -    might not be so intuitive, but changing the printing order at -    least makes Wumpus-Core match SVG and PostScript.-  .-  * Changed the visiblity of the new colours (yellow, cyan, -    magenta) to be hidden at the top level. They can be exposed-    by importing @Wumpus.Core.Colour@. +  0.34.0 to 0.35.0:   .-  * @Wumpus.Core.FontSize@ - added @spacerWidth@ function.+  * Bug fix - PostScript output - when more than one stroke +    property changed the changes were concatenated without +    a separator. This generated invalid PostScript. Now fixed.   .+  * Documentation updates to the guide and the Haddock docs.   .   . build-type:         Simple