In general, an IPW header file corresponds to a single function category in an IPW library. In this case, a single man page documents both the header file and the function category. For example, the man page named "bih" describes the function category for IPW basic image headers and its corresponding header file "bih.h".
However, an IPW header file may correspond to several function categories, e.g., the standard IPW header file "ipw.h". In this case, the header file has several man pages associated with it, one for each function category. The naming convention for these man pages is to use a combination of the header file's name and the function category's name. For example, the man page named "ipw-dt" is one of the man pages for the header file "ipw.h" which describes the function category for dates and times ("datetime").
The sections in the man page for an IPW header file are:
NAME SYNOPSIS DESCRIPTION SEE ALSO
These various sections are described below. The name of each section is a 2nd-level header.
Use the IPW macro "%name" to refer to the man page, instead of using its name explicity. This macro should be surrounded by bold tags, i.e.,
<B>%name</B>
Do NOT use tabs in pre-formated text, i.e., text surrounded by the tags "<PRE>" and "</PRE>". There is no guarantee that tabs will display correctly. Use only spaces.
NAME section
It specifies the name of the function category, and its brief
description. Both the name and description are specified in the
function category's Makefile, and are inserted in the man page
through the use of IPW macros.
As a general guideline, try to keep the description to a very
brief phrase since it is used in the titles and headings of
HTML versions of the man page. Look at existing IPW man pages
for a good idea for how to word the description, and to get an
idea of the proper length.
Example:
SYNOPSIS section
This section specifies how the header file is included in an
IPW program. It is tagged as pre-formatted text.
If the header file requires other header files to be included
prior to its inclusion, list those files as well.
Example:
DESCRIPTION section
This section describes what the function category represents.
Remember to preceed each paragraph with a paragraph tag "<P>".
Example:
Next, describe any public "typedef"s defined in the
header file associated with the function category. List only
those fields that are public, i.e., those fields that the
application programmer should change.
The list of fields should be PRE-formatted, and the name of
the typedef should be in boldface.
Example:
Next, list any public constants associated with the category
that are defined in header file.
Example:
Next, list any public macros associated with the category
that are defined in header file. Make sure to indicate
the type of arguments expected if it is not clear from
the macro's name or description.
Example:
An alternative to using a definition list can be used if
there is a group of related macros, for example, a set of
macros for accessing fields in a typedef.
Example:
<H2>NAME</H2>
<P>
<B>%name</B> - %description
</P>
<H2>SYNOPSIS</H2>
<PRE>
#include "ipw.h"
#include "snow.h"
</PRE>
<H2>DESCRIPTION</H2>
<P>
Basic image headers for IPW images describe the images'
basic properties, e.g., the number of lines in the image,
the number of samples per line, the number of pixels (bands)
per sample, the number of bits per pixel, etc.
<P>
A date-time combination in IPW is represented by a single
typedef:
<PRE>
typedef <B>datetime_t</B> has these fields:
int year; /* year (note: 90 = 90 AD, not 1990) */
int month; /* month [1 - 12] */
int day; /* day of month [1 - 31] */
int hour; /* time of day: hour [0 - 23] */
int min; /* " " " : minutes [0 - 59] */
int sec; /* " " " : seconds [0 - 59] */
</PRE>
<P>
<B>Constants</B>
<P>
<DL>
<DT><SAMP>SECS_IN_MIN</SAMP>
<DD>
# of seconds in a minute (integer).
</DD>
<P>
<DT><SAMP>SECS_IN_HR</SAMP>
<DD>
# of seconds in an hour (integer).
</DD>
<P>
<DT><SAMP>SECS_IN_HR</SAMP>
<DD>
# of seconds in an hour.
</DD>
<P>
<DT><SAMP>SECS_IN_DAY</SAMP>
<DD>
# of seconds in a day.
</DD>
</DL>
<P>
<B>Macros</B>
<P>
<DT><SAMP>HR_TO_MIN(h)</SAMP>
<DD>
Convert # of hours (h) into # of minutes.
</DD>
<P>
<DT><SAMP>HMS_TO_SEC(h,m,s)</SAMP>
<DD>
Convert a time in hours (h), minutes (m), and seconds (s) into
a total # of seconds.
</DD>
<P>
<DT><SAMP>DAYS_IN_YR(y)</SAMP>
<DD>
Returns the # of days in a given calendar year (y). Handles
leap years, so it returns either 365 or 366.
</DD>
</DL>
<P>
The following macros are defined for accessing the fields in the
BIH_T structure:
<PRE>
BIH_T * p;
bih_byteorder(p)
bih_nlines(p)
bih_nsamps(p)
bih_nbands(p)
bih_nbytes(p)
bih_nbits(p)
bih_history(p)
bih_annot(p)
</PRE>
IPW documentation /
Last revised 29 May 2009 /
IPW web site