Mdate
=====
Sean Dwyer <ewetoo@gmail.com>

.Revision History
******************************************************************************
0.1, 2009-06-14: Initial conversion from linuxdoc to Docbook XML

$Rev: 18 $, 2009-11-15: Minor_work.

$Id 3b7919e113e1b728e73921c3386eece98fc78a4b $, 2011-01-12: per-version updates

$Id$ : rewritten to support asciidoc processing.
******************************************************************************

.Abstract
******************************************************************************
Mdate is an easy to use command-line utility for conversion between Gregorian
calendar dates and Mayan calendar dates.
******************************************************************************

Introduction
------------

What is Mdate?
~~~~~~~~~~~~~~

Mdate was written to fill a need: a simple, freely-available program for non-
academic people interested in the Mayan calendar. Except for the Emacs Mayan
calendar mode (which has some severe limitations), this has been lacking on all
popular operating systems, which is odd considering the continuing public
interest in the Mayan civilisation.

Mdate has been in continuous development for over ten years, mostly due to the
limited interest in such a program by programmers, but fortunately not by
users.

Disclaimer & License
~~~~~~~~~~~~~~~~~~~~

This document was formerly licensed under the GNU FDL 1.1. It now falls under
the general GPL license of the accompanying code. Previous versions of this
documentation may, if wished, also fall under GPL on contact with the author.

Copyright (c) 2002-2011 by Sean Dwyer.

Please freely copy and distribute (sell or give away) this document in any
format, providing you adhere to the terms of the above License. It's requested
that corrections and/or comments be forwarded to the document maintainer.

History
~~~~~~~

The current version of Mdate is 1.7.0, written by Sean Dwyer with help from
many others over the years.

The first public version of Mdate was 0.5.0, written in late 1998, and was also
ported to MS-DOS. Craig Robbins contributed to versions 0.5.1 to 1.0.0beta1.

Version 1.0.0beta1 (1999) was the first GPL version of Mdate, and included a Tk
interface.

Mdate 1.0.5 was internationalised, and was quickly followed by version 1.1.0,
also the first version at the new sourceforge.net home.

Mdate 1.2.0 was modularised into a library (libmdate) and front-ends for Tk,
command-line and GTK+.

Mdate 1.2.8 was the last libmdate-dependent and frontend-oriented Mdate, by now
suffering from too much setup code and neglect.

Mdate 1.3.0 dropped the libmdate dependence, had a total rewrite in C++/C and a
much simpler build system, although still missing internationalisation support
and needing new front-ends.

Mdate 1.3.4 added a simple translation layer, following the mplayer method.

