Documentation for iowidth_

------------------------------------------------------------------------
*A subroutine to read column widths from a global array, so that the
output display of parameter names and values align*.
------------------------------------------------------------------------

*Background*

Columnar alignment is highly desirable in a numerical output display.
The developers of the JGOFS system have devised a simple output display
algorithm:

	count the number of characters in the parameter names, then
        use this count as the width for displaying the entire column

If the parameter name character count is not sufficient to allow for the
values, the name may be extended for this purpose by adding enough
underscores, "_" , to total the desired count. Alternatively, an
attribute may be used to identify the width of the column. An example of
this form is: comment[width=30]
Note that you must use this attribute exactly, as [width=X], where X is
the width you desire to use.

*Technical aspects*

The /iowidth_()/ routine is written in the C language. Include it in an
inner method source file (ex: def.c, nm.c). This routine presumes that
the global array it references, as some variation of fldwidths[],
widths[] or tabwidths[], exists and has been populated with the
appropriate column widths for displaying the corresponding variable values.

Definition of iowidth_(), taken from outer.c:
    int iowidth_(); /* int iowidth_(vn); int *vn; Return length of
variable field indexed by vn. */

Example of iowidth_(), taken from def.c:
int iowidth_(vn) int *vn; { int i; i = tabwidths[*vn]; return i; }

In the default method, def.c, the routine named in_proclabel reads the
parameter labels, or variable names, counts the characters (including
any extending underscores) and creates an attribute, [width=/count/]
where /count/ is a number, for each parameter (column). Then, any
extending underscores are stripped from the paremeter label. If an
explicit [width=X] attribute exists in the data, then it is not
overwritten.

The ioattrout_ routine, reads each variable name's [width=X] attribute
and populates the global widths[] array.

*See code in nm.c for an alternative*

The other method which is distributed with the JGOFS system is called
nm.c. It uses a global array of attributes, as opposed to the local
array that def.c uses. This may be a preferable technique if you are
modifying your own method for width-sensing.

*Example of width-extending*

A simple file, such as the test hydrographic data, is displayed on
output like this:

press    temp     sal      o2      sigth
5.000    18.334   33.570   5.970   24.096   
25.000   12.848   34.159   6.990   25.773   
49.000   11.070   34.523   6.060   26.394   
99.000   11.093   35.090   5.340   26.831   
149.000  11.906   35.487   5.020   26.990   
199.000  10.819   35.435   4.210   27.152   
300.000  8.293    35.126   3.730   27.334   
400.000  6.363    35.046   4.640   27.546   
500.000  5.724    35.019   4.980   27.608   
...

In order to align the labels with the columns of numbers, the input
parameter labels need to be extended:

press__  temp__   sal___   o2___   sigth_
5.000    18.334   33.570   5.970   24.096   
25.000   12.848   34.159   6.990   25.773   
49.000   11.070   34.523   6.060   26.394   
99.000   11.093   35.090   5.340   26.831   
149.000  11.906   35.487   5.020   26.990   
199.000  10.819   35.435   4.210   27.152   
300.000  8.293    35.126   3.730   27.334   
400.000  6.363    35.046   4.640   27.546   
500.000  5.724    35.019   4.980   27.608   
...

Alternatively, the data could be prepared like this:

press[width=7], temp[width=6], sal[width=6], o2[width=5], sigth[width=6]
5.000    18.334   33.570   5.970   24.096   
25.000   12.848   34.159   6.990   25.773   
49.000   11.070   34.523   6.060   26.394   
99.000   11.093   35.090   5.340   26.831   
149.000  11.906   35.487   5.020   26.990   
199.000  10.819   35.435   4.210   27.152   
300.000  8.293    35.126   3.730   27.334   
400.000  6.363    35.046   4.640   27.546   
500.000  5.724    35.019   4.980   27.608   
...