From 9d8d5ee467e73f318be47a4b8dcc1a2fbfbc9cf9 Mon Sep 17 00:00:00 2001 From: Ambrose Chua Date: Tue, 10 Nov 2020 18:17:43 +0800 Subject: [PATCH] Improve README --- README.md | 59 ++++++++++++++++++++++++++++++------------- templates/footer.html | 14 +++++----- templates/index.html | 3 ++- 3 files changed, 50 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 85fffd4..d94c166 100644 --- a/README.md +++ b/README.md @@ -1,33 +1,56 @@ -# WIP: datetime.link +# datetime.link -Clean links to a point in time +Readable links to a point in time + +## Credits + +- [GeoNames](https://www.geonames.org/) and its contributors + +## Reporting Problems + +File an [issue](https://github.com/serverwentdown/datetime.link/issues/new) on +GitHub. ## Rationale -Sometimes, you want to refer to a point in time, but want to provide a timezone converter for them. datetime.link provides links to points in time and presents them in localtime. You can also optionally select which timezones to present the time in. +Sometimes, you want to refer to a point in time, and also want to provide a +timezone converter for them. datetime.link provides links to points in time and +presents them in a set of selected timezones and/or local time. ## Compatibility -To achieve backwards compatibility and usability without JavaScript, the dates must be converted and rendered into pure HTML. This makes cURL a working target. - -Progressive enhancement extends on the UI by providing a visual editor for timezones, dates and times that change the URL. This is done with JavaScript and native input elements. In the future custom input elements could replace the native ones. +To ensure compatibility with non-JavaScript clients, the server responds with a +pure HTML page without local time. JavaScript provides the rendering of local +time and local time format using the native [Intl](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat) +and [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) +APIs, eventually the [Temporal API](https://github.com/tc39/proposal-temporal). +JavaScript also provides the visual editing interface for the date, time and +list of timezones to show in. ## Timezone Specifiers -### `tzdata` +[GeoNames](https://www.geonames.org/) data is used to generate +[`data/cities.json`](https://datetime.link/data/cities.json), a huge 5MB JSON +blob containing cities with a population greater than 15000. In the event this +is not enough, more cities can be included by using the alternate +`cities5000.txt` file. -These are defined in the ICANN/IETF database. Examples: +The timezone specifiers are generated by the code in `scripts/data.go`, which +assemble an identifier replacing non-alphanumeric and quote characters with +underscores. Dashes then are used to join the city name, administrative division +level 1 names and country names. -- Asia/Kolkata (India) -- Asia/Singapore (Singapore) -- America/Mexico_City (Mexico) -- Asia/Saigon (Vietnam) -- America/Los_Angeles (Pacific) +Alternatively, a fixed timezone can be specified as an offset like `+08:00`. +This caters for scenarios where the local DST and other local time differences +should not be accounted for. These are guarenteed to be stable and accurate. -### GeoNames +## Timezone Data + +Go [relies on local tzdata](https://golang.org/pkg/time/#LoadLocation), and thus +`datetime.link` relies on local tzdata. + +## Upcoming Improvements + +See [Issues](https://github.com/serverwentdown/datetime.link/issues). -Sources: -- `cities15000.txt` -- `countryInfo.txt` -- diff --git a/templates/footer.html b/templates/footer.html index 26a6673..2610a5c 100644 --- a/templates/footer.html +++ b/templates/footer.html @@ -1,11 +1,11 @@ diff --git a/templates/index.html b/templates/index.html index 5387887..2c75cff 100644 --- a/templates/index.html +++ b/templates/index.html @@ -15,10 +15,11 @@ {{$t := .Req.Time}} {{range .Req.Zones}} + {{$zoneName := .}} {{with resolveZone $app .}} {{if .Error}} - Unable to load zone. The URL path might not be valid + Unable to load zone "{{$zoneName}}". The URL path might not be valid {{else}} {{$zt := $t.In .Location}}