Mdate 1.4.0 brought in user date formatting (like date(1), and began the
process of proper internationalization and configuration, still using the
example of mplayer.

The first BeOS port was made in Mdate version 1.4.1.

Mdate 1.4.2 enhanced the language support by making it a runtime choice per an
option.

Mdate 1.4.3 added a mingw32 cross-compiler port and allowed different language
defaults.

Mdate 1.4.5 included a compile-time option to use modern Mayan calendar month
names.

Mdate 1.4.7 introduced the first FreeBSD (4.9-STABLE) port. The program-
parseable flag (-p) was rendered defunct when the parseable output became the
default output format. A new OS X (Mac 32-bit console) port also became
available.

Mdate 1.5.2 switched the VC system over to subversion, with intentions to open
up development with a better multiple developer system.

Mdate 1.5.6 was the first new release of mdate since version 1.5.1 on
sourceforge.net.

Mdate 1.5.7 was the first release on code.google.com.

Mdate 1.6.0 made the GMT correlation the default. Mdate was moved to git
version control on github.com.

Mdate 1.7.0 implemented a configuration file.

Usage
-----

Mayan Calendar Names
~~~~~~~~~~~~~~~~~~~~

From version 1.4.5, a compile-time option was added for those preferring the
new Romanized Mayan calendar names to the old ones, e.g. Kumk'u (new) for Cumku
(old) and 'Ahaw (new) for Ahau (old). I'm interested in feedback about this
option, and whether it could be a format item in its own right.

Language Support
~~~~~~~~~~~~~~~~

As at version 1.4.5, mdate supports five languages: English, Spanish, German,
French and Polish (en, es, de, fr and pl). A runtime option was added so you
could use a different language. The language support is compiled-in and
currently ignores environment language variables.

.Example usage:
------------------------------------------------------------------------------
  $ mdate -L es

  NDJ: 2453168.0 fecha: Fri 11 06 2004  12.19.11.06.03 7 Ak'bal  06 Sots
------------------------------------------------------------------------------

The default language is English (en). There is no support for regional language
subsets (eg en_AU). Other languages may be compiled as the default.

Output Format
~~~~~~~~~~~~~

The previous default behaviour of Mdate was to output a formatted printout of
current date information, using the default Lounsbury correlation for today's
date:

------------------------------------------------------------------------------
  $ mdate

  Gregorian Date    : 05-April-2002 (05/04/2002)
  Julian Day Number : 2452370.0
  Long Count        : 12.19.09.02.05
  Tzolkin Date      : 2 Chicchan
  Haab Date         : 3 Uayeb
------------------------------------------------------------------------------
However, pretty output formatting is now a compile-time option only, due to
ongoing problems (i.e. bugs) on several platforms. The old -p, --parseable flag
is now the default behavior, and outputs this information in one line, much
like date(1). 

.Example:
------------------------------------------------------------------------------
  $ mdate

  JDN: 2452370.0 date:  05  04  2002 12.19.09.02.05  02 Chicchan  03 Uayeb
------------------------------------------------------------------------------

The parseable flag is now effectively ignored when pretty formatting is not
compiled in.

Date Formatting
~~~~~~~~~~~~~~~

You may want to specify your current date in a specific way, using one of
mdate's formatting options. Here is the full list:

  @a abbreviated weekday name
  @A full weekday name
  @b abbreviated month name
  @B full month name
  @d weekday (01..31)
  @e weekday without a leading zero
  @F ISO format Gregorian date (%Y-%m-%d)
  @f ISO format Gregorian date (%Y%m%d)
  @h unpadded Haab date
  @H padded Haab date
  @l Long Count
  @M named Gregorian month
  @m numbered Gregorian month
  @T padded Tzolkin date
  @t unpadded Tzolkin date
  @y year as decimal 00 to 99
  @Y Gregorian year
  @n add a newline to the output
  @j add a tab to the output

Like date(1), mdate will format a date when given a `+' option, for example:

------------------------------------------------------------------------------
  $ mdate -d '07 09 2003' +'@f @l'

  20030907 12.19.10.10.15
------------------------------------------------------------------------------

This was specifically requested for those who like to add a Mayan byline to
emails and web pages. However, mdate has not ever supported time of day
parsing/formatting, so it's not rfc822 compliant! Most formats are merely
passed on to strftime(3) where applicable.

Correlation Options
~~~~~~~~~~~~~~~~~~~

By default, Mdate used the Lounsbury correlation which is equivalent to the
Julian Day Number 584285 in versions of Mdate prior to 1.6.0. Since then the
GMT correlation is standard.
The -g, --gmt option uses the standard Goodman-Martinez-Thompson correlation
(GMT for short). It corresponds to the Julian Day Number 584283. Versions of
Mdate from 1.6.0 silently ignores this option.
If you don't agree with the correlation constant, the -c, --correlation
[=DOUBLE] allows you to specify a correlation of your own. Don't be surprised,
however if it doesn't work the way you intended, especially if you set the
Julian Day Number too low (see Limitations to understand why!)

Date Input
~~~~~~~~~~

You probably want to check a specific date at some point. This can be done in
several different ways, depending on the kind of date you already have.
The -d, --dmy[="dd mm [-]yyyy"] option allows you to specify a Gregorian date.
You can also specify negative (BC) years.

------------------------------------------------------------------------------
  $ mdate -d '05 04 2002'

  JDN: 2452311.0 date: Tues 05 02 2002  12.19.08.17.06 8 Kimi  04 Pax
------------------------------------------------------------------------------
In the same way, the -j, --julian=[DOUBLE] option will output the date with a
specified Julian Day Number:
------------------------------------------------------------------------------
  $ mdate -j 2452370

  JDN: 2452370.0 date: Fri 05 04 2002  12.19.09.02.05 2 Chik'chan  03 Wayeb
------------------------------------------------------------------------------
Notice that you can leave the decimal part out if you wish.
Finally, the -l, --longcount[="nn nn nn nn nn"] option does the same thing with
a Mayan long count date input:
------------------------------------------------------------------------------
  $ mdate -l '12 19 09 02 05'

  JDN: 2452370.0 date: Fri 05 04 2002  12.19.09.02.05 2 Chik'chan  03 Wayeb
------------------------------------------------------------------------------

Miscellaneous Options
~~~~~~~~~~~~~~~~~~~~~

The -h, --help option gives a simple display of help for Mdate.
The -v, -V, --version option outputs version information for Mdate.

Limitations
-----------

Mdate does not support any dates beyond the beginning of the current epoch
(longcount 0.0.0.0.0) matching with the Julian Day Number correlation,
including Gregorian dates. However, you can have fun with correlations, for
example:
------------------------------------------------------------------------------
  $ mdate -c 584285 -j 584285 '+@J @d @m @Y @l @h @t'

  584285.0 13 08 -3113 00.00.00.00.00 8 Kumk'u  04 'Ahaw
------------------------------------------------------------------------------
However, the Mayan date above is meaningless :)
