doc/: Cleanup, add Makefile

diff --git a/doc/Makefile b/doc/Makefile
new file mode 100644 (file)
index 0000000..7d30015
--- /dev/null
+++ b/doc/Makefile
@@ -0,0 +1,26 @@
+FILES = \
+       index.md \
+       gettime.md \
+       parse.md \
+       timetable.md \
+       tzinfo.md \
+       links.md
+
+all: luatz.html luatz.pdf luatz.3
+
+luatz.html: template.html site.css metadata.yaml $(FILES)
+       pandoc -o $@ -t html5 -s --toc --template=template.html --section-divs --self-contained -c site.css metadata.yaml $(FILES)
+
+luatz.pdf: metadata.yaml $(FILES)
+       pandoc -o $@ -t latex -s --toc --toc-depth=2 -V documentclass=article -V classoption=oneside -V links-as-notes -V geometry=a4paper,includeheadfoot,margin=2.54cm metadata.yaml $(FILES)
+
+luatz.3: metadata.yaml $(FILES)
+       pandoc -o $@ -t man -s metadata.yaml $(FILES)
+
+man: luatz.3
+       man -l $^
+
+clean:
+       rm -f luatz.html luatz.pdf luatz.3
+
+.PHONY: all man install clean

diff --git a/doc/README.md b/doc/README.md
new file mode 100644 (file)
index 0000000..ed82567
--- /dev/null
+++ b/doc/README.md
@@ -0,0 +1,5 @@
+Documentation in this directory is intended to be converted to other formats using [pandoc](http://pandoc.org/).
+
+An online HTML version can be found at [https://daurnimator.github.io/luatz/](https://daurnimator.github.io/luatz/)
+
+The *Makefile* in this directory should be used to compile the documentation.

diff --git a/doc/gettime.md b/doc/gettime.md
index 0457855cdcf384cd0ffc760ff0082f1f2fa0c1b6..a31e5a09682f465b46b8d2c16038298da8f0bd9d 100644 (file)
--- a/doc/gettime.md
+++ b/doc/gettime.md
@@ -1,4 +1,4 @@
-# `luatz.gettime`
+## `luatz.gettime` <!-- --> {#gettime}

 
 A module to get the current time.
 
 
 A module to get the current time.
 


@@ -9,16 +9,18 @@ Uses the most precise method available (in order:)
          - `gettimeofday(2)`
   - [luasocket](http://w3.impa.br/~diego/software/luasocket/)'s `socket.gettime`
   - [Openresty](http://openresty.org/)'s [`ngx.now`](http://wiki.nginx.org/HttpLuaModule#ngx.now)
          - `gettimeofday(2)`
   - [luasocket](http://w3.impa.br/~diego/software/luasocket/)'s `socket.gettime`
   - [Openresty](http://openresty.org/)'s [`ngx.now`](http://wiki.nginx.org/HttpLuaModule#ngx.now)

-  - [`os.time`](http://www.lua.org/manual/5.2/manual.html#pdf-os.time)
+  - [`os.time`](http://www.lua.org/manual/5.3/manual.html#pdf-os.time)

 
 

-### `source`
+### `source` <!-- --> {#gettime.source}

 
 

-The library/function currently in use.
+The library/function currently in use by [`gettime()`](#gettime.gettime).

 
 

-### `resolution`

 
 

-The smallest time resolution (in seconds) available from `gettime ( )` .
+### `resolution` <!-- --> {#gettime.resolution}

 
 

-### `gettime ( )`
+The smallest time resolution (in seconds) available from [`gettime()`](#gettime.gettime).
+
+
+### `gettime()` <!-- --> {#gettime.gettime}

 
 Returns the number of seconds since unix epoch (1970-01-01T00:00:00Z) as a lua number
 
 Returns the number of seconds since unix epoch (1970-01-01T00:00:00Z) as a lua number

diff --git a/doc/index.md b/doc/index.md
index e0ece6af8fe8592e50e65b5263c2ad14c72c853e..68a3381eede51ca49d3cb3e3dd0c729fde01c4d9 100644 (file)
--- a/doc/index.md
+++ b/doc/index.md
@@ -1,25 +1,25 @@
-# `luatz`
+## `luatz`

 
 Requiring the base luatz module will give you a table of commonly used functions and submodules.
 
 The table includes the following sub modules, which have their own documentation:
 
 
 Requiring the base luatz module will give you a table of commonly used functions and submodules.
 
 The table includes the following sub modules, which have their own documentation:
 

-  - `parse`: Parses common date/time formats
-  - `timetable`: Class for date/time objects supporting normalisation
+  - [`parse`](#parse): Parses common date/time formats
+  - [`timetable`](#timetable): Class for date/time objects supporting normalisation

 
 

-
-### `time ( )`
+### `time()` <!-- --> {#luatz.time}

 
 Returns the current unix timestamp using the most precise source available.
 
 Returns the current unix timestamp using the most precise source available.

-See `gettime` for more information.
+See [`gettime`](#luatz.gettime) for more information.
+

 
 

-### `now ( )`
+### `now()` <!-- --> {#luatz.now}

 
 Returns the current time as a timetable object
 See `timetable` for more information
 
 
 
 Returns the current time as a timetable object
 See `timetable` for more information
 
 

-### `get_tz ( [timezone_name] )`
+### `get_tz([timezone_name])` <!-- --> {#luatz.get_tz}

 
 Returns a timezone object (see `tzinfo` documentation) for the given `timezone_name`.
 If `timezone_name` is `nil` then the local timezone is used.
 
 Returns a timezone object (see `tzinfo` documentation) for the given `timezone_name`.
 If `timezone_name` is `nil` then the local timezone is used.


@@ -30,17 +30,22 @@ names are usually of the form `Country/Largest_City` e.g. "America/New_York".
 Check [wikipedia](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) for an example list.
 
 
 Check [wikipedia](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) for an example list.
 
 

-### `time_in ( timezone_name [, utc_ts] )`
+### `time_in(timezone_name[, utc_ts])` <!-- --> {#luatz.time_in}

 
 Returns the current time in seconds since 1970-01-01 0:00:00 in the given timezone as a string,
 
 Returns the current time in seconds since 1970-01-01 0:00:00 in the given timezone as a string,

-(same semantics as `get_tz`) at the given UTC time (defaults to now).
+(same semantics as [`get_tz`](#luatz.get_tz)) at the given UTC time (defaults to now).
+
+
+### `gmtime(ts)` <!-- --> {#luatz.gmtime}
+
+As in the C standard library

 
 
 
 

-## As in the C standard library
+### `localtime(ts)` <!-- --> {#luatz.localtime}

 
 

-### `gmtime ( ts )`
+As in the C standard library

 
 

-### `localtime ( ts )`

 
 

-### `ctime ( ts )`
+### `ctime(ts)` <!-- --> {#luatz.ctime}

 
 

+As in the C standard library

diff --git a/doc/links.md b/doc/links.md
new file mode 100644 (file)
index 0000000..3e8905f
--- /dev/null
+++ b/doc/links.md
@@ -0,0 +1,5 @@
+# Links
+
+  - [Github](https://github.com/daurnimator/luatz)
+  - [Issue tracker](https://github.com/daurnimator/luatz/issues)
+  - [luarocks](https://luarocks.org/modules/daurnimator/luatz)

diff --git a/doc/metadata.yaml b/doc/metadata.yaml
new file mode 100644 (file)
index 0000000..4f144f0
--- /dev/null
+++ b/doc/metadata.yaml
@@ -0,0 +1,6 @@
+---
+title: luatz
+subtitle: A lua library for time and date manipulation
+author: Daurnimator <quae@daurnimator.com>
+section: 3
+...

diff --git a/doc/parse.md b/doc/parse.md
index 649ee8121c8c56244ad1177893acba9c75dd6f9b..c41eae56ae11ef629b7e841e5364924f63bd7b37 100644 (file)
--- a/doc/parse.md
+++ b/doc/parse.md
@@ -1,10 +1,10 @@
-# `luatz.parse`
+## `luatz.parse` <!-- --> {#parse}

 
 Provides parsers for common time and date formats.
 
 Functions take the source string and an optional initial postition.
 
 
 Provides parsers for common time and date formats.
 
 Functions take the source string and an optional initial postition.
 

-### `rfc_3339 ( string [, init] )`
+### `rfc_3339(string[, init])` <!-- --> {#parse.rfc_3339}

 
 If the string is a valid RFC-3339 timestamp,
 returns a luatz timetable and the (optional) time zone offset in seconds.
 
 If the string is a valid RFC-3339 timestamp,
 returns a luatz timetable and the (optional) time zone offset in seconds.

diff --git a/doc/site.css b/doc/site.css
new file mode 100644 (file)
index 0000000..8858002
--- /dev/null
+++ b/doc/site.css
@@ -0,0 +1,156 @@
+* {
+    -webkit-box-sizing: border-box;
+    -moz-box-sizing: border-box;
+    box-sizing: border-box
+}
+html,
+body {
+    height: 100%
+}
+article,
+aside,
+figure,
+footer,
+header,
+hgroup,
+menu,
+nav,
+section {
+    display: block
+}
+body {
+    margin: 0
+}
+h1,
+h2,
+h3 {
+    margin: 1rem 0
+}
+h4,
+h5,
+h6,
+ul,
+ol,
+dl,
+blockquote,
+address,
+p,
+figure {
+    margin: 0 0 1rem 0
+}
+img {
+    max-width: 100%
+}
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+    font-weight: 700
+}
+h1 {
+    font-size: 2.5rem;
+    line-height: 3rem
+}
+h2 {
+    font-size: 1.5rem;
+    line-height: 2rem
+}
+h3 {
+    font-size: 1.25rem;
+    line-height: 1.5rem
+}
+h4,
+h5,
+h6 {
+    font-size: 1rem;
+    line-height: 1.25rem
+}
+hr {
+    border: 0;
+    border-bottom: 1px solid;
+    margin-top: -1px;
+    margin-bottom: 1rem
+}
+a:hover {
+    color: inherit
+}
+small {
+    font-size: .875rem
+}
+ul,
+ol {
+    padding-left: 1rem
+}
+ul ul,
+ul ol,
+ol ol,
+ol ul {
+    margin: 0
+}
+dt {
+    font-weight: 700
+}
+dd {
+    margin: 0
+}
+blockquote {
+    border-left: 1px solid;
+    padding-left: 1rem
+}
+address {
+    font-style: normal
+}
+html {
+    color: #333;
+    font: 100%/1.5  Avenir, 'Helvetica Neue', Helvetica, Arial, sans-serif;
+    -webkit-font-smoothing: antialiased;
+    -webkit-text-size-adjust: 100%;
+        -ms-text-size-adjust: 100%;
+    background: #FFF;
+}
+a {
+    color: #999;
+    text-decoration: none;
+    transition: color 0.3s;
+}
+a > h1,
+a > h2,
+a > h3 {
+    color: #333;
+}
+
+body > * {
+    padding: 0 1rem;
+}
+.subtitle {
+    font-size: 1rem;
+    line-height: 1.5rem
+}
+.author {
+    display: none
+}
+@media screen and (min-width: 55rem) {
+    .meta {
+        position: fixed;
+        width: 20rem;
+        height: 100%;
+        overflow: auto;
+        background: #FFF;
+        z-index: 1;
+    }
+    main {
+        display: block; /* required for e.g. konqueror */
+        margin-left: 20rem;
+        overflow: auto;
+    }
+}
+@media print {
+    section.level1 {
+        page-break-inside: avoid
+    }
+    nav a::after {
+        content: leader('.') target-counter(attr(href url), page, decimal)
+    }
+}

diff --git a/doc/template.html b/doc/template.html
new file mode 100644 (file)
index 0000000..a74a7b6
--- /dev/null
+++ b/doc/template.html
@@ -0,0 +1,71 @@
+<!DOCTYPE html>
+<html$if(lang)$ lang="$lang$"$endif$$if(dir)$ dir="$dir$"$endif$>
+<head>
+  <meta charset="utf-8">
+  <meta name="generator" content="pandoc">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
+$for(author-meta)$
+  <meta name="author" content="$author-meta$">
+$endfor$
+$if(date-meta)$
+  <meta name="dcterms.date" content="$date-meta$">
+$endif$
+$if(keywords)$
+  <meta name="keywords" content="$for(keywords)$$keywords$$sep$, $endfor$">
+$endif$
+  <title>$if(title-prefix)$$title-prefix$ – $endif$$pagetitle$</title>
+  <style type="text/css">code{white-space: pre;}</style>
+$if(quotes)$
+  <style type="text/css">q { quotes: "“" "”" "‘" "’"; }</style>
+$endif$
+$if(highlighting-css)$
+  <style type="text/css">
+$highlighting-css$
+  </style>
+$endif$
+$for(css)$
+  <link rel="stylesheet" href="$css$">
+$endfor$
+$if(math)$
+  $math$
+$endif$
+  <!--[if lt IE 9]>
+    <script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv-printshiv.min.js"></script>
+  <![endif]-->
+$for(header-includes)$
+  $header-includes$
+$endfor$
+</head>
+<body>
+$for(include-before)$
+$include-before$
+$endfor$
+<div class="meta">
+$if(title)$
+<header>
+<h1 class="title">$title$</h1>
+$if(subtitle)$
+<h1 class="subtitle">$subtitle$</h1>
+$endif$
+$for(author)$
+<h2 class="author">$author$</h2>
+$endfor$
+$if(date)$
+<h3 class="date">$date$</h3>
+$endif$
+</header>
+$endif$
+$if(toc)$
+<nav id="$idprefix$TOC">
+$toc$
+</nav>
+$endif$
+</div>
+<main>
+$body$
+</main>
+$for(include-after)$
+$include-after$
+$endfor$
+</body>
+</html>

diff --git a/doc/timetable.md b/doc/timetable.md
index 49fe046b5a494fa7bc04e635b1152737b47898aa..812da43c711e4ab9b272cdc770e085efeefbbec6 100644 (file)
--- a/doc/timetable.md
+++ b/doc/timetable.md
@@ -1,4 +1,4 @@
-# `luatz.timetable`
+## `luatz.timetable` <!-- --> {#timetable}

 
 Provides an class to represent a time and date.
 Objects have no concept of timezone or utc offset.
 
 Provides an class to represent a time and date.
 Objects have no concept of timezone or utc offset.


@@ -15,29 +15,29 @@ The fields are intentionally compatible with the lua standard library's `os.date
   - `wday` (optional)
   
 timetable components may be outside of their standard range (e.g. a month component of 
   - `wday` (optional)
   
 timetable components may be outside of their standard range (e.g. a month component of 

-14) to facilitate arithmetic operations on date components. `:normalise ( )` can be 
+14) to facilitate arithmetic operations on date components. `:normalise()` can be 

 called to modify components to return to their standard range.
 
 Equality and comparisons should work between timetable objects.
 
 
 called to modify components to return to their standard range.
 
 Equality and comparisons should work between timetable objects.
 
 

-### `new ( year , month , day , hour , min , sec , [yday] , [wday] )`
+### `new(year, month, day, hour, min, sec[, yday[, [wday]])` <!-- --> {#timetable.new}

 
 Returns a new timetable with the given contents.
 
 
 
 Returns a new timetable with the given contents.
 
 

-### `new_from_timestamp ( timestamp )`
+### `new_from_timestamp(timestamp)` <!-- --> {#timetable.new_from_timestamp}

 
 Returns a new (normalised) timetable, given a timestamp in seconds since the unix epoch of 
 1970-01-01.
 
 
 
 Returns a new (normalised) timetable, given a timestamp in seconds since the unix epoch of 
 1970-01-01.
 
 

-### `:clone ( )`
+### `timetable:clone()` <!-- --> {#timetable:clone}

 
 Returns a new independent instance of an existing timetable object.
 
 
 
 Returns a new independent instance of an existing timetable object.
 
 

-### `:normalise ( )`
+### `timetable:normalise()` <!-- --> {#timetable:normalise}

 
 Mutates the current object's time and date components so that are integers within 'normal'
 ranges e.g. `month` is `1`-`12`; `min` is `0`-`59`
 
 Mutates the current object's time and date components so that are integers within 'normal'
 ranges e.g. `month` is `1`-`12`; `min` is `0`-`59`


@@ -51,19 +51,21 @@ e.g. `.hour=10` `.min=100` (100 minutes past 10am)
 normalises to `.hour=11` `.min=40`
 
 
 normalises to `.hour=11` `.min=40`
 
 

-### `:rfc_3339 ( )` and `__tostring` metamethod
+### `timetable:rfc_3339()` <!-- --> {#timetable:rfc_3339}

 
 Returns the timetable formatted as an rfc-3339 style string.
 The timezone offset (or Z) is not appended.
 The ranges of components are not checked, if you want a valid timestamp,
 
 Returns the timetable formatted as an rfc-3339 style string.
 The timezone offset (or Z) is not appended.
 The ranges of components are not checked, if you want a valid timestamp,

-`:normalise ( )` should be called first.
+[`:normalise()`](#timetable:normalise) should be called first.

 
 

+This function is also the `__tostring` metamethod for timetable objects

 
 

-### `:timestamp ( )`
+
+### `timetable:timestamp()` <!-- --> {#timetable:timestamp}

 
 Returns the timetable as the number of seconds since unix epoch (1970-01-01) as a lua number.
 
 
 
 Returns the timetable as the number of seconds since unix epoch (1970-01-01) as a lua number.
 
 

-### `:unpack ( )`
+### `timetable:unpack()` <!-- --> {#timetable:unpack}

 
 Unpacks the timetable object; returns `year`, `month`, `day`, `hour`, `min`, `sec`, `yday`, `wday`
 
 Unpacks the timetable object; returns `year`, `month`, `day`, `hour`, `min`, `sec`, `yday`, `wday`

diff --git a/doc/tzinfo.md b/doc/tzinfo.md
index 8f95b5d46e886e5a0448d95c558d708cab9be7d7..d4791e2757f54e2a156d67f945b3aa1367412869 100644 (file)
--- a/doc/tzinfo.md
+++ b/doc/tzinfo.md
@@ -1,4 +1,4 @@
-# `luatz.tzinfo`
+## `luatz.tzinfo` <!-- --> {#tzinfo}

 
 Provides a metatable for the timezone class.
 
 
 Provides a metatable for the timezone class.
 


@@ -26,18 +26,18 @@ and contains the following fields:
   - `isgmt` (boolean)
 
 
   - `isgmt` (boolean)
 
 

-### `:find_current ( utc_ts )`
+### `tzinfo:find_current(utc_ts)` <!-- --> {#tzinfo:find_current}

 
 Returns the relevant `tt_info` object for the given UTC timestamp in the timezone.
 
 
 
 Returns the relevant `tt_info` object for the given UTC timestamp in the timezone.
 
 

-### `:localise ( utc_ts )` and `:localize ( utc_ts )`
+### `tzinfo:localise(utc_ts)` and `tzinfo:localize(utc_ts)` <!-- --> {#tzinfo:localise}

 
 Convert the given UTC timestamp to the timezone.
 Returns the number of seconds since unix epoch in the given timezone.
 
 
 
 Convert the given UTC timestamp to the timezone.
 Returns the number of seconds since unix epoch in the given timezone.
 
 

-### `:utctime ( local_ts )`
+### `tzinfo:utctime(local_ts)` <!-- --> {#tzinfo:utctime}

 
 Convert the given local timestamp (seconds since unix epoch in the time zone) to a UTC timestamp.
 This may result in ambigous results, in which case multiple values are returned.
 
 Convert the given local timestamp (seconds since unix epoch in the time zone) to a UTC timestamp.
 This may result in ambigous results, in which case multiple values are returned.