[nongnu] elpa/datetime 61e63cd061 014/147: Expand package documentation.

[ELPA Syncer]

branch: elpa/datetime
commit 61e63cd061c8730441e89a8292acdc85b540d7dc
Author: Paul Pogonyshev <pogonyshev@gmail.com>
Commit: Paul Pogonyshev <pogonyshev@gmail.com>

    Expand package documentation.
---
 README.md   | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++----
 datetime.el | 27 +++++++++++++++++++--
 2 files changed, 100 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 1068b50dfd..9ac171447a 100644
--- a/README.md
+++ b/README.md
@@ -1,12 +1,11 @@
 # datetime
 
 Datetime is a library for parsing, formatting, matching and recoding
-timestamps and date-time format strings.  It is written as a utility
-for Logview, so currently most of functionality not needed for that
-mode is *not implemented*.
+timestamps and date-time format strings.  Not all of the planned
+functionality is implemented yet.
 
 
-### Pattern types
+## Pattern types
 
 There exist several different ways to specify date and/or time format.
 Different programming language and their libraries use different
@@ -21,3 +20,75 @@ This library currently uses Java pattern format, but is 
internally
 written in such a way that support for other types can be added
 relatively easily.
 
+
+## Formatting timestamps
+
+To format timestamps you first need to create a *formatter function*.
+This function accepts one argument — the timestamp as a floating point
+number — and converts it to a string.  All customization, most
+importantly, specifying the pattern, is done at the point of creating
+the formatter.
+
+For example:
+
+    (datetime-float-formatter 'java "yyyy-MM-dd HH:mm:ss.SSS"
+                              :timezone 'system)
+
+With this formatter function you can now format timestamps as follows:
+
+    (let ((formatter (datetime-float-formatter 'java "yyyy-MM-dd HH:mm:ss.SSS"
+                                               :timezone 'system)))
+      (funcall formatter (float-time)))
+
+Note that if you plan to format result of `float-time` function, you
+need to pass `'system` as `:timezone` option to
+`datetime-float-formatter`: default timezone is UTC.
+
+
+## Matching timestamps
+
+Sometimes you need to determine if given string is (likely) a
+timestamp, corresponding to given pattern.  A robust way, of course,
+is to try to parse it.  However, it is much faster, though not as
+precise, to use a regular expression.
+
+Function `datetime-matching-regexp` builds such a regular expression
+for given pattern.  For example,
+
+    (datetime-matching-regexp 'java "yyyy-MM-dd HH:mm:ss.SSS")
+
+returns a regexp that will match all timestamp strings produced by the
+formatter we created earlier.  It will also match some other strings,
+but is good enough in practice to tell if “this does look like a
+timestamp”.
+
+
+## Other functions
+
+These functions are also part of the library interface.  They are
+documented within Emacs.
+
+* `datetime-recode-pattern`
+
+* `datetime-pattern-locale-dependent-p`
+* `datetime-pattern-includes-date-p`
+* `datetime-pattern-includes-time-p`
+* `datetime-pattern-includes-era-p`
+* `datetime-pattern-includes-year-p`
+* `datetime-pattern-includes-month-p`
+* `datetime-pattern-includes-week-p`
+* `datetime-pattern-includes-day-p`
+* `datetime-pattern-includes-weekday-p`
+* `datetime-pattern-includes-hour-p`
+* `datetime-pattern-includes-minute-p`
+* `datetime-pattern-includes-second-p`
+* `datetime-pattern-includes-millisecond-p`
+* `datetime-pattern-includes-timezone-p`
+
+* `datetime-list-locales`
+* `datetime-list-timezones`
+
+* `datetime-locale-date-pattern`
+* `datetime-locale-time-pattern`
+* `datetime-locale-date-time-pattern`
+* `datetime-locale-field`
diff --git a/datetime.el b/datetime.el
index 5c3041cb5b..e641cabd51 100644
--- a/datetime.el
+++ b/datetime.el
@@ -25,8 +25,31 @@
 
 ;;; Commentary:
 
-;; Library that provides support for formatting, parsing and matching
-;; timestamps in certain format.
+;; Library for generic timestamp handling.  It is targeted at bulk
+;; processing, therefore many functions are optimized for speed, but
+;; not necessarily for ease of use.  For example, formatting is done
+;; in two steps: first you need to generate a formatting function for
+;; given pattern, and only using it obtain formatted strings.
+;;
+;; Package's main feature currently is timestamp formatting based on
+;; Java pattern.  Arbitrary timezones and locales (i.e. not
+;; necessarily those used by the system) are supported.  See function
+;; `datetime-float-formatter' for details.
+;;
+;; Library also supports timestamp matching.  It can generate regular
+;; expressions that match timestamps corresponding to given pattern.
+;; These regular expressions can give false positives, but for most
+;; purposes are good enough to detect timestamps in text files,
+;; e.g. in various application logs.  See `datetime-matching-regexp'.
+;;
+;; Finally, library provides functions to select an appropriate
+;; timestamp format for given locale.  For example, function
+;; `datetime-locale-date-pattern' returns a Java pattern suitable for
+;; formatting date only, without time part.  However, it is not
+;; required that formats are generated this way.
+;;
+;; Timestamp parsing is currently not implemented, but planned for a
+;; future version.
 
 
 ;;; Code: