-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Plotter-like fonts i.e. a series of straight lines which make letter shapes.
--   
@package plotfont
@version 0.1.0.1


-- | <h2>Rationale</h2>
--   
--   There are many good looking fonts which optimize for appearance. I
--   wanted some cruder fonts which had a simpler representation: a
--   relatively small number of straight lines which could easily be
--   plotted by a machine, or perhaps a person.
--   
--   So this might be a good package for you if you're going to do
--   something with the coordinates afterwards, but not if you just want to
--   render some text.
--   
--   <h2>Example</h2>
--   
--   Here is an example using <tt>Diagrams</tt> to generate a SVG file:
--   
--   <pre>
--   import qualified Graphics.PlotFont as PF
--   
--   import Diagrams.Prelude
--   import Diagrams.Backend.SVG
--   
--   strokes :: [[(Double,Double)]]    
--   strokes = PF.render' PF.canvastextFont "Hello World!"
--   
--   toDiag :: [[(Double,Double)]] -&gt; Diagram SVG
--   toDiag = extrudeLeft 20 . mconcat . map (fromVertices . map p2)
--   
--   main :: IO ()         
--   main = renderSVG "hello.svg" (mkSizeSpec2D (Just 800) (Just 200)) $
--             toDiag strokes # lw 3
--   </pre>
--   
--   <h2>License discussion</h2>
--   
--   My code is licensed under the GPL version 2 or later see
--   <a>http://www.gnu.org/copyleft/gpl.html</a>
--   
--   The data in canvasText and fallbackGlyph come from Jim Studt's
--   canvastext.js: <a>http://jim.studt.net/canvastext/</a> which he placed
--   in the public domain. He cites the original source as the Hershey
--   fonts: <a>https://en.wikipedia.org/wiki/Hershey_fonts</a>
--   
--   The Hershey fonts appear to have this license:
--   
--   <ol>
--   <li>The following acknowledgements must be distributed with the font
--   data: - The Hershey Fonts were originally created by Dr. A. V. Hershey
--   while working at the U. S. National Bureau of Standards. - The format
--   of the Font data in this distribution was originally created by James
--   Hurt Cognition, Inc. 900 Technology Park Drive Billerica, MA 01821
--   (mit-eddie!ci-dandelion!hurt)</li>
--   <li>The font data in this distribution may be converted into any other
--   format *EXCEPT* the format distributed by the U.S. NTIS (which
--   organization holds the rights to the distribution and use of the font
--   data in that particular format). Not that anybody would really *want*
--   to use their format... each point is described in eight bytes as "xxx
--   yyy:", where xxx and yyy are the coordinate values as ASCII
--   numbers.</li>
--   </ol>
--   
--   It is not clear to me if Mr Studt used 'this distribution'.
module Graphics.PlotFont

-- | The <a>PlotFont</a> type wraps the basic font: a map from <a>Char</a>
--   to <a>PFGlyph</a>
data PlotFont
type PFWidth = Double
type PFPoint = (Double, Double)

-- | <a>PFStroke</a> is the basic graphic element: a series of points
--   joined by straight lines.
type PFStroke = [PFPoint]

-- | <a>PFGlyph</a> is the basic element of the font: the symbol's width,
--   plus the strokes we need to draw it.
type PFGlyph = (PFWidth, [PFStroke])

-- | Given a <a>PlotFont</a> and a <a>String</a>, return
--   
--   <ul>
--   <li><a>Right</a> strokes if the <a>String</a> can be rendered.</li>
--   <li><a>Left</a> error otherwise.</li>
--   </ul>
render :: PlotFont -> String -> Either String [PFStroke]

-- | A varient of <a>render</a> which replaces unknown characters with a
--   question mark.
--   
--   It is guaranteed to render something, and thus useful if you want to
--   ignore the possibility of errors e.g. because you're manually checking
--   the output.
render' :: PlotFont -> String -> [PFStroke]

-- | Given a set of strokes, try to optimize their order and direction so
--   as to prefer:
--   
--   <ul>
--   <li>fewer strokes;</li>
--   <li>smaller gaps between strokes;</li>
--   <li>left-most starting position;</li>
--   <li>bottom-most starting position.</li>
--   </ul>
--   
--   The code does a reasonable job of improving fonts where no thought has
--   been given to this, but hand-tweaking is still better.
optimizeStrokes :: [PFStroke] -> [PFStroke]

-- | The Hershey font used by <a>canvastext.js</a> which provides
--   <tt>!"#$%&amp;()*+,-./0123456789:;&lt;=&gt;?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[]^_`abcdefghijklmnopqrstuvwxyz{|}~</tt>
canvastextFont :: PlotFont