API/Naming Suggestions

[Kwarrtz]

Hi @timjs ,

Overall, I think you've done a great with the library. The Layout module seems especially useful, though your decision to use rectangular envelopes is slightly troubling. It seems counterintuitive, for instance, that if I try to anchor something to the right of a circle it will lie directly on the edge of said circle, but if I try to anchor something to the top-right of it it will lie a bit above of it. There are also a few things about the Layout API that are still unclear to me from the documentation. The first is about the operation of the anchors. In particular, if I anchor a circle to the top-right hand corner of the square, will it be the bottom-left hand corner or the center of the circle that gets anchored? The second is what happens to the envelope when you rotate a collage. Does the envelope keep the same dimensions but rotate with the collage? Or do the dimensions change?

That aside, after looking through the documentation I have a few questions and suggestions regarding the naming and API. All of these suggestions are matters of taste and preference, not function, so feel free to implement or ignore them at your discretion. Further, if there is a specific reason that you have done things the way you have that you think I'm missing, please feel free to say so. That said, here are a few of the things I would change about the API:

• [x] Rename styled, traced and rendered to shape, path and text. The current names seem confusing to me.
• [x] Make the LineStyle and FillStyle separate arguments to styled. This largely a matter of personal taste, but it would be more in line with the conventions I've generally seen used in Elm libraries.
• [x] Rename path to something more specific like polyline or segments. Since you're already using the word "path" as a general descriptor for all line-like objects, I would recommend against also using it to name a function which creates a far more specific object, namely a polyline. This will be especially important, I think, if you ever decide to add curved paths.
• [ ] Rename ngon to regularPolygon. In my experience, the term "n-gon" is used synonymously with "polygon" and does not imply any sort of regularity. So, a more explicit name seems preferable.
• [x] Remove line and Text.empty. What are the intended use cases for these?
• [ ] Restructure the API for styling text to be more consistent with the API for shapes and paths. In particular, for both shapes and paths you pass the styling information to the function that converts them to Collages, but with text the styling is somehow intrinsic to the Text object. Unless there is a reason not to, I would rewrite rendered to have a type signature of TextStyle -> String -> Collage and rework the helper functions in Collage.Text to instead be helper functions for constructing TextStyles. This way the API is more consistent across the different forms. This would also make it more difficult for people to try to set multiple fonts or styles on text (e.g, right now you could try Text.fromString "foobar" |> Text.color blue |> Text.color red).
• [x] Collapse the Collage.Text submodule into Collage. Why are they separated?
• [x] Clarify the difference between mouseEnter, mouseLeave, mouseOver and mouseOff. In fact, I'm still unsure of the difference myself. A comment in the documentation should be sufficient.

As I said before, if you have questions about any of these suggestions or I've missed something as to why you did things the way you did, please say so. Otherwise, I hope this feedback is useful the next time you look at making changes to your API.

[timjs]

Hi @Kwarrtz,

Thanks a lot for your ideas and suggestions! Below I hope to explain some of the decisions and start some discussion on how to improve things. Feel free to comment. Maybe we'll have to open separate issues for some of them, to not mix up different discussions. This post is already way to long, but here we go!

• Tighter envelops instead of rectangular bounding boxes.

  This, off course, would be awesome! Strange things like the top-right of a circle being out of the shape won't happen any more. Two things are important to keep in mind however:

  1. It is quite hard to get this right for all possible shapes.
  2. It will make the library more complicated, as we'll want to calculate envelopes in arbitrary directions using 2D vectors, as Haskell Diagrams does.

  Summarised: awesome to extend envelopes further, but I currently don't have the time and knowledge to implement this myself.

  To answer your two questions:

  • Envelopes always get recalculated after every transformation, although they will stay rectangular.
  • Positioning is always "stacking the internal origin on top of a specified point." So putting a circle at the top-right corner of a rectangle will put the internal origin of the circle on top of the top-right corner of the rectangle.

  I'll add this to the documentation.

