]> git.madduck.net Git - etc/awesome.git/commitdiff

madduck's git repository

Every one of the projects in this repository is available at the canonical URL git://git.madduck.net/madduck/pub/<projectpath> — see each project's metadata for the exact URL.

All patches and comments are welcome. Please squash your changes to logical commits before using git-format-patch and git-send-email to patches@git.madduck.net. If you'd read over the Git project's submission guidelines and adhered to them, I'd be especially grateful.

SSH access, as well as push access can be individually arranged.

If you use my repositories frequently, consider adding the following snippet to ~/.gitconfig and using the third clone URL listed for each project:

[url "git://git.madduck.net/madduck/"]
  insteadOf = madduck:

doc/: Cleanup, add Makefile
authordaurnimator <quae@daurnimator.com>
Fri, 27 Jan 2017 01:34:20 +0000 (12:34 +1100)
committerdaurnimator <quae@daurnimator.com>
Fri, 27 Jan 2017 01:40:11 +0000 (12:40 +1100)
doc/Makefile [new file with mode: 0644]
doc/README.md [new file with mode: 0644]
doc/gettime.md
doc/index.md
doc/links.md [new file with mode: 0644]
doc/metadata.yaml [new file with mode: 0644]
doc/parse.md
doc/site.css [new file with mode: 0644]
doc/template.html [new file with mode: 0644]
doc/timetable.md
doc/tzinfo.md

diff --git a/doc/Makefile b/doc/Makefile
new file mode 100644 (file)
index 0000000..7d30015
--- /dev/null
@@ -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
@@ -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.
index 0457855cdcf384cd0ffc760ff0082f1f2fa0c1b6..a31e5a09682f465b46b8d2c16038298da8f0bd9d 100644 (file)
@@ -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
index e0ece6af8fe8592e50e65b5263c2ad14c72c853e..68a3381eede51ca49d3cb3e3dd0c729fde01c4d9 100644 (file)
@@ -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 (file)
index 0000000..3e8905f
--- /dev/null
@@ -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
@@ -0,0 +1,6 @@
+---
+title: luatz
+subtitle: A lua library for time and date manipulation
+author: Daurnimator <quae@daurnimator.com>
+section: 3
+...
index 649ee8121c8c56244ad1177893acba9c75dd6f9b..c41eae56ae11ef629b7e841e5364924f63bd7b37 100644 (file)
@@ -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 (file)
index 0000000..8858002
--- /dev/null
@@ -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
@@ -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>
index 49fe046b5a494fa7bc04e635b1152737b47898aa..812da43c711e4ab9b272cdc770e085efeefbbec6 100644 (file)
@@ -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`
index 8f95b5d46e886e5a0448d95c558d708cab9be7d7..d4791e2757f54e2a156d67f945b3aa1367412869 100644 (file)
@@ -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.