
Standards
---------
Relevant pseudo-standards docs:
    IAU style manual, section 5.1, 1989
        http://www.iau.org/static/publications/stylemanual1989.pdf
    OGIP memo OGIP/93-001, 1993
        ftp://legacy.gsfc.nasa.gov/fits_info/fits_formats/docs/general/ogip_93_001/ogip_93_001.ps
    Standards for Astronomical Catalogues, Version 2.0, section 3.2, 2000
        http://cdsweb.u-strasbg.fr/doc/catstd-3.2.htx
    FITS, section 4.3; see v3.0 (W.D. Pence et al., A&A 524, A42, 2010
        doi:10.1051/0004-6361/201015362) and v4.0
        https://fits.gsfc.nasa.gov/fits_standard.html (all)

Standards documents:
    BIPM SI brochure
        http://www.bipm.org/utils/common/pdf/si_brochure_8_en.pdf
    IEC kibibit standard:  IEC 60027-2: 2005, third edition,
        Letter symbols to be used in electrical technology – Part 2:
        Telecommunications and electronics.  See also ISO/IEC 80000-13, which
	'ancels and replaces subclauses 3.8 and 3.9 of IEC 60027-2:2005'.
    ISO 80000.  Part 1 has general remarks, including discussion of formatting
        units, and lists the kibi-multiples, with reference to part 13.

Use of solidus: the CDS document is ambiguous; but the OGIP and IAU
styles flatly contradict each other on how many solidi can be used in
an expression: OGIP says they apply only to the following unit, IAU that
there can be only one; this matches BIPM, who say (Sect 5.1) "[a] solidus
must not be used more than once in a given expression without brackets
to remove ambiguities".  They also disagree about whether '.' or ' ' is
used for multiplication.


Sebastien's IVOA Naples notes about units:
http://www.ivoa.net/internal/IVOA/InteropMay2011Semantics/VOUnits_Semantics.pdf

The unit-manipulation library UDUNITS has various interesting features,
and is available at <http://www.unidata.ucar.edu/software/udunits/>.  It
supports reading and writing units (in a non-standardised syntax), and
some operations for defining new units, and doing arithmetic on them.


Software used
-------------

This library incorporates code to implement the
au.com.bytecode.opencsv package, from opencsv.sourceforge.net.  There
are no local modifications to that code (see file
src/grammar/tools/Notes for discussion).  That library is Copyright 2005
Bytecode Pty Ltd, and is distributed with an Apache-2.0 licence.



Other flex/yacc-like systems
----------------------------
http://www.antlr.org/
    (big multi-language system, produces parsers with runtimes)
http://byaccj.sourceforge.net/
    Port (more-or-less) of Berkeley YACC to Java.  Standalone parser
http://www2.cs.tum.edu/projects/cup/
    Parser-generator for Java
http://jflex.de/
    Lex for Java, intended to work with CUP and BYacc/J
http://www.dabeaz.com/ply/
    Python Lex-Yacc
http://www.freenet.org.nz/python/pybison/
    Another Python Bison-a-like


In order to build the Java tree, it's necessary to install jflex and
byaccj in someplace like .../tools


Portability
-----------

The library builds on OS X (tested on 10.6), on Scientific Linux, on Ubuntu, and
on OpenBSD.  It's not systematically tested on all platforms.

It's source-compatible with Java 1.5, and unity.jar is built to be
compatible with a 1.5 JRE.  The build should be tested with a Java 1.5
JDK, to ensure it's source-compatible -- the "-target 1.5" doesn't
check that.  Mark Taylor emphasised the importance of this
compatibility to the various current Java projects (within the VO)
which might potentially use this library.


Tasks
-----

TODO
----

NONE

DONE
----

Add other trig functions. (DONE 2013-07)

Add [logs] in CDS parser. (DONE 2013-07)

The CDS specification permits non-round factors (that is, factors
which aren't a power of ten).  These are now permitted in this CDS
parser.  (DONE before v0.6)

Add CDS parsing (DONE 2011-Jun-29)

Documentation: doxygen for C library (DONE 2011 July 3)

Add canonical writing functions for the various formats, and LaTeX/siunitx (DONE 2011 July 5)

Make a separately buildable distribution (DONE 2011 July 11)

Add otherwise-problematic units like 'pixel' (which shouldn't be a
pico-ixel).  How far can I go here without requiring unit validation,
which I'm not sure I do or don't want, or whether it should be optional.
(DONE 2011 July 17)

Rework recommended/deprecated to recognised (all units are known),
deprecated (all units are known but some are deprecated) and
recommended (all units known, and none deprecated)
(DONE 2011 July 18)

Fix numerous memory leaks in the C version (I hate C).  See valgrind.org
(DONE 2011 July 18)

Add IEEE binary prefixes (DONE 2013)
