%N pgtbox %F $MIR/src/pgtbox.f
%D Draw frame and write (DD) HH MM SS.S labelling
%B
      SUBROUTINE PGTBOX (XOPT, XTICK, NXSUB, YOPT, YTICK, NYSUB)

      REAL XTICK, YTICK
      INTEGER NXSUB, NYSUB
      CHARACTER XOPT*(*), YOPT*(*)

 Draw a box and optionally label one or both axes with (DD) HH MM SS 
 style numeric labels (useful for time or RA - DEC plots).   If this 
 style of labelling is desired, then PGSWIN should have been called
 previously with the extrema in SECONDS of time.

 In the seconds field, you can have at most 3 places after the decimal
 point, so that 1 ms is the smallest time interval you can time label.

 Large numbers are coped with by fields of 6 characters long.  Thus 
 you could have times with days or hours as big as 999999.  However, 
 in practice, you might have trouble with labels overwriting  themselves
 with such large numbers unless you a) use a small time INTERVAL, 
 b) use a small character size or c) choose your own sparse ticks in 
 the call to PGTBOX.  

 PGTBOX will attempt, when choosing its own ticks, not to overwrite
 the labels, but this algorithm is not very bright and may fail.

 Note that small intervals but large absolute times such as
 TMIN = 200000.0 s and TMAX=200000.1 s will cause the algorithm
 to fail.  This is inherent in PGPLOT's use of single precision
 and cannot be avoided.  In such cases, you should use relative
 times if possible.

 PGTBOX's labelling philosophy is that the left-most or bottom tick of
 the axis contains a full label.  Thereafter, only changing fields are
 labelled.  Negative fields are given a '-' label, positive fields
 have none.   Axes that have the DD (or HH if the day field is not
 used) field on each major tick carry the sign on each field.  If the
 axis crosses zero, the zero tick will carry a full label and sign.

 This labelling style can cause a little confusion with some special
 cases, but as long as you know its philosophy, the truth can be divined.
 Consider an axis with TMIN=20s, TMAX=-20s.   The labels will look like

        +----------+----------+----------+----------+
     0h0m20s      10s      -0h0m0s      10s        20s

 Knowing that the left field always has a full label and that
 positive fields are unsigned, informs that time is decreasing
 from left to right, not vice versa.   This can become very 
 unclear if you have used the 'F' option, but that is your problem !

 Exceptions to this labelling philosophy are when the finest time
 increment being displayed is hours (with option 'Y') or days.  
 Then all fields carry a label.  For example,

        +----------+----------+----------+----------+
      -10h        -8h        -6h        -4h        -2h

 PGTBOX can be used in place of PGBOX; it calls PGBOX and only invokes 
 time labelling if requested. Other options are passed intact to PGBOX.

 Inputs:
  XOPT   :  X-options for PGTBOX.  Same as for PGBOX plus 

             'Z' for (DD) HH MM SS.S time labelling
             'Y' means don't include the day field so that labels
                 are HH MM SS.S rather than DD HH MM SS.S   The hours
                 will accumulate beyond 24 if necessary in this case.
             'X' label the HH field as modulo 24.  Thus, a label
                 such as 25h 10m would come out as 1h 10m
             'H' means superscript numbers with d, h, m, & s  symbols
             'D' means superscript numbers with    o, ', & '' symbols 
             'F' causes the first label (left- or bottom-most) to
                 be omitted. Useful for sub-panels that abut each other.
                 Care is needed because first label carries sign as well.
             'O' means omit leading zeros in numbers < 10
                 E.g.  3h 3m 1.2s rather than 03h 03m 01.2s  Useful
                 to help save space on X-axes. The day field does not 
                 use this facility.

  YOPT   :  Y-options for PGTBOX.  See above.
  XTICK  :  X-axis major tick increment.  0.0 for default. 
  YTICK  :  Y-axis major tick increment.  0.0 for default. 
            If the 'Z' option is used then XTICK and/or YTICK must
            be in seconds.
  NXSUB  :  Number of intervals for minor ticks on X-axis. 0 for default
  NYSUB  :  Number of intervals for minor ticks on Y-axis. 0 for default

  The regular XOPT and YOPT axis options for PGBOX are

  A : draw Axis (X axis is horizontal line Y=0, Y axis is vertical
      line X=0).
  B : draw bottom (X) or left (Y) edge of frame.
  C : draw top (X) or right (Y) edge of frame.
  G : draw Grid of vertical (X) or horizontal (Y) lines.
  I : Invert the tick marks; ie draw them outside the viewport
      instead of inside.
  L : label axis Logarithmically (see below).
  N : write Numeric labels in the conventional location below the
      viewport (X) or to the left of the viewport (Y).
  P : extend ("Project") major tick marks outside the box (ignored if
      option I is specified).
  M : write numeric labels in the unconventional location above the
      viewport (X) or to the right of the viewport (Y).
  T : draw major Tick marks at the major coordinate interval.
  S : draw minor tick marks (Subticks).
  V : orient numeric labels Vertically. This is only applicable to Y.
      The default is to write Y-labels parallel to the axis.
  1 : force decimal labelling, instead of automatic choice (see PGNUMB).
  2 : force exponential labelling, instead of automatic.

      The default is to write Y-labels parallel to the axis

        ******************        EXCEPTIONS       *******************

        Note that 
          1) PGBOX option 'L' (log labels) is ignored with option 'Z'
          2) The 'O' option will be ignored for the 'V' option as it 
             makes it impossible to align the labels nicely
          3) Option 'Y' is forced with option 'D'

        ***************************************************************
