Thanks to raymank26 in #diagrams for the suggestion.

Dear Brent,

We are currently in the end phase of planning the upcoming
November 2014 edition of the Haskel Communities and
Activities Report (HCAR).

For a previous edition of HCAR, you have kindly provided material
on the following topic:

• diagrams

We would very much like to receive an update from you on this topic
for inclusion in the new edition. Your contribution is important
to keep the report interesting and up-to-date, which in turn
serves the entire Haskell community.

The article from the previous report is attached to this mail.
If you update it, please use the attachment as a basis.

Completely new entries/topics are also welcome!

If you want to include Haskell code, consider using lhs2tex syntax
(http://www.andres-loeh.de/lhs2tex/). The report is compiled
in mode polycode.fmt.

Please note that images (in .jpg format) are a good opportunity to
pep up entries.

If the attached .tex source does contain code for including
images, please do not change that code (unless you want to
drop the image in question, or add a new image, of course).

In any case, please do not send us .zip archives or similar.
Plain file attachements are the way.

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Please submit your entries until Saturday, 1 November 2014.
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Thank you very much for your support. We look forward to
hearing from you.

Best,
Mihai and Alejandro.

The new semantics of trailVertices cause the example of decorateTrail in the manual to break. I think we should come up with a better example of decoratePath. Since the easiest fix to the code:

dot     = circle 1 # fc  black
dotSep  = 0.5
rowSep  = width (Dot :: D R2) + dotSep
mkRow n = hcat' (with & sep .~ dotSep) (replicate n dot)
mkTri n = cat' v (with & sep .~ rowSep & catMethod .~ Distrib) $ rows
   where
     rows = map mkRow [n, n-1 .. 1]
     v = fromDirection (1/6 @@ turn)

No longer uses the decoratePath function.

We also need to fix TriangularNumbers.lhs in the gallery, in this case a patch similar to the one above should work.

https://groups.google.com/forum/#!msg/haskell-cafe/0GQgEdMKCj0/BE54vcKh6DIJ

http://projects.haskell.org/diagrams/

Should only open a new tab. It does both currently.

Reported by @bitemyapp diagrams/diagrams#10

We register an event listener on each of the gray boxes / p elements. Clicking on a link shouldn't bubble up to the p.

(Imported from http://code.google.com/p/diagrams/issues/detail?id=20. Original issue from [email protected] on April 2, 2011, 06:46:39 PM UTC)

Once the work on core and lib settles down a bit, we'll need to start working on a nice step-by-step tutorial to guide new users through the fundamental concepts embodied in the core and how to use the tools available from the library.

We'll probably also want a tutorial about how to get involved as a contributor (i.e. how to get up and running with darcs, how to build and test, coding standards, procedure for submitting patches, etc.)

Thanks to raymank26 in IRC for the suggestion.

When I build the manual right now inline Haskell code is not showing. For example the third paragraph here. I'm not sure what is causing this. Full code blocks have the expected highlighting and links to haddocks so those parts of the system are at least working.

(Imported from http://code.google.com/p/diagrams/issues/detail?id=37. Original issue from [email protected] on June 19, 2011, 05:20:01 PM UTC)

The examples in the cairo/examples directory and web gallery are drifting out of sync. It would be nice to come up with some sort of solution that makes this less work to maintain. Not exactly sure what such a system should look like, open to ideas.

(Imported from http://code.google.com/p/diagrams/issues/detail?id=58. Original issue from [email protected] on November 6, 2011, 01:46:25 AM UTC)

The current website was just thrown together by me (Brent), and I hardly know a thing about web design. It doesn't look horrible but it doesn't look great either. If there are any designers out there who want to take a shot at a better design, go right ahead!

In order to run the source code that accompanies
the gallery images, one need at a minimum to
add

import Diagrams.Backend.XXX.CmdLine

main = mainWith (example :: Diagram B R2)

This is confusing to new comers.
Can we find a way to make the code build-able and
simultaneously use it to generate the images for the website.
Otherwise we should at least mention somewhere
how to run the source code for the gallery images.

(Imported from http://code.google.com/p/diagrams/issues/detail?id=74. Original issue from [email protected] on March 12, 2012, 01:59:57 AM UTC)

There are a number of ways that the current tutorial could be improved:

1. Include more features. E.g. it currently doesn't even talk about trails or paths at all.
2. It would be nice to organize some of it (e.g. perhaps some new material, or perhaps including a rewrite of some of the current material) around a coherent example, e.g. "Suppose we'd like to make this nice diagram here. The next three sections will walk you through the steps and concepts we need to create it.".

This could make a good project for someone wanting to contribute and confident in their writing skills but not as confident in their Haskell skills -- it would be a concrete way to contribute that wouldn't require a lot of Haskell experience, but also a way to gain some experience and understanding at the same time.

The area for backends documentation in the diagrams-core explanation is missing.

As reference, here is what @bergey explained to me about the Backend architecture

<bergey> The key pieces of writing a Backend are an instance of the Backend
         type class and one or more instances of the Renderable type class
                                                                        [09:31]
<bergey>
         http://hackage.haskell.org/package/diagrams-core-1.3.0.6/docs/Diagrams-Core-Types.html#g:16
<bergey> Typically, a Renderable instance for the Path type.  [09:32]
<bergey> When writing the Backend instance, you get to pick some types.  You
         might pick that the Result type of rendering a Diagram is an IO ()
         action which draws the Diagram.  Or something more flexible, like
         GLContext -> IO ()  [09:36]

Not sure how difficult this is to change. But right now if any errors are encountered while building diagrams embedded in the user manual, an error message is printed but the build still succeeds.

I am in http://projects.haskell.org/diagrams/doc/vector.html and want to look up fromDirection
When clicking on the command fromDirection I am linked to http://projects.haskell.org/diagrams/haddock/Diagrams-ThreeD.html#v:fromDirection where fromDirection is not specified.

1. http://projects.haskell.org/diagrams/doc/vector.html#destructing-vectors
   The magnitude function does not seem to exist anymore. Should it be replaced by the norm function?

2. http://projects.haskell.org/diagrams/doc/vector.html#vector-operations
   The function which "changes the magnitude of a vector to 1, while keeping the direction fixed." should be the normalize function rather than the normalized one?

When I'm trying to build the documentation, I sometimes get errors where an entire html file (it doesn't always print the same one) is printed out, followed by the error

diagrams-doc: panic! (the 'impossible' happened)
  (GHC version 7.10.3 for x86_64-unknown-linux):
        thread killed

Please report this as a GHC bug:  http://www.haskell.org/ghc/reportabug
diagrams-doc: Error when running Shake build system:
* dist/doc/arrow.html
Error, rule "dist//*.html" failed to build file:
  dist/doc/arrow.html

Has anyone encountered this before?

http://projects.haskell.org/diagrams/doc/manual.html#traces

At the bottom of this manual section (4.2) appears this:

:: > {-# LANGUAGE TypeFamilies #-}

import Data.Maybe (mapMaybe) > illustrateTrace :: (TrailLike a, Traced a, Semigroup a, Monoid a, V a ~ R2) => a -> a > illustrateTrace d = d <> traceLines > where > traceLines = mconcat > . mapMaybe traceLine > . iterateN 30 (rotateBy (1/60)) > $ unitX > traceLine v = (basePt ~~) <$> traceP basePt v d > basePt = p2 (0, -2) > > example > = hcat' (with & sep .~ 1) > . map illustrateTrace > $ [ square 1 > , circle 1 > , triangle 1 # rotateBy (-1/4) ||| triangle 1 # rotateBy (1/4) > ]

I think this tutorial is excellent, below are just some really small nit picks and some personal preferences.

1. Towards the bottom of the Constructing vectors section.

example = lw 0.05 . mconcat . map (fromOffsets . (:[]))
$ [ r *^ e (Rad r) | r <- [33 * tau/32, 34 * tau/32 .. 2 * tau] ]
I think the following is easier to read for those less fluent in haskell:
example = lw 0.05 . mconcat . map fromOffsets
$ [ [ r *^ e (Rad r)] | r <- [33 * tau/32, 34 * tau/32 .. 2 * tau] ]

2. Deconstructing Vectors - maybe give an example of when magnitudeSq would be useful, like if one only wanted to compare the size of two vectors.

3. Vector operations - same comment as 1) but this is just personal taste:

example = mconcat $ map (fromOffsets . (:[])) vs
where
vs = take 33 . iterate (scale (2**(1/32)) . rotateBy (1/32)) $ unitX
to:
example = mconcat $ map fromOffsets ls
where
vs = take 33 . iterate (scale (2**(1/32)) . rotateBy (1/32)) $ unitX
ls = [[x] | x <- vs]

4. I noticed that * seems to work where ^* or *^ would. Why is it dangerous to use *?

5. I think it would be a good idea to reiterate the type signature of the position function, i.e that it takes a list of pairs, (Point (V a), a) to clearly show why the TrailLike object is a list of points in the following example:

example = position . map (\p -> (p, circle 0.2 # fc green)) $ nonagon 1

6. When discussing affine space, we may want to mention that an affine function in R2 looks like y = m * x + b, which most people will be familiar with.

The manual should mention the position combinator, and it should have an example. I wouldn't have known about it if I hadn't found this issue when I was trying to figure out why decorateTrail and decoratePath were deprecated.

[Reported by Dominic, [email protected]]

Quite a lot of the links in the section on Vectors and Points seem to be broken
e.g. http://projects.haskell.org/diagrams/doc/Data-VectorSpace.html gives me
404. I would normally try and fix these myself and send a patch but I don't
feel familiar enough yet with the package to do this. Were you intending the
link to be this:
http://hackage.haskell.org/packages/archive/vector-space/0.8.2/doc/html/Data-VectorSpace.html?

The idea is to be able to write (specially marked) diagrams code within Haddock documentation, then run some sort of preprocessor over it (using diagrams-builder) which will compile the code and insert URLs referencing the images (Haddock supports <<URL>> syntax for embedded images). The images can be hosted on projects.haskell.org. The final result will be Haddock documentation with embedded images next to the code used to generate them -- these can serve as simple examples as well as illustrations of whatever is being explained in the documentation.

The tricky part is that this preprocessor needs to be idempotent. It's no good to replace the code with image URLs, because we don't want to be forced to maintain two separate versions of everything (one with diagrams code and the other with image URLs).

One idea is to just have the preprocessor look for comment sections of the form

-- <<URL>>
--
-- > foo = circle 3 # red
-- > example = foo ||| foo

that is, if you want the preprocessor to render some diagrams code, you must prefix it with a <<URL>> link (presumably the link could be garbage or empty initially). The preprocessor will then update the URL if necessary -- diagrams-builder already has a facility for computing a hash of the code to see whether it needs to be rebuilt.

Expand the code examples and add explanations, so that the tutorial's examples can be compiled without errors with GHC 7.10.

In the current state it is neccessary to either add type annotations or language pragmas (both of which are not given/explained in the tutorial) at various points in the tutorial. For Haskell beginners this might be very non-trivial to figure out.

From a didactic point of view it might be useful to add and explain type annotations to make it work, rather than language pragmas, as the types support the understanding for what's going on and they might be needed anyways when continuing to work with Diagrams. Language pragmas, however, seem quite black-magicky.

Should be pretty easy to make a search box that takes you to Hoogle, automatically adding stuff like +active, +diagrams-core, +diagrams-lib, and so on.

See https://groups.google.com/d/msg/diagrams-discuss/KYllo9A3_IQ/FWHHse3CJzcJ .

When building I have observed that the Xml2Html process continues to grow in memory use as it compiles diagrams. I'm not sure what is leaking it, but I can't really build the whole of -doc without killing everything in the middle and starting again.

The haddock links in the manual, as well as the "API" link in the sidebar link to http://projects.haskell.org/diagrams/doc/ instead of http://projects.haskell.org/haddock

In the chapter Connecting Points in the Tutorial for Arrows the word Normalized links to Diagrams-Prelude-ThreeD instead of Diagrams-Core-Types.

On the haddock-generated page for Diagrams.Util, The link to the typeclass Default in the documentation for with should go to the hackage docuentation for Data.Default.Class but instead links to a local file.

(Imported from http://code.google.com/p/diagrams/issues/detail?id=19. Original issue from [email protected] on April 2, 2011, 06:32:56 PM UTC)

Eventually we'll need a nice web page for linking to downloads, documentation, and communication channels, showing off examples, and so on.

Hakyll had a major version release in January, and the API changed substantially. There's a migration guide:

http://jaspervdj.be/hakyll/tutorials/hakyll-3-to-hakyll4-migration-guide.html

Is it worth patching diagrams-doc to use hakyll 4, or better to make clear that it needs hakyll 3.5? (3.5.3.0, the last in the 3.5 series, works for me.)

What version of Hakyll does travis-ci pull in?

The interface of several Shake functions changed sometime between 0.4 and 0.8.

ghc --make Shake.hs fails with the following errors with shake 0.8. The first error matches a change between 0.4 and 0.5; I have not checked when the others were introduced.

Shake.hs:63:15:
    Couldn't match expected type `q0 -> Action a0'
                with actual type `[t0]'
    In the first argument of `addOracle', namely `["ghc-pkg"]'
    In the expression: addOracle ["ghc-pkg"]
    In a stmt of a 'do' block:
      addOracle ["ghc-pkg"]
      $ do { (out, _) <- systemOutput
                           "ghc-pkg" ["list", "--simple-output"];
             return $ words out }

Shake.hs:73:47:
    Couldn't match expected type `FilePattern' with actual type `Char'
    Expected type: [FilePattern]
      Actual type: [Char]
    In the second argument of `getDirectoryFiles', namely `"*.hs"'
    In a stmt of a 'do' block:
      hsIcons <- getDirectoryFiles "manual/icons" "*.hs"

Shake.hs:79:50:
    Couldn't match expected type `FilePattern' with actual type `Char'
    Expected type: [FilePattern]
      Actual type: [Char]
    In the second argument of `getDirectoryFiles', namely `"*"'
    In a stmt of a 'do' block:
      staticSrc <- getDirectoryFiles "manual/static" "*"

Shake.hs:85:53:
    Couldn't match expected type `FilePattern' with actual type `Char'
    Expected type: [FilePattern]
      Actual type: [Char]
    In the second argument of `getDirectoryFiles', namely `"*.png"'
    In a stmt of a 'do' block:
      images <- getDirectoryFiles (obj "manual/images") "*.png"```

(Imported from http://code.google.com/p/diagrams/issues/detail?id=83. Original issue from [email protected] on May 31, 2012, 01:42:23 PM UTC)

Add example of errors like

No instance for (Eq (Scalar (V (Point R2))))
  arising from a use of `scale'
Possible fix:
  add an instance declaration for (Eq (Scalar (V (Point R2))))
In the second argument of `(#)', namely `scale 0.7'
In the expression: p2 (- 1, 3) # scale 0.7
In an equation for `infPt': infPt = p2 (- 1, 3) # scale 0.7

and solution (import Graphics.Rendering.Diagrams.Points) to user manual.

Also need to file GHC bug ticket re: this behavior!

(Imported from http://code.google.com/p/diagrams/issues/detail?id=30. Original issue from [email protected] on May 16, 2011, 03:47:31 PM UTC)

Splitting this out from issue 20.

There should be a tutorial about how to get involved as a contributor (i.e. how to get up and running with darcs, how to build and test, coding standards, procedure for submitting patches, etc.)

(Imported from http://code.google.com/p/diagrams/issues/detail?id=86. Original issue from [email protected] on July 22, 2012, 04:59:18 PM UTC)

(11:35) <sleepyMonad> greetings / goedemiddag
(12:10) <sleepyMonad> Manual says: mappend is composition of transformations; yet rect 5 1 # (rotate (Rad tau/8) <> translateX 10 ) does not give me the same result as rect 5 1 # translateX 10 # rotate (Rad
tau/8)
(12:10) <sleepyMonad> I end up with 2 rectangles instead of one in the former case
(12:23) <sleepyMonad> cf. http://www.ipaste.org/ytj for an example
(12:52) < byorgey> sleepyMonad: hmm, let me take a look
(12:54) < byorgey> sleepyMonad: oh! heh, I see what's going on. Note that rotate (Rad tau/8) and translateX 10 are functions, so rotate (Rad tau/8) <> translateX 10 is using the Monoid m => Monoid (a
-> m) instance
(12:54) < byorgey> in particular (f <> g) x = f x <> g x
(12:55) < byorgey> so rect 5 1 # (rotate (Rad tau/8) <> translateX 10) = (rect 5 1 # rotate (Rad tau/8)) <> (rect 5 1 # translateX 10)
(12:56) < byorgey> it's doing exactly what it should, but it is certainly true that it can be tricky keeping track of all the different Monoid instances.
(12:56) < byorgey> if you wanted to actually use the monoid instance for transformations you would have to do something like
(12:56) < byorgey> rect 5 1 # transform (rotation (Rad tau/8) <> translationX 10)
(12:56) < byorgey> which should give the result you wanted.

The user manual states:

You can also click on any function or operator name in code examples to take you to its documentation. Try it:

But it doesn't work.

(Imported from http://code.google.com/p/diagrams/issues/detail?id=88. Original issue from [email protected] on July 28, 2012, 06:00:04 PM UTC)

> What steps will reproduce the problem?

1. go to http://hackage.haskell.org/packages/archive/diagrams-lib/0.5.0.1/doc/html/Diagrams-TwoD.html#t:CircleFrac
2. look at it

> What is the expected output?
According to the source, "For example, 1/3 = tau/3 radians = 120 degrees."

> What do you see instead?
"For example, 13 = tau3 radians = 120 degrees.", with some italics

> What version of the product are you using? On what operating system?
N/A

> Please provide any additional information below.
It's conceivable that similar problems exist in other places, I didn't check.

(Imported from http://code.google.com/p/diagrams/issues/detail?id=5. Original issue from [email protected] on December 23, 2010, 10:22:48 PM UTC)

It ought to somehow be possible to embed diagrams code in the Haddock documentation and have it be automatically preprocessed by the current library version, ending up with an image embedded in the rendered documentation. Some sort of infrastructure needs to be set up to make this possible.

Links to section headings in the user manual are not working. The links are fine, with the expected #the-transformable-class form. The anchor tags which should be the targets of those links are not present. Examples:

http://projects.haskell.org/diagrams/doc/manual.html#the-transformable-class
http://projects.haskell.org/diagrams/doc/manual.html#deformations

There are probably techniques in the minds of more experienced users for how to figure out why your diagram isn't displaying the way you want; it would be nice for novice users if there were a reference (even if it's a page on the wiki).

For example, I was confused about where a location was in my diagram, so I put a unitCircle there; this wasn't obvious.

http://www.cmears.id.au/articles/diagrams-internals.html

(Imported from http://code.google.com/p/diagrams/issues/detail?id=69. Original issue from [email protected] on March 5, 2012, 09:38:06 PM UTC)

This will probably have to wait until the SVG backend is done, so we can make diagrams-examples depend on it and give people an easy way to quickly get their hands on some working examples. The idea would be for this package to contain source (with included commentary) for a bunch of examples, along with an easy way to build them all. We would also want a way to auto-populate the web gallery from this package.

Diagrams can produce animations, but currently the user manual is a bit sparse in that area, especially because there are no examples. It ought to be possible to include animations in the user manual, but there are some technical issues to be worked out first.

http://projects.haskell.org/diagrams/doc/manual.html#other-resources says "The API reference documentation for all the diagrams packages is intended to be high-quality and up-to-date, and is available from the diagrams website.". It links to http://projects.haskell.org/diagrams/doc/index.html, but the latter does not exist.

See https://groups.google.com/d/msg/diagrams-discuss/fsJQ7wC5B7s/-Cy7QkkxOhkJ for context.

(Imported from http://code.google.com/p/diagrams/issues/detail?id=6. Original issue from [email protected] on December 23, 2010, 11:37:17 PM UTC)

See the old logo here: http://code.haskell.org/diagrams/example/static/logo.png and the source code here: http://code.haskell.org/diagrams/example/logo.hs

At some point we should create a new logo that (a) looks nicer and (b) shows off a bit more of the capabilities of the library. It would also be nice to be able to use the 'D' portion of the logo as a standalone icon for use on the Google Code site, web page, and so on.

(Imported from http://code.google.com/p/diagrams/issues/detail?id=68. Original issue from [email protected] on February 27, 2012, 05:40:26 AM UTC)

These classes were added in 0.5 especially for the purpose of being able to use alignment and juxtaposition combinators with animations. Not sure of the best place to discuss them.

Adding the following lines to .travis.yml brings the packages in the last line to the versions in platform 2012.2.

• sudo ghc-pkg --global unregister cgi
• sudo ghc-pkg --global unregister HTTP
• sudo ghc-pkg --global unregister network
• sudo ghc-pkg --global unregister regex-compat
• sudo ghc-pkg --global unregister regex-posix
• cabal install --force-reinstalls transformers-0.3.0.0 mtl-2.1.1 parsec-3.1.2

At that point, diagrams-doc builds far enough to run into #25, #26, which are easy to fix.

I don't like all the sudo global unregister lines, though. Is there a better approach?

See also:
my work in progress:
https://github.com/bergey/diagrams-doc/tree/travis-build
travis build:
https://travis-ci.org/bergey/diagrams-doc/builds/4822029

In the manual links to names that end in a prime are linked to haddocks as the unprimed name.

All functions from Diagrams.ThreeD.Transforms redirections to Diagrams.ThreeD. For example, reflectAbout redirects to

http://projects.haskell.org/diagrams/haddock/Diagrams-ThreeD.html#v:reflectAbout

(which is wrong) instead of

http://projects.haskell.org/diagrams/haddock/Diagrams-ThreeD-Transform.html#v:reflectAbout