From: daurnimator Date: Fri, 27 Jan 2017 01:34:20 +0000 (+1100) Subject: doc/: Cleanup, add Makefile X-Git-Url: https://git.madduck.net/etc/awesome.git/commitdiff_plain/c9eb90f7079172d62c2def3155015dac56558029?ds=inline doc/: Cleanup, add Makefile --- diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 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 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 0457855..a31e5a0 100644 --- a/doc/gettime.md +++ b/doc/gettime.md @@ -1,4 +1,4 @@ -# `luatz.gettime` +## `luatz.gettime` {#gettime} 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) - - [`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 diff --git a/doc/index.md b/doc/index.md index e0ece6a..68a3381 100644 --- 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: - - `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. -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 -### `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. @@ -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. -### `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, -(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 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 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 +section: 3 +... diff --git a/doc/parse.md b/doc/parse.md index 649ee81..c41eae5 100644 --- 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. -### `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. diff --git a/doc/site.css b/doc/site.css new file mode 100644 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 index 0000000..a74a7b6 --- /dev/null +++ b/doc/template.html @@ -0,0 +1,71 @@ + + + + + + +$for(author-meta)$ + +$endfor$ +$if(date-meta)$ + +$endif$ +$if(keywords)$ + +$endif$ + $if(title-prefix)$$title-prefix$ – $endif$$pagetitle$ + +$if(quotes)$ + +$endif$ +$if(highlighting-css)$ + +$endif$ +$for(css)$ + +$endfor$ +$if(math)$ + $math$ +$endif$ + +$for(header-includes)$ + $header-includes$ +$endfor$ + + +$for(include-before)$ +$include-before$ +$endfor$ +
+$if(title)$ +
+

$title$

+$if(subtitle)$ +

$subtitle$

+$endif$ +$for(author)$ +

$author$

+$endfor$ +$if(date)$ +

$date$

+$endif$ +
+$endif$ +$if(toc)$ + +$endif$ +
+
+$body$ +
+$for(include-after)$ +$include-after$ +$endfor$ + + diff --git a/doc/timetable.md b/doc/timetable.md index 49fe046..812da43 100644 --- 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. @@ -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 -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. -### `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. -### `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. -### `:clone ( )` +### `timetable:clone()` {#timetable:clone} 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` @@ -51,19 +51,21 @@ e.g. `.hour=10` `.min=100` (100 minutes past 10am) 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, -`: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. -### `:unpack ( )` +### `timetable:unpack()` {#timetable:unpack} Unpacks the timetable object; returns `year`, `month`, `day`, `hour`, `min`, `sec`, `yday`, `wday` diff --git a/doc/tzinfo.md b/doc/tzinfo.md index 8f95b5d..d4791e2 100644 --- a/doc/tzinfo.md +++ b/doc/tzinfo.md @@ -1,4 +1,4 @@ -# `luatz.tzinfo` +## `luatz.tzinfo` {#tzinfo} Provides a metatable for the timezone class. @@ -26,18 +26,18 @@ and contains the following fields: - `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. -### `: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. -### `: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.