gdritter repos telml-markup / 90b8cc9
Filled in some of the readme Getty Ritter 9 years ago
1 changed file(s) with 95 addition(s) and 11 deletion(s). Collapse all Expand all
+95
-11
README.md less more
11 # telml-markup
22
3 TODO: Write description here
3 The `telml-markup` package provides a simple, LaTeX-inspired markup
4 language with the possibility of writing extensible instructions.
45
5 ## Installation
6 ## Basic Usage
67
7 TODO: Write installation instructions here
8 The `render` function takes a [`telml`](https://github.com/aisamanra/telml)
9 document and renders it into the
10 [`blaze-html`](http://hackage.haskell.org/package/blaze-html-0.8.0.2)
11 [`Html`] type, which can then be rendered into HTML. For example, using
12 the following minimal program:
813
9 ## Usage
14 ~~~~{.haskell}
15 module Main
1016
11 TODO: Write usage instructions here
17 import Control.Monad ((>=>))
18 import Data.TeLML (parse)
19 import Data.TeLML.Markup (render)
20 import Text.Blaze.Renderer.String (renderMarkup)
1221
13 ## How to run tests
22 main :: IO ()
23 main = do
24 str <- getContents
25 case (parse >=> render) str of
26 Left err -> putStrLn err
27 Right doc -> putStrLn (renderMarkup doc)
28 ~~~~
1429
15 ```
16 cabal configure --enable-tests && cabal build && cabal test
17 ```
30 We could invoke it at the command line like so:
1831
19 ## Contributing
32 ~~~~
33 $ ./telml-markup-test <<EOF
34 > This should be \em{emphasized}.
35 >
36 > This, on the other hand, is \strong{bold}.
37 > EOF
38 <p>This should be<em>emphasized</em>.
39 </p><p>This, on the other hand, is <strong>bold</strong>.
40 </p>
41 ~~~~
2042
21 TODO: Write contribution instructions here
43 If we give it an unknown tag, or a tag with the wrong arity, it will
44 give us an error:
45
46 ~~~~
47 $ ./telml-markup-test <<EOF
48 > This is a \fake{tag}.
49 > EOF
50 Error: no match for tag fake/1
51 $ ./telml-markup-test <<EOF
52 > This is a tag with \em{too|many|arguments}.
53 > EOF
54 Error: no match for tag em/3
55 ~~~~
56
57 ## Extended Usage
58
59 The `renderWith` function takes a list of additional tags to understand.
60 It will always give precedence to the built-in tags, so one cannot overload
61 (for example) the built-in tag `em/1`. However, you can add any additional
62 tags that you want.
63
64 For example, here we add a tag so that `\hello{...}` will render out to
65 the HTML string `<strong>Hello, ...!</strong>`:
66
67 ~~~~{.haskell}
68 module Main where
69
70 import Control.Monad ((>=>))
71 import Data.TeLML (parse)
72 import Data.TeLML.Markup (Renderer, renderWith)
73 import Text.Blaze.Renderer.String (renderMarkup)
74 import Text.Blaze.Html5 (strong, toMarkup)
75
76 myTags :: [(String, Renderer)]
77 myTags =
78 [ ("hello", \ c -> case c of
79 (render, [name]) -> do
80 rName <- mapM render name
81 return $ strong $ do
82 toMarkup "Hello, "
83 sequence_ rName
84 toMarkup "!"
85 (_, args) -> Left ("Did not match hello/" ++ show (length args))
86 )
87 ]
88
89 main :: IO ()
90 main = do
91 str <- getContents
92 case (parse >=> renderWith myTags) str of
93 Left err -> putStrLn err
94 Right doc -> putStrLn (renderMarkup doc)
95 ~~~~
96
97 We can execute this to test it:
98
99 ~~~~
100 $ ./telml-markup-extended-test <<EOF
101 > Now we can do this: \hello{friend}.
102 > EOF
103 <p>Now we can do this: <strong>Hello, friend!</strong>.
104 </p>
105 ~~~~