• Rename styled, traced and rendered to shape, path and text.

  I prefer the names styled, traced and rendered because they make clear we "finished" its styling. It also fits nicely with filled and outlined. The name traced comes from Elm Graphics, which uses it to "trace a path". Compare these two snippets of code:

  segment ( 0, 5 ) ( 5, 0 )
    |> traced (uniform blue)
  
  fromString "Hello Collage!"
    |> Text.shape Italic
    |> Text.color blue
    |> rendered

  segment ( 0, 5 ) ( 5, 0 )
    |> path (uniform blue)
  
  fromString "Hello Collage!"
    |> Text.shape Italic
    |> Text.color blue
    |> text

  For me, path reads strange: how are we supposed to "path" a segment? Same holds for text, where rendered seems a more natural way to close the pipeline, especially when the Text module is imported qualified.

  More important, path doesn't create a Path but a Collage! A Path is created by segment or line. The same holds for text not creating Text. I think this is more confusing than using traced and rendered.

• Make the LineStyle and FillStyle separate arguments to styled.

  This is a reminiscence from the Elm Render library's ShapeStyle. Note that styled in Elm Collage is more similar to styledShape than to filledAndBordered. I tried to simplify things and merge these to ways to add fill and outline to a shape. It is a hard one to design properly. ShapeStyle was a record, I made Style a tuple. Take a look at these two simple fills and outlines:

  rectangle 100 50
      |> filled (uniform blue)
  
  rectangle 100 50
      |> outlined (solid thick (uniform red))

  and the three possible options to use styled with undefined styles:

  -- Option 1: separate arguments
  rectangle 100 50
      |> styled (uniform blue) (solid thick (uniform red))
  
  -- Option 2: tuple
  rectangle 100 50
      |> styled ( uniform blue, solid thick (uniform red) )
  
  -- Option 3: record
  rectangle 100 50
      |> styled { fill = uniform blue, line = solid thick (uniform red) }

  As for parentheses, it doesn't matter that much. You'll need them anyway in option 1 and option 2. I think option 3 is way to verbose and contains unnecessary information.

  Now comes the deliberation: How does it look like when using predefined styles?

  --
  -- Option 1: separate arguments => create styling functions
  --
  outlinedAndFilled thickness fillColor =
      styled (uniform fillColor) (solid thickness (uniform black))
  
  thinOutlinedAndFilled =
      outlinedAndFilled thin
  
  thickOutlinedAndFilled =
      outlinedAndFilled thick
  
  triangle 30
      |> thickOutlinedAndFilled green
  
  --
  -- Option 2: tuple => create new `Style` tuple
  --
  thinOutlinedAndFilled fillColor =
      ( uniform fillColor, solid thin (uniform black) )
  
  thickOutlinedAndFilled fillColor =
      let
          (fill, line) =
              thinOutlinedAndFilled fillColor
      in
      ( fill, {line | thickness = thick} )
  
  triangle 30
      |> styled (thickOutlinedAndFilled green)
  
  --
  -- Option 3: record => create new `Style` record
  --
  thinOutlinedAndFilled fillColor =
      { fill = uniform fillColor, line = solid thin (uniform black) }
  
  thickOutlinedAndFilled fillColor =
      let
          old =
              thinOutlinedAndFilled fillColor
  
          -- Elm doesn't accept an expression before the bar in records...
          old_line =
              old.line
      in
      { old | line = {old_line | thickness = thick} }
  
  triangle 30
      |> styled (thickOutlinedAndFilled green)

  I'm not sure any more if using a type alias for a shape style consisting of a tuple or a record is a good idea. Probably good old currying and abstraction are indeed our biggest friends here!

• Rename path to something more specific like polyline or segments.

  polyline would be a good name for this. Although I am thinking about naming curved path curve. Let see how this will work out when someone decides to add Bézier curves.

• Rename ngon to regularPolygon.

  Yeah, you are right, another reminiscence from Elm Graphics. But than we probably should do the same with triangle and rename it to regularTriangle which will make names really long. Not sure if I like that, although it is already the case with roundedRectangle...

• Remove line and Text.empty.

  line is very important when using layouting! It is often the case you calculate some width or height and use this it as the length of a line:

  line (width otherPart)

  Because the created line is always centred at (0, 0), it safes you from writing

  segment ( 0, 0 ) ( width otherPart, 0 )
      |> center

  all over your code!

  As for Text.empty, it is a reminiscence from the Elm Graphics library where you could append chunks of text. I don't support that, but I forgot to remove this function with it. So in the next major release I will either add Text.append or remove Text.empty.

• Restructure the API for styling text to be more consistent with the API for shapes and paths.

  I'm not very happy with the current api of the text module, also not very dissatisfied. It is indeed the case that with collages you're styling them "at once" and with text you style them "in parts". It is harder to get text right, because there are so many options. It is not clear to me yet which are the most common we could fit into helper functions. In Collage solid, dashed, dotted etc. fall into this category. They capture the most common styling options for lines: dashing, thickness and colour. More complicated styling can be done by creating a line style.

  Your last point about setting multiple styling options twice is a good one, as that is something I'm trying to avoid with collages. We need some more examples and feedback to decide on a good api for text.

• Collapse the Collage.Text submodule into Collage.

  I believe that text styling is something separate from drawing collages. Elm Graphics keeps it separate too. I can imagine a function rendering Text as Html instead of requiring to use it in a collage. Such a module could even be in a separate package, like Color is going to be in Elm 0.19.

• Clarify the difference between mouseEnter, mouseLeave, mouseOver and mouseOff.

  Really good point, I'm always confused and have to look it up myself over and over again! JQuery has a good explanation. We'll have to come up with a Collage equivalent of this.

[Kwarrtz]

Thanks for the point by point breakdown. Most of my qualms you've either adequately explained or opened an issue for. The only point I still find unsatisfactory is traced, rendered and styled. I understand your desire to use names which reflect the idea that the forms are being "finalized" as collages, so the names I suggested may not be preferable. And on balance, traced seems reasonably named, especially considering the precedent from Elm Graphics you mentioned. However, I would still strongly recommend reconsidering the names of rendered and styled. Both of these names are far more general than their usage implies, since lines can be styled and shapes can be rendered. This ambiguity could, I think, easily lead to a great deal of confusion for one first learning the library. I don't know what names you would want to use in their place, but I would at least try to think of alternatives for these two functions.

[timjs]

Yeah, you’re right about the generality of rendered and styled. How about printed for text and depicted for shapes? Drawn, painted and formed for shapes also seem to general to me and typesetted, which would be ideal for text, doesn’t seem to be correct English.

On 18 Oct 2017, 05:26 +0200, Dathan Ault-McCoy notifications@github.com, wrote:

Thanks for the point by point breakdown. Most of my qualms you've either adequately explained or opened an issue for. The only point I still find unsatisfactory is traced, rendered and styled. I understand your desire to use names which reflect the idea that the forms are being "finalized" as collages, so the names I suggested may not be preferable. And on balance, traced seems reasonably named, especially considering the precedent from Elm Graphics you mentioned. However, I would still strongly recommend reconsidering the names of rendered and styled. Both of these names are far more general than their usage implies, since lines can be styled and shapes can be rendered. This ambiguity could, I think, easily lead to a great deal of confusion for one first learning the library. I don't know what names you would want to use in their place, but I would at least try to think of alternatives for these two functions. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.

[Kwarrtz]

I believe "typeset" would be the proper conjugation, but that leaves ambiguity about whether it's being used as an adjective or an imperative. Using that word here seems a bit oblique to me anyway. I prefer "printed". As for the shape function, "depicted" seems both too general and too tenuous, but I'm having trouble thinking of better options.