README.md
1smi - Simple Markup Interpreter
2===============================
3
4smi is a Simple Markup Interpreter for simplified markup dialect.
5
6**smi** will produce HTML output, by "interpreting"
7[Markdown](http://daringfireball.net/projects/markdown/) formatted text.
8
9**smi** is written in C. Is small, and easily built, and used. In fact; I use it for
10a wiki! I might later, also create a Perl version of **smi**.
11
12INSTALLATION
13------------
14
15Unpack the archive:
16
17 $ tar -xvzf smi-N.N.tar.gz
18 $ cd smi-N.N
19
20where `N.N` represents the Version number(s).
21
22followed by:
23
24 $ make
25 $ sudo make install
26
27Done!
28
29USAGE
30-----
31
32 **smi** [option] infile
33
34 where **option** is currently **-h** (HELP) **-n** (**strict** mode), and
35-v (VERSION)
36
37**EXAMPLE**
38
39 $ smi <Markdown-File>
40
41will echo (dump) the (converted) output (<Markdown-File>) to STDOUT (your screen).
42
43 **-n** -- a so-called "strict mode"
44
45Here's an example using the **-n** switch.
46The **-n** switch causes **smi** to be more "strict" about it's output.
47
48 $ smi -n <Markdown-File>
49
50Again; same syntax, but with *hopefully* more (HTML) "conformant" output.
51
52More accurately; the **-n** switch is better designed to more strictly
53escape HTML markup generated within the **output** file. Please see
54"**bonus features**" below, for a better understanding of what this means.
55
56BONUS FEATURES
57--------------
58
59A few things *possibly* worth noting;
60
61You can re-direct the output to a filehandle (File Name) of your choosing;
62
63eg;
64
65 $ smi README.md > README.html
66
67which will create an HTMLized README file (README.html) from the Markdown
68formatted README.md file. The output file will still lack the <html>, <head>,
69<body> tags, as well as their closing tags. But not having them makes it pretty
70easy to include them within your web site templates.
71
72Another *feature* of **smi**, is it's ability to turn that same HTMLized
73output into code. That is; if you reverse the redirected output:
74
75 $ smi -n README.html > README.code
76
77**smi** will have converted all of the HTML tag fragments into their
78HTML entities! For example the left angle bracket "`<`" becomes "`<`".
79In other words; it will convert the meta-characters from it's own output
80into their equivilent HTML entities.
81
82The same goes for all the other meta-characters generated by **smi**.
83
84This makes it a snap to create code fragments to include in your web
85pages.
86
87I'm sure there are a number of other "features" I haven't *yet* thought of.
88But I'll bet you'll find them. :)
89
90BUGS / TODO
91-----------
92
93Strictly speaking; Markdown supports the <cite> fragment. **smi** doesn't
94*yet* properly cope with them. smi version 1.5 will correct this, and any
95other *bugs* that might be reported before it's release.
96
97**smi** is (c) 2014, Chris Hutchinson
98**smi** is based on work by Enno boland
99Please see [LICENSE](LICENSE), for usage, and any possible restrictions.
100
101The [smi](http://BSDforge.com/projects/textproc/smi/) web site will always
102have the most recent version, and any other related information.
103
104
105