Browse Source

Add documentation in HTML format

Peter Colberg 4 years ago
parent
commit
ac2fba7af4
13 changed files with 275 additions and 133 deletions
  1. 0
    1
      .gitignore
  2. 10
    2
      Makefile
  3. 43
    0
      doc/INSTALL.html
  4. 3
    1
      doc/INSTALL.mdwn
  5. 1
    1
      doc/Makefile
  6. 9
    9
      doc/contents.mdwn
  7. 30
    0
      doc/index.html
  8. 9
    6
      doc/index.mdwn
  9. 59
    88
      doc/pandoc.css
  10. 6
    15
      doc/pandoc.html.in
  11. 93
    0
      doc/reference.html
  12. 7
    5
      doc/reference.mdwn
  13. 5
    5
      rockspec/lua-units-1.0.0-1.rockspec

+ 0
- 1
.gitignore View File

@@ -1,2 +1 @@
1
-/doc/*.html
2 1
 /test/*.out

+ 10
- 2
Makefile View File

@@ -6,13 +6,16 @@
6 6
 
7 7
 PREFIX = /usr/local
8 8
 LUADIR = $(PREFIX)/share/lua/5.1
9
+DOCDIR = $(PREFIX)/share/doc/lua-units
9 10
 
10 11
 INSTALL_D = mkdir -p
11 12
 INSTALL_F = install -m 644
12 13
 
13 14
 FILES_LUA = C.lua init.lua
15
+FILES_DOC = index.mdwn INSTALL.mdwn reference.mdwn
16
+FILES_DOC_HTML = index.html INSTALL.html reference.html pandoc.css lua-units.png
14 17
 
15
-all: units
18
+all: units doc
16 19
 
17 20
 units:
18 21
 	@$(MAKE) -C units
@@ -20,13 +23,18 @@ units:
20 23
 test:
21 24
 	@$(MAKE) -C test
22 25
 
26
+doc:
27
+	@$(MAKE) -C doc
28
+
23 29
 install:
24 30
 	$(INSTALL_D) $(DESTDIR)$(LUADIR)/units
25 31
 	cd units && $(INSTALL_F) $(FILES_LUA) $(DESTDIR)$(LUADIR)/units
32
+	$(INSTALL_D) $(DESTDIR)$(DOCDIR)
33
+	cd doc && $(INSTALL_F) $(FILES_DOC) $(FILES_DOC_HTML) $(DESTDIR)$(DOCDIR)
26 34
 
27 35
 clean:
28 36
 	@$(MAKE) -C units clean
29 37
 	@$(MAKE) -C test clean
30 38
 	@$(MAKE) -C doc clean
31 39
 
32
-.PHONY: units test install clean
40
+.PHONY: units test doc install clean

+ 43
- 0
doc/INSTALL.html View File

@@ -0,0 +1,43 @@
1
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2
+<html xmlns="http://www.w3.org/1999/xhtml">
3
+<head>
4
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
5
+  <meta http-equiv="Content-Style-Type" content="text/css" />
6
+  <meta name="generator" content="pandoc" />
7
+  <meta name="author" content="Peter Colberg" />
8
+  <title>Installing &mdash; Lua Units</title>
9
+  <style type="text/css">code{white-space: pre;}</style>
10
+  <link rel="stylesheet" href="pandoc.css" type="text/css" />
11
+</head>
12
+<body>
13
+<div class="header">
14
+<ul>
15
+<li><a href="index.html">Lua Units</a></li>
16
+<li><a href="INSTALL.html">Installing</a></li>
17
+<li><a href="reference.html">Reference</a></li>
18
+<li><a href="https://lists.colberg.org/listinfo/lua-units">Mailing list</a></li>
19
+</ul>
20
+</div>
21
+<div class="body">
22
+<h1>Installing</h1>
23
+<p>Lua Units is available from a <a href="http://git.colberg.org/lua-units">git repository</a>:</p>
24
+<pre><code>git clone http://git.colberg.org/lua-units</code></pre>
25
+<p>Before using the module, generate matching FFI C bindings for the udunits2 library using the <a href="http://colberg.org/gcc-lua/INSTALL.html">Lua plugin for GCC</a> and the <a href="http://colberg.org/gcc-lua-cdecl/INSTALL.html">C declaration composer</a>:</p>
26
+<pre><code>make</code></pre>
27
+<p>To override the default C compiler <code>gcc</code>, set <code>CC</code>:</p>
28
+<pre><code>make CC=gcc-4.7</code></pre>
29
+<p>If the udunits2 header files are not installed in a system path, set CPATH:</p>
30
+<pre><code>CPATH=/opt/udunits2/include make</code></pre>
31
+<p>To override the name of the udunits2 library, set <code>LIBNAME</code>:</p>
32
+<pre><code>make LIBNAME=libudunits2.so.0</code></pre>
33
+<p>The module is accompanied by a test suite:</p>
34
+<pre><code>make test</code></pre>
35
+<p>To install the module to the default Lua path:</p>
36
+<pre><code>make install</code></pre>
37
+</div>
38
+<div class="footer">
39
+&copy; Copyright 2013–2014, Peter Colberg.
40
+Created using <a href="http://johnmacfarlane.net/pandoc/">Pandoc</a>.
41
+</div>
42
+</body>
43
+</html>

+ 3
- 1
doc/INSTALL.mdwn View File

@@ -1,4 +1,6 @@
1
-% Installing
1
+---
2
+title: Installing
3
+---
2 4
 
3 5
 Lua Units is available from a [git repository]:
4 6
 

+ 1
- 1
doc/Makefile View File

@@ -1,7 +1,7 @@
1 1
 html: index.html INSTALL.html reference.html
2 2
 
3 3
 %.html: %.mdwn pandoc.html
4
-	pandoc --template=pandoc.html --css=pandoc.css --toc -o $@ $<
4
+	pandoc --template=pandoc.html --css=pandoc.css --toc --toc-depth=2 -o $@ $<
5 5
 
6 6
 index.html: index.mdwn pandoc.html
7 7
 	pandoc --template=pandoc.html --css=pandoc.css -V pagetitle= -o $@ $<

+ 9
- 9
doc/contents.mdwn View File

@@ -1,10 +1,10 @@
1
-% Lua Units
2
-% Peter Colberg
3
-% 2013
1
+---
2
+title: Lua Units
3
+author: Peter Colberg
4
+date: "2013–2014"
5
+---
4 6
 
5
-[![](lua-units.png "Lua Units")](index.html)
6
-
7
-* [Lua Units](index.html)
8
-    + [Installing](INSTALL.html)
9
-    + [Reference](reference.html)
10
-    + [Mailing list](https://lists.colberg.org/listinfo/lua-units)
7
+- [Lua Units](index.html)
8
+- [Installing](INSTALL.html)
9
+- [Reference](reference.html)
10
+- [Mailing list](https://lists.colberg.org/listinfo/lua-units)

+ 30
- 0
doc/index.html View File

@@ -0,0 +1,30 @@
1
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2
+<html xmlns="http://www.w3.org/1999/xhtml">
3
+<head>
4
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
5
+  <meta http-equiv="Content-Style-Type" content="text/css" />
6
+  <meta name="generator" content="pandoc" />
7
+  <meta name="author" content="Peter Colberg" />
8
+  <title>Lua Units</title>
9
+  <style type="text/css">code{white-space: pre;}</style>
10
+  <link rel="stylesheet" href="pandoc.css" type="text/css" />
11
+</head>
12
+<body>
13
+<div class="header">
14
+<ul>
15
+<li><a href="index.html">Lua Units</a></li>
16
+<li><a href="INSTALL.html">Installing</a></li>
17
+<li><a href="reference.html">Reference</a></li>
18
+<li><a href="https://lists.colberg.org/listinfo/lua-units">Mailing list</a></li>
19
+</ul>
20
+</div>
21
+<div class="body">
22
+<h1>About Lua Units</h1>
23
+<p><a href="http://colberg.org/lua-units/"><img src="lua-units.png" title="Lua Units" /></a> <a href="http://colberg.org/lua-units/">Lua Units</a> provides bindings for <a href="http://www.unidata.ucar.edu/software/udunits/udunits-2/udunits2.html">UDUNITS-2</a>, a package that supports calculation with and conversion between units of physical quantities. <a href="http://luajit.org/luajit.html">LuaJIT</a> is a just-in-time compiler for the <a href="http://www.lua.org/about.html">Lua</a> language that provides native C data structures through its foreign function interface (<a href="http://luajit.org/ext_ffi.html">FFI</a>) library.</p>
24
+</div>
25
+<div class="footer">
26
+&copy; Copyright 2013–2014, Peter Colberg.
27
+Created using <a href="http://johnmacfarlane.net/pandoc/">Pandoc</a>.
28
+</div>
29
+</body>
30
+</html>

+ 9
- 6
doc/index.mdwn View File

@@ -1,10 +1,13 @@
1
-% About Lua Units
1
+---
2
+title: About Lua Units
3
+---
2 4
 
3
-[Lua Units] provides bindings for [UDUNITS-2], a package that provides support
4
-for units of physical quantities. [Lua] is a powerful, fast, lightweight, and
5
-embeddable scripting language. [LuaJIT] is a just-in-time compiler for the Lua
6
-language, which allows using native C data structures as part of its foreign
7
-function interface library ([FFI]).
5
+[![](lua-units.png "Lua Units")][Lua Units]
6
+[Lua Units] provides bindings for [UDUNITS-2], a package that supports
7
+calculation with and conversion between units of physical quantities.
8
+[LuaJIT] is a just-in-time compiler for the [Lua] language that provides
9
+native C data structures through its foreign function interface ([FFI])
10
+library.
8 11
 
9 12
 [Lua Units]: http://colberg.org/lua-units/
10 13
 [UDUNITS-2]: http://www.unidata.ucar.edu/software/udunits/udunits-2/udunits2.html

+ 59
- 88
doc/pandoc.css View File

@@ -1,6 +1,6 @@
1 1
 /*
2 2
  * Stylesheet for Pandoc.
3
- * Copyright © 2013 Peter Colberg.
3
+ * Copyright © 2013–2014 Peter Colberg.
4 4
  * For conditions of distribution and use, see copyright notice in LICENSE.
5 5
  */
6 6
 
@@ -19,115 +19,61 @@ body {
19 19
 
20 20
 div.header ul {
21 21
   display: table;
22
-  list-style: none;
23 22
   margin: 0;
24
-  padding: 0 0 0 10px;
25
-  height: 2.5em;
23
+  padding: 0;
26 24
 }
27 25
 
28 26
 div.header ul li {
29 27
   display: table-cell;
30
-  vertical-align: middle;
31 28
 }
32 29
 
33 30
 div.header ul li a {
34
-  font-weight: bold;
31
+  display: inline-block;
35 32
   color: #fff;
36 33
   text-shadow: 0 1px rgba(0, 0, 0, 0.5);
37
-  margin: 0 0 0 4px;
38
-  padding: 3px 6px;
39
-  border: none;
40
-  border-radius: 3px;
34
+  line-height: 2em;
35
+  padding: 0 0.5em;
36
+  border-bottom: none;
37
+}
38
+
39
+div.header ul li:first-child a {
40
+  font-weight: bold;
41 41
 }
42 42
 
43 43
 div.header ul li a:hover {
44 44
   background-color: #7a8ad1;
45
-  border-radius: 3px;
46 45
 }
47 46
 
48
-div.columns {
49
-  display: table;
50
-  table-layout: fixed;
51
-  width: 100%;
47
+div.body {
52 48
   color: #000;
49
+  background-color: #fff;
50
+  padding: 0.5em 1.3em;
51
+  border-top: 1px solid #ccc;
52
+  border-bottom: 1px solid #ccc;
53 53
 }
54 54
 
55
-div.columns div {
56
-  display: table-cell;
57
-  vertical-align: top;
58
-}
59
-
60
-div.sidebar {
61
-  background-color: #e8e9ef;
62
-  width: 12em;
63
-}
64
-
65
-div.sidebar ul {
66
-  list-style: none;
67
-  font-size: 1em;
68
-  margin: 1em;
55
+div.toc ul {
56
+  margin: 0.5em 0 1em 0;
69 57
   padding: 0;
58
+  font-size: 0.9em;
70 59
 }
71 60
 
72
-div.sidebar ul ul {
73
-  margin: 0;
74
-}
75
-
76
-div.sidebar ul ul ul {
77
-  margin-left: 1em;
78
-}
79
-
80
-div.sidebar a {
81
-  border-bottom: none;
82
-}
83
-
84
-div.sidebar ul ul li {
85
-  overflow: hidden;
86
-  white-space: nowrap;
87
-  text-overflow: ellipsis;
88
-  position: relative;
89
-}
90
-
91
-div.sidebar ul ul li:hover {
92
-  overflow: visible;
93
-}
94
-
95
-div.sidebar ul li a {
96
-  font-weight: bold;
97
-  color: #444;
98
-}
99
-
100
-div.sidebar ul li a:hover {
101
-  color: #111;
102
-  border-bottom: 1px solid #111;
103
-}
104
-
105
-div.sidebar ul ul li a {
106
-  font-weight: normal;
107
-  background-color: #e8e9ef;
108
-  padding: 0 5px;
109
-  border: 1px solid transparent;
110
-  border-radius: 3px;
111
-}
112
-
113
-div.sidebar ul ul li a:hover {
114
-  border: 1px solid #888;
61
+div.toc ul li {
62
+  display: inline;
115 63
 }
116 64
 
117
-div.sidebar p {
118
-  text-align: center;
65
+div.toc ul li:after {
66
+  padding: 0 0.2em 0 0.3em;
67
+  content: '\b7';
119 68
 }
120 69
 
121
-div.body {
122
-  background-color: #fff;
123
-  padding: 0.5em 1.3em;
124
-  border-left: 1px solid #ccc;
125
-  border-bottom: 1px solid #ccc;
70
+div.toc ul li:last-child:after {
71
+  content: none;
126 72
 }
127 73
 
128 74
 div.footer {
75
+  text-shadow: 0 1px rgba(0, 0, 0, 0.5);
129 76
   font-size: 0.8em;
130
-  color: #fff;
131 77
   text-align: center;
132 78
   padding: 0 2em 2em 2em;
133 79
 }
@@ -140,6 +86,11 @@ div.footer a:hover {
140 86
   border-bottom: 1px solid #7a8ad1;
141 87
 }
142 88
 
89
+div.figure {
90
+  text-align: center;
91
+  font-size: 0.9em;
92
+}
93
+
143 94
 a {
144 95
   color: #444;
145 96
   text-decoration: none;
@@ -203,12 +154,34 @@ h4 a {
203 154
   border-bottom: none;
204 155
 }
205 156
 
206
-div.body p {
157
+p, dl, ul {
207 158
   margin-top: 0.5em;
208 159
   margin-bottom: 1em;
209 160
 }
210 161
 
211
-cite, code, dt, pre {
162
+p {
163
+  overflow: auto;
164
+}
165
+
166
+li p {
167
+  overflow: visible;
168
+}
169
+
170
+p img {
171
+  float: left;
172
+  margin-right: 1.3em;
173
+}
174
+
175
+ul {
176
+  padding-left: 2em;
177
+}
178
+
179
+ul ul {
180
+  margin-top: 0;
181
+  margin-bottom: 0;
182
+}
183
+
184
+cite, code, pre {
212 185
   font-family: 'Consolas', 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono', monospace;
213 186
 }
214 187
 
@@ -216,21 +189,19 @@ cite, code {
216 189
   font-size: 0.95em;
217 190
 }
218 191
 
219
-dl {
220
-  margin: 0;
221
-  padding: 0;
222
-}
223
-
224 192
 dt {
225 193
   font-weight: bold;
226 194
   color: #444;
227 195
 }
228 196
 
229 197
 dt code {
230
-  font: inherit;
231 198
   font-size: 1em;
232 199
 }
233 200
 
201
+dd {
202
+  margin-left: 2em;
203
+}
204
+
234 205
 pre {
235 206
   font-size: 0.85em;
236 207
   line-height: 120%;

+ 6
- 15
doc/pandoc.html.in View File

@@ -39,27 +39,18 @@ $$for(include-before)$$
39 39
 $$include-before$$
40 40
 $$endfor$$
41 41
 <div class="header">
42
-<ul>
43
-<li><a href="index.html">$title$</a></li>
44
-</ul>
45
-</div>
46
-<div class="columns">
47
-<div class="sidebar">
48 42
 $body$
49
-$$if(toc)$$
50
-<ul>
51
-<li><a href="#">$$title$$</a>
52
-$$toc$$
53
-</li>
54
-</ul>
55
-$$endif$$
56 43
 </div>
57 44
 <div class="body">
58 45
 $$if(title)$$
59
-<h1 class="title">$$title$$</h1>
46
+<h1>$$title$$</h1>
60 47
 $$endif$$
61
-$$body$$
48
+$$if(toc)$$
49
+<div class="toc">
50
+$$toc$$
62 51
 </div>
52
+$$endif$$
53
+$$body$$
63 54
 </div>
64 55
 <div class="footer">
65 56
 &copy; Copyright $date$$for(author)$, $author$$endfor$.

+ 93
- 0
doc/reference.html View File

@@ -0,0 +1,93 @@
1
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2
+<html xmlns="http://www.w3.org/1999/xhtml">
3
+<head>
4
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
5
+  <meta http-equiv="Content-Style-Type" content="text/css" />
6
+  <meta name="generator" content="pandoc" />
7
+  <meta name="author" content="Peter Colberg" />
8
+  <title>Reference &mdash; Lua Units</title>
9
+  <style type="text/css">code{white-space: pre;}</style>
10
+  <link rel="stylesheet" href="pandoc.css" type="text/css" />
11
+</head>
12
+<body>
13
+<div class="header">
14
+<ul>
15
+<li><a href="index.html">Lua Units</a></li>
16
+<li><a href="INSTALL.html">Installing</a></li>
17
+<li><a href="reference.html">Reference</a></li>
18
+<li><a href="https://lists.colberg.org/listinfo/lua-units">Mailing list</a></li>
19
+</ul>
20
+</div>
21
+<div class="body">
22
+<h1>Reference</h1>
23
+<div class="toc">
24
+<ul>
25
+<li><a href="#unit-systems">Unit systems</a></li>
26
+<li><a href="#units">Units</a></li>
27
+</ul>
28
+</div>
29
+<h2 id="unit-systems">Unit systems</h2>
30
+<dl>
31
+<dt><code>units.read_xml([path])</code></dt>
32
+<dd><p>Reads a <a href="http://www.unidata.ucar.edu/software/udunits/udunits-2/udunits2.html#Database">units database</a> in XML format and returns a unit system. If the path to the database is ommitted, the function reads the path specified in the environment variable <code>UDUNITS2_XML_PATH</code>; or, if unset, the default database.</p>
33
+</dd>
34
+<dt><code>system:get_dimensionless_unit_one()</code></dt>
35
+<dd><p>Returns the unit of dimension 1.</p>
36
+</dd>
37
+<dt><code>system:get_unit_by_name(s)</code></dt>
38
+<dd><p>Returns the unit that matches the given name in a case-insensitive manner.</p>
39
+</dd>
40
+<dt><code>system:get_unit_by_symbol(s)</code></dt>
41
+<dd><p>Returns the unit that matches the given symbol in a case-sensitive manner.</p>
42
+</dd>
43
+<dt><code>system:parse(s[, encoding])</code></dt>
44
+<dd><p>Parses the given unit string and returns the corresponding unit. A second, optional argument <code>encoding</code> specifies the character encoding of the string.</p>
45
+<p><code>encoding</code> may be any of the following:</p>
46
+<ul>
47
+<li><strong>&quot;ascii&quot;</strong>;</li>
48
+<li><strong>&quot;iso_8859_1&quot;</strong>;</li>
49
+<li><strong>&quot;latin1&quot;</strong> (an alias of <strong>&quot;iso_8859_1&quot;</strong>);</li>
50
+<li><strong>&quot;utf8&quot;</strong> (the default).</li>
51
+</ul>
52
+</dd>
53
+</dl>
54
+<h2 id="units">Units</h2>
55
+<dl>
56
+<dt><code>x * unit</code></dt>
57
+<dd><p>Returns a unit that equals <code>unit</code> scaled by <code>x</code>.</p>
58
+</dd>
59
+<dt><code>unit * x</code></dt>
60
+<dd><p>Returns a unit that equals <code>unit</code> scaled by <code>x</code>.</p>
61
+</dd>
62
+<dt><code>unit1 * unit2</code></dt>
63
+<dd><p>Returns a unit that equals the product of the two units.</p>
64
+</dd>
65
+<dt><code>x / unit</code></dt>
66
+<dd><p>Returns a unit that equals the inverse of <code>unit</code> scaled by <code>x</code>.</p>
67
+</dd>
68
+<dt><code>unit / x</code></dt>
69
+<dd><p>Returns a unit that equals <code>unit</code> scaled by the inverse of <code>x</code>.</p>
70
+</dd>
71
+<dt><code>unit1 / unit2</code></dt>
72
+<dd><p>Returns a unit that equals the quotient of the two units.</p>
73
+</dd>
74
+<dt><code>unit ^ n</code></dt>
75
+<dd><p>Returns a unit that equals <code>unit</code> raised to the power of <code>n</code>.</p>
76
+</dd>
77
+<dt><code>unit % x</code></dt>
78
+<dd><p>Returns a unit that equals <code>unit</code> offset by <code>x</code>.</p>
79
+</dd>
80
+<dt><code>unit1 == unit2</code></dt>
81
+<dd><p>Returns <strong>true</strong> if the two units belong to the same unit system and are equal; otherwise returns <strong>false</strong>.</p>
82
+</dd>
83
+<dt><code>tostring(unit)</code></dt>
84
+<dd><p>Returns a string representation of <code>unit</code> in ASCII character encoding.</p>
85
+</dd>
86
+</dl>
87
+</div>
88
+<div class="footer">
89
+&copy; Copyright 2013–2014, Peter Colberg.
90
+Created using <a href="http://johnmacfarlane.net/pandoc/">Pandoc</a>.
91
+</div>
92
+</body>
93
+</html>

+ 7
- 5
doc/reference.mdwn View File

@@ -1,4 +1,6 @@
1
-% Reference
1
+---
2
+title: Reference
3
+---
2 4
 
3 5
 Unit systems
4 6
 ------------
@@ -32,10 +34,10 @@ Unit systems
32 34
 
33 35
     `encoding` may be any of the following:
34 36
 
35
-    * **"ascii"**;
36
-    * **"iso_8859_1"**;
37
-    * **"latin1"** (an alias of **"iso_8859_1"**);
38
-    * **"utf8"** (the default).
37
+      - **"ascii"**;
38
+      - **"iso_8859_1"**;
39
+      - **"latin1"** (an alias of **"iso_8859_1"**);
40
+      - **"utf8"** (the default).
39 41
 
40 42
 
41 43
 Units

+ 5
- 5
rockspec/lua-units-1.0.0-1.rockspec View File

@@ -7,11 +7,11 @@ source = {
7 7
 description = {
8 8
    summary = "Lua Units",
9 9
    detailed = [[
10
-      Lua Units provides bindings for UDUNITS-2, a package that provides support
11
-      for units of physical quantities. Lua is a powerful, fast, lightweight, and
12
-      embeddable scripting language. LuaJIT is a just-in-time compiler for the Lua
13
-      language, which allows using native C data structures as part of its foreign
14
-      function interface library (FFI).
10
+      Lua Units provides bindings for UDUNITS-2, a package that supports
11
+      calculation with and conversion between units of physical quantities.
12
+      LuaJIT is a just-in-time compiler for the Lua language that provides
13
+      native C data structures through its foreign function interface (FFI)
14
+      library.
15 15
    ]],
16 16
    homepage = "http://colberg.org/lua-units/",
17 17
    license = "MIT/X11",

Loading…
Cancel
Save