@@ -1,15 +1,21 @@
11module Text where
2−
3−{-| Functions for displaying text
2+{-| A library for styling and displaying text. Whlie the `String` library
3+focuses on representing and manipulating strings of character strings, the
4+`Text` library focuses on how those strings should look on screen. It lets
5+you make text bold or italic, set the typeface, set the text size, etc.
46
57# Creating Text
68@docs toText
79
810# Creating Elements
11+
12+Each of the following functions places `Text` into a box. The function you use
13+determines the alignment of the text.
14+
915@docs leftAligned, rightAligned, centered, justified
1016
1117# Links and Style
12−@docs link, Style, style, Line, defaultStyle
18+@docs link, Style, style, defaultStyle, Line
1319
1420# Convenience Functions
1521
@@ -35,9 +41,28 @@ import Native.Text
3541
3642data Text = Text
3743
44+{-| Styles for lines on text. This allows you to add an underline, an overline,
45+or a strike out text:
46+
47+ line Under (toText "underline")
48+ line Over (toText "overline")
49+ line Through (toText "strike out")
50+-}
3851data Line = Under | Over | Through
3952
40−{-| Representation of all the ways you can style `Text`.
53+{-| Representation of all the ways you can style `Text`. If the `typeface` list
54+is empty or the `height` is `Nothing`, the users will fall back on their
55+browser's default settings. The following `Style` is black, 16 pixel tall,
56+underlined, and Times New Roman (assuming that typeface is available on the
57+user's computer):
58+
59+ { typeface = [ "Times New Roman", "serif" ]
60+ , height = Just 16
61+ , color = black
62+ , bold = False
63+ , italic = False
64+ , line = Just Under
65+ }
4166-}
4267type Style =
4368 { typeface : [String]
@@ -69,11 +94,19 @@ defaultStyle =
6994 , line = Nothing
7095 }
7196
72−{-| Convert a string into text which can be styled and displayed. -}
97+{-| Convert a string into text which can be styled and displayed. To show the
98+string `"Hello World!"` on screen in italics, you could say:
99+
100+ main = leftAligned (italic (toText "Hello World!"))
101+-}
73102toText : String -> Text
74103toText = Native.Text.toText
75104
76−{-| Set the style of some text.
105+{-| Set the style of some text. For example, if you design a `Style` called
106+`footerStyle` that is specifically for the bottom of your page, you could apply
107+it to text like this:
108+
109+ style footerStyle (toText "the old prince / 2007")
77110-}
78111style : Style -> Text -> Text
79112style = Native.Text.style
@@ -82,53 +115,93 @@ style = Native.Text.style
82115
83116 ["helvetica","arial","sans-serif"]
84117
85−Not everyone has access to the same typefaces, so rendering will use the first
86−typeface in the list that is found on the user's computer. If there are no
87−matches, it will use their default typeface. Works the same as the CSS
118+Not every browser has access to the same typefaces, so rendering will use the
119+first typeface in the list that is found on the user's computer. If there are
120+no matches, it will use their default typeface. This works the same as the CSS
88121font-family property.
89122-}
90123typeface : [String] -> Text -> Text
91124typeface = Native.Text.typeface
92125
93−{-| Switch to a monospace typeface. Good for code snippets. -}
126+{-| Switch to a monospace typeface. Good for code snippets.
127+
128+ monospace (toText "foldl (+) 0 [1,2,3]")
129+-}
94130monospace : Text -> Text
95131monospace = Native.Text.monospace
96132
97−{-| Create a link.
133+{-| Create a link by providing a URL and the text of the link:
98134
99135 link "http://elm-lang.org" (toText "Elm Website")
100136-}
101137link : String -> Text -> Text
102138link = Native.Text.link
103139
140+{-| Set the height of some text:
141+
142+ height 40 (toText "Title")
143+-}
104144height : Float -> Text -> Text
105145height = Native.Text.height
106146
147+{-| Set the color of some text:
148+
149+ color red (toText "Red")
150+-}
107151color : Color -> Text -> Text
108152color = Native.Text.color
109153
154+{-| Make text bold:
155+
156+ toText "sometimes you want " ++ bold (toText "emphasis")
157+-}
110158bold : Text -> Text
111159bold = Native.Text.bold
112160
161+{-| Make text italic:
162+
163+ toText "make it " ++ italic (toText "important")
164+-}
113165italic : Text -> Text
114166italic = Native.Text.italic
115167
168+{-| Put lines on text:
169+
170+ line Under (toText "underlined")
171+ line Over (toText "overlined")
172+ line Through (toText "strike out")
173+-}
116174line : Line -> Text -> Text
117175line = Native.Text.line
118176
177+{-| `Text` is aligned along the left side of the text block. This is sometimes
178+known as *ragged right*.
179+-}
119180leftAligned : Text -> Element
120181leftAligned = Native.Text.leftAligned
121182
183+{-| `Text` is aligned along the right side of the text block. This is sometimes
184+known as *ragged left*.
185+-}
122186rightAligned : Text -> Element
123187rightAligned = Native.Text.rightAligned
124188
189+{-| `Text` is centered in the text block. There is equal spacing on either side
190+of a line of text.
191+-}
125192centered : Text -> Element
126193centered = Native.Text.centered
127194
195+{-| `Text` is aligned along the left and right sides of the text block. Word
196+spacing is adjusted to make this possible.
197+-}
128198justified : Text -> Element
129199justified = Native.Text.justified
130200
131−{-| Display a plain string. -}
201+{-| Display a string with no styling:
202+
203+ plainText string = leftAligned (toText string)
204+-}
132205plainText : String -> Element
133206plainText str =
134207 leftAligned (toText str)
@@ -140,7 +213,7 @@ markdown = Native.Text.markdown
140213{-| Convert anything to its textual representation and make it displayable in
141214the browser:
142215
143− asText == text . monospace . show
216+ asText value = text (monospace (show value))
144217
145218Excellent for debugging.
146219-}