--- psiconv/trunk/lib/psiconv/data.h	2004/01/18 19:58:12	187
+++ psiconv/trunk/lib/psiconv/data.h	2004/01/26 12:59:54	188
@@ -18,8 +18,11 @@
 */
 
 /* This file contains the declarations of all types that are used to
-   represent the Word file. Variables of these types are written by the
-   parse routines, and read by the generation routines. */
+   represent the Psion files. Variables of these types are written by the
+   parse routines, and read by the generation routines. 
+   
+   Mostly, the data structures reflect the file format documentation,
+   as included in the formats directory. When in doubt, refer there. */
 
 #ifndef PSICONV_DATA_H
 #define PSICONV_DATA_H
@@ -28,7 +31,7 @@
 #include <psiconv/list.h>
 
 /* All types which end on _t are plain types; all other types are pointers
-   to structs */
+   to structs. */
 
 #ifdef __cplusplus
 extern "C" {
@@ -37,8 +40,14 @@
 /* Forward declaration (for psiconv_embedded_object_section) */
 typedef struct psiconv_file_s *psiconv_file;
 
+
+/* Enums and simple types */
+
+
+/* Floating point number representation */
 typedef double psiconv_float_t;
 
+/* The supported file types. */
 typedef enum psiconv_file_type {
   psiconv_unknown_file,
   psiconv_word_file,
@@ -49,25 +58,28 @@
   psiconv_sheet_file
 } psiconv_file_type_t;
   
-/* Length indicators */
-typedef psiconv_u32 psiconv_S_t;
-typedef psiconv_u32 psiconv_X_t;
-
-/* A string */
+/* String representation. A string is an array of UCS2 characters, terminated
+   by a 0. So they are just like normal C strings, except that they are built
+   of psiconv_ucs2 elements instead of char elements.
+   The psiconv_ucs2 type holds 16 bits; see unicode.h for more information. */
 typedef psiconv_ucs2 *psiconv_string_t;
 
-/* In the Psion file, these are identical; but we translate them to more
+/* Represent lengths (in centimeters) and sizes (in points).
+   In the Psion file, these are identical; but we translate them to more
    human-readable quantities */
 typedef float psiconv_length_t;    /* For offsets in centimeters */
 typedef float psiconv_size_t;      /* For sizes in points */
 
-/* Some enums */
+/* Represent booleans. As false is zero in the enum, you can still do things
+   like { if (test) ... } instead of { if (test == psiconv_bool_true) ... }.
+   Choose whatever style suits you best. */
 typedef enum psiconv_bool
 {
   psiconv_bool_false,
   psiconv_bool_true
 } psiconv_bool_t;
 
+/* Some kind of three-valued boolean, used at several places. */
 typedef enum psiconv_triple
 {
   psiconv_triple_on,
@@ -75,12 +87,16 @@
   psiconv_triple_auto
 } psiconv_triple_t;
 
+/* Text can be in superscript or subscript or neither, but never both
+   superscript and subscript at once. Also, super-superscript and things
+   like that do not exist in the Psion world. */
 typedef enum psiconv_super_sub
 { psiconv_normalscript,
   psiconv_superscript,
   psiconv_subscript
 } psiconv_super_sub_t;
 
+/* Horizontal justification. */
 typedef enum psiconv_justify_hor
 { psiconv_justify_left, 
   psiconv_justify_centre, 
@@ -88,33 +104,60 @@
   psiconv_justify_full 
 } psiconv_justify_hor_t;
 
+/* Vertical justification. */
 typedef enum psiconv_justify_ver
 { psiconv_justify_top,
   psiconv_justify_middle,
   psiconv_justify_bottom
 } psiconv_justify_ver_t;
 
+/* Borders around text fields. */
 typedef enum psiconv_border_kind
-{ psiconv_border_none,
-  psiconv_border_solid,
-  psiconv_border_double,
-  psiconv_border_dotted,
-  psiconv_border_dashed,
-  psiconv_border_dotdashed,
-  psiconv_border_dotdotdashed
+{ psiconv_border_none,            /* No border */
+  psiconv_border_solid,           /* Single line */
+  psiconv_border_double,          /* Double line */
+  psiconv_border_dotted,          /* Dotted line: . . . . . */
+  psiconv_border_dashed,          /* Dashed line: _ _ _ _ _ */
+  psiconv_border_dotdashed,       /* Dotted/dashed line: _ . _ . _ */
+  psiconv_border_dotdotdashed     /* Dotted/dashed line: . . _ . . _ */
 } psiconv_border_kind_t;
 
+/* Though each printer driver has its own fonts for printing, they are
+   represented on the Psion screen by a few built-in fonts. */
 typedef enum psiconv_screenfont
 {
-  psiconv_font_misc,
-  psiconv_font_sansserif,
-  psiconv_font_nonprop,
-  psiconv_font_serif
+  psiconv_font_misc,          /* Nonproportional symbols, like Wingbat? */
+  psiconv_font_sansserif,     /* Proportional sans-serif, like Arial */
+  psiconv_font_nonprop,       /* Nonproportional, like Courier */
+  psiconv_font_serif          /* Proportional serifed, like Times */
 } psiconv_screenfont_t;
 
-/* Colors.
-   black: 0x00 0x00 0x00 
-   white: 0xff 0xff 0xff */
+
+/* The kind of tab. Note that decimal tabs are not supported by the Psion. */
+typedef enum psiconv_tab_kind
+{
+  psiconv_tab_left,      /* Left tab */
+  psiconv_tab_centre,    /* Centre tab */
+  psiconv_tab_right      /* Right tab */
+} psiconv_tab_kind_t;
+
+/* When text has to be replaced, the kind of replacement to do
+   (not yet implemented!) */
+typedef enum psiconv_replacement_type
+{
+  psiconv_replace_time,
+  psiconv_replace_date,
+  psiconv_replace_pagenr,
+  psiconv_replace_nr_of_pages,
+  psiconv_replace_filename
+} psiconv_replacement_type_t;
+
+
+/* Here starts the struct definitions */
+
+/* The color of a single pixel, in RGB format.
+   Black: 0x00 0x00 0x00 
+   White: 0xff 0xff 0xff */
 typedef struct psiconv_color_s
 {
   psiconv_u8 red;
@@ -122,90 +165,125 @@
   psiconv_u8 blue;
 } * psiconv_color;
 
+
+/* Complete font information: both a printer font and a corresponding screen
+   font to display it. */
 typedef struct psiconv_font_s
 {
-  psiconv_string_t name;
-  psiconv_screenfont_t screenfont;
+  psiconv_string_t name;             /* Printer font */
+  psiconv_screenfont_t screenfont;   /* Screen font */
 } *psiconv_font;
 
+/* Complete border information */
 typedef struct psiconv_border_s
 { 
-  psiconv_border_kind_t kind;
-  psiconv_size_t thickness; /* Set to 1/20 for non-solid lines */
-  psiconv_color color;
+  psiconv_border_kind_t kind;   /* Border kind */
+  psiconv_size_t thickness;     /* Set to 1/20 for non-solid lines */
+  psiconv_color color;          /* Border color */
 } *psiconv_border;
 
+/* Complete bullet information.
+   If indent if off, the bullet is at the first line indentation level,
+   and the line text begins right after it. If it is on, the bullet is at 
+   the minimum of the first line and left indentation, and the text starts
+   at the maximum of both. */
 typedef struct psiconv_bullet_s
 {
-  psiconv_bool_t on;
-  psiconv_size_t font_size;
-  psiconv_ucs2 character;
-  psiconv_bool_t indent;
-  psiconv_color color;
-  psiconv_font font;
+  psiconv_bool_t on;           /* Whether the bullet is shown */
+  psiconv_size_t font_size;    /* Bullet font size */
+  psiconv_ucs2 character;      /* Bullet character */
+  psiconv_bool_t indent;       /* Whether to indent (see above */
+  psiconv_color color;         /* Bullet color */
+  psiconv_font font;           /* Bullet font */
 } *psiconv_bullet;
 
-typedef enum psiconv_tab_kind
-{
-  psiconv_tab_left,
-  psiconv_tab_centre,
-  psiconv_tab_right
-} psiconv_tab_kind_t;
-
+/* Complete single tab information */
 typedef struct psiconv_tab_s
 {
-  psiconv_length_t location;
-  psiconv_tab_kind_t kind;
+  psiconv_length_t location;      /* The indentation level */
+  psiconv_tab_kind_t kind;        /* Tab kind */
 } *psiconv_tab;
 
+/* A list of tabs */
+typedef psiconv_list psiconv_tab_list; /* of struct psiconv_tab_s */
 
-typedef psiconv_list psiconv_tab_list; /* of struct psiconv_tab */
-
+/* Information about all tabs.
+   Normal tabs start after the rightmost extra tab */
 typedef struct psiconv_all_tabs_s
 {
-  psiconv_length_t normal;
-  psiconv_tab_list extras;
+  psiconv_length_t normal;        /* Normal tab distance */
+  psiconv_tab_list extras;        /* Additional defined tabs */
 } *psiconv_all_tabs;
 
+/* Character layout.
+   This structure holds all layout information that can be applied on the
+   character level (as opposed to layouts that only apply to whole 
+   paragraphs). 
+   Note that at all times, this structure holds the complete layout 
+   information; we do not use incremental layouts, unlike the Psion
+   file format itself. So if an italic text is also underlined, the 
+   character_layout will have both set for that region. */
 typedef struct psiconv_character_layout_s
 {
-  psiconv_color color;
-  psiconv_color back_color;
-  psiconv_size_t font_size;
-  psiconv_bool_t italic;
-  psiconv_bool_t bold;
-  psiconv_super_sub_t super_sub;
-  psiconv_bool_t underline;
-  psiconv_bool_t strikethrough;
-  psiconv_font font; 
+  psiconv_color color;             /* Character color */
+  psiconv_color back_color;        /* Background color */
+  psiconv_size_t font_size;        /* Font size */
+  psiconv_bool_t italic;           /* Use italics? */
+  psiconv_bool_t bold;             /* Use bold? */
+  psiconv_super_sub_t super_sub;   /* Use super/subscript? */
+  psiconv_bool_t underline;        /* Underline? */
+  psiconv_bool_t strikethrough;    /* Strike through? */
+  psiconv_font font;               /* Character font */
 } *psiconv_character_layout;
 
+/* Paragraph layout.
+   This structure holds all layout information that can be applied on the
+   paragraph level (as opposed to layouts that also apply to single 
+   characters). 
+   Note that at all times, this structure holds the complete layout 
+   information; we do not use incremental layouts, unlike the Psion 
+   file format itself. 
+   Linespacing is the amount of vertical space between lines. If
+   linespacing_exact is set, this amount is used even if that would make
+   text overlap; if it is not set, a greater distance is used if text would
+   otherwise overlap.
+   Several booleans determine where page breaks may be set. keep_together
+   forbids page breaks in the middle of the paragraph; keep_with_next
+   forbids page breaks between this and the next paragraph. on_next_page
+   forces a pagebreak before the paragraph. no_widow_protection allows
+   one single line of the paragraph on a page, and the rest on another page. 
+   Sheet cell text normally does not wrap; wrap_to_fit_cell allows this. */
 typedef struct psiconv_paragraph_layout_s
 {
-  psiconv_color back_color;
-  psiconv_length_t indent_left;
-  psiconv_length_t indent_right;
-  psiconv_length_t indent_first;
-  psiconv_justify_hor_t justify_hor;
-  psiconv_justify_ver_t justify_ver;
-  psiconv_size_t linespacing;
-  psiconv_bool_t linespacing_exact;
-  psiconv_size_t space_above;
-  psiconv_size_t space_below;
-  psiconv_bool_t keep_together;
-  psiconv_bool_t keep_with_next;
-  psiconv_bool_t on_next_page;
-  psiconv_bool_t no_widow_protection;
-  psiconv_bool_t wrap_to_fit_cell;
-  psiconv_length_t border_distance;
-  psiconv_bullet bullet;
-  psiconv_border left_border;
-  psiconv_border right_border;
-  psiconv_border top_border;
-  psiconv_border bottom_border;
-  psiconv_all_tabs tabs;
+  psiconv_color back_color;           /* Background color */
+  psiconv_length_t indent_left;       /* Left indentation (except first line) */
+  psiconv_length_t indent_right;      /* Right indentation */
+  psiconv_length_t indent_first;      /* First line left indentation */
+  psiconv_justify_hor_t justify_hor;  /* Horizontal justification */
+  psiconv_justify_ver_t justify_ver;  /* Vertical justification */
+  psiconv_size_t linespacing;         /* The linespacing */
+  psiconv_bool_t linespacing_exact;   /* Is linespacing exact or the minimum? */
+  psiconv_size_t space_above;         /* Vertical space before the paragraph */
+  psiconv_size_t space_below;         /* Vertical space after the paragraph */
+  psiconv_bool_t keep_together;       /* Keep lines on one page? */
+  psiconv_bool_t keep_with_next;      /* Disallow pagebreak after paragraph? */
+  psiconv_bool_t on_next_page;        /* Force page break before paragraph? */
+  psiconv_bool_t no_widow_protection; /* Undo widow protection? */
+  psiconv_bool_t wrap_to_fit_cell;    /* Wrap sheet cell text? */
+  psiconv_length_t border_distance;   /* Distance to borders */
+  psiconv_bullet bullet;              /* Bullet information */
+  psiconv_border left_border;         /* Left border information */
+  psiconv_border right_border;        /* Right border information */
+  psiconv_border top_border;          /* Top border information */
+  psiconv_border bottom_border;       /* Bottom border information */
+  psiconv_all_tabs tabs;              /* All tab information */
 } *psiconv_paragraph_layout;
 
+/* A Header Section.
+   It contains the three UIDs and the checksum, and the type of file.
+   As the type of file uniquely defines the UIDs, and as the UIDs determine
+   the checksum, this is never included in a regular psiconv_file structure.
+   It can be used to read the header section separately, though. */
 typedef struct psiconv_header_section_s
 {
   psiconv_u32 uid1;
@@ -215,180 +293,260 @@
   psiconv_file_type_t file;
 } *psiconv_header_section;
 
+/* A Section Table Section entry.
+   Each entry has a UID and an offset.
+   This is never included in a regular psiconv_file structure, as the 
+   information is too low-level. It is used internally, though. */
 typedef struct psiconv_section_table_entry_s
 {
-  psiconv_u32 id;
-  psiconv_u32 offset;
+  psiconv_u32 id;           /* Section UID */
+  psiconv_u32 offset;       /* Section offset within the file */
 } *psiconv_section_table_entry;
 
+/* A Section Table Section.
+   A list of sections and their offsets.
+   It is simply a list of Section Table Section Entries.
+   This is never included in a regular psiconv_file structure, as the 
+   information is too low-level. It is used internally, though. */
 typedef psiconv_list psiconv_section_table_section; 
-/* Of struct sectiontable_entry */
+                                   /* Of struct psiconv_sectiontable_entry_s */
 
+/* An Application ID Section.
+   The type of file.
+   Never included in a regular psiconv_file structure, because it is too
+   low-level. You can always recover it if you know the file type. Used
+   internally. 
+   The name should probably be case-insensitive. */
 typedef struct psiconv_application_id_section_s
 {
-  psiconv_u32 id;
-  psiconv_string_t name;
+  psiconv_u32 id;            /* File type UID */
+  psiconv_string_t name;     /* File type name */
 } *psiconv_application_id_section;
 
+/* An Object Icon Section.
+   The icon used for an embedded object. */
 typedef struct psiconv_object_icon_section_s
 {
-  psiconv_length_t icon_width;
-  psiconv_length_t icon_height;
-  psiconv_string_t icon_name;
+  psiconv_length_t icon_width;      /* Icon width */
+  psiconv_length_t icon_height;     /* Icon height */
+  psiconv_string_t icon_name;       /* Icon name */
 } *psiconv_object_icon_section;
 
+/* An Object Display Section.
+   How an embedded icon should be displayed. 
+   The sizes are computed after cropping or resizing; if the object is shown
+   as an icon, the icon sizes are used here. */
 typedef struct psiconv_object_display_section_s
 {
-  psiconv_bool_t show_icon;
-  psiconv_length_t width;
-  psiconv_length_t height;
+  psiconv_bool_t show_icon;         /* Show an icon or the whole file? */
+  psiconv_length_t width;           /* Object display width */
+  psiconv_length_t height;          /* Object display height */
 } *psiconv_object_display_section;
 
+/* An Embedded Object Section. 
+   All data about an embedded object. 
+   An object is another psiconv_file, which is embedded in the current
+   file. Objects can also be embedded in each other, of course. */
 typedef struct psiconv_embedded_object_section_s
 {
-  psiconv_object_icon_section icon;
-  psiconv_object_display_section display;
-  psiconv_file object;
+  psiconv_object_icon_section icon;       /* Icon information */
+  psiconv_object_display_section display; /* Display information */
+  psiconv_file object;                    /* The object itself */
 } *psiconv_embedded_object_section;
 
+/* Inline character-level layout information.
+   Information how some characters should be laid out. 
+   Note that, though you can choose specific layouts for an object, this
+   will probably not affect the object's rendering.
+   Usually, object will be NULL, and the object_width and object_height 
+   will be ignored. 
+   The object sizes are the same as in the Object Display Section, so
+   this information seems to be redundant. */
 typedef struct psiconv_in_line_layout_s
 {
-  psiconv_character_layout layout;
-  int length;
-  /* If object is NULL, this does not apply to an object */
-  psiconv_embedded_object_section object;
-  psiconv_length_t object_width;
-  psiconv_length_t object_height;
+  psiconv_character_layout layout;         /* Layout information */
+  int length;                              /* Number of characters */
+  psiconv_embedded_object_section object;  /* Embedded object or NULL */
+  psiconv_length_t object_width;           /* Object display width */
+  psiconv_length_t object_height;          /* Object display height */
 } *psiconv_in_line_layout;
 
-typedef psiconv_list psiconv_in_line_layouts; /* of struct in_line_layout */
-
-typedef enum psiconv_replacement_type
-{
-  psiconv_replace_time,
-  psiconv_replace_date,
-  psiconv_replace_pagenr,
-  psiconv_replace_nr_of_pages,
-  psiconv_replace_filename
-} psiconv_replacement_type_t;
+/* Inline character information for a whole line.
+   A list of inline character information */
+typedef psiconv_list psiconv_in_line_layouts; 
+                                  /* of struct psiconv_in_line_layout_s */
 
+/* What to replace where in text. Not yet implemented! 
+   (not yet implemented!) */
 typedef struct psiconv_replacement_s
 {
-  int offset;
-  int cur_len;
-  psiconv_replacement_type_t type;
+  int offset;                       /* Offset in text */
+  int cur_len;                      /* Length of text to replace */
+  psiconv_replacement_type_t type;  /* Kind of replacement */
 } *psiconv_replacement;
 
-typedef psiconv_list psiconv_replacements; /* of struct replacement */
+/* A list of replacements */
+typedef psiconv_list psiconv_replacements; /* of struct psiconv_replacement_s */
 
+/* A paragraph of text.
+   Layout and actual paragraph text are combined here, even though
+   they are seperated in the Psion file format.
+   The base style is referred to, but the base_character and
+   base_paragraph have all style settings already incorporated.
+   The base style can be found using the psiconv_get_style function. 
+   The in_lines are either an empty list, or they should apply to exactly
+   the number of characters in this paragraph */
 typedef struct psiconv_paragraph_s
 {
-  psiconv_string_t text;
-  psiconv_character_layout base_character;
-  psiconv_paragraph_layout base_paragraph;
-  psiconv_s16 base_style;
-  psiconv_in_line_layouts in_lines;
-  psiconv_replacements replacements;
+  psiconv_string_t text;                     /* Paragraph text */
+  psiconv_character_layout base_character;   /* Base character layout */
+  psiconv_paragraph_layout base_paragraph;   /* Base paragraph layout */
+  psiconv_s16 base_style;                    /* Paragraph style */
+  psiconv_in_line_layouts in_lines;          /* In-paragraph layout */
+  psiconv_replacements replacements;         /* Replacements like the date */
 } *psiconv_paragraph;
 
-typedef psiconv_list psiconv_text_and_layout; /* Of struct paragraphs */
+/* A collection of text paragraphs */
+typedef psiconv_list psiconv_text_and_layout; 
+                                          /* Of struct psiconv_paragraph_s */
 
+/* A TextEd Section.
+   Text and simple layout, without styles.  */
 typedef struct psiconv_texted_section_s
 {
   psiconv_text_and_layout paragraphs; 
 } *psiconv_texted_section;
 
+/* A Page Header.
+   All information about a page header or footer.
+   An explicit base paragraph and character layout is found; this is used
+   as a sort of base style, on which all further formatting is based */
 typedef struct psiconv_page_header_s
 {
-  psiconv_bool_t on_first_page;
-  psiconv_paragraph_layout base_paragraph_layout;
-  psiconv_character_layout base_character_layout;
-  psiconv_texted_section text; 
+  psiconv_bool_t on_first_page;                   /* Display on first page? */
+  psiconv_paragraph_layout base_paragraph_layout; /* Base paragraph layout */
+  psiconv_character_layout base_character_layout; /* Base character layout */
+  psiconv_texted_section text;                    /* The actual text */
 } *psiconv_page_header;
 
+/* A Page Layout Section
+   All information about the layout of a page.
+   Margins, page size, the header, the footer and page numbers */
 typedef struct psiconv_page_layout_section_s
 {
-  psiconv_u32 first_page_nr;
-  psiconv_length_t header_dist;
-  psiconv_length_t footer_dist;
-  psiconv_length_t left_margin;
-  psiconv_length_t right_margin;
-  psiconv_length_t top_margin;
-  psiconv_length_t bottom_margin;
-  psiconv_length_t page_width;
-  psiconv_length_t page_height;
-  psiconv_page_header header;
-  psiconv_page_header footer;
-  psiconv_bool_t landscape;
+  psiconv_u32 first_page_nr;         /* Page numbers start counting here */
+  psiconv_length_t header_dist;      /* Distance of header to text */
+  psiconv_length_t footer_dist;      /* Distance of footer to text */
+  psiconv_length_t left_margin;      /* Left margin */
+  psiconv_length_t right_margin;     /* Right margin */
+  psiconv_length_t top_margin;       /* Top margin */
+  psiconv_length_t bottom_margin;    /* Bottom margin */
+  psiconv_length_t page_width;       /* Page width */
+  psiconv_length_t page_height;      /* Page height */
+  psiconv_page_header header;        /* Header information */
+  psiconv_page_header footer;        /* Footer information */
+  psiconv_bool_t landscape;          /* Landscape orientation? */
 } * psiconv_page_layout_section;
 
+/* A Word Status Section
+   Settings of the Word program. 
+   Several whitespace and related characters can be explicitely shown.
+   Embedded pictures and graphs can be iconized or displayed full.
+   Toolbars can be shown or hidden.
+   Long lines can be wrapped, or you have to use scrolling.
+   The cursor position is the character number of the text.
+   Zoom level: 1000 is "normal" */
 typedef struct psiconv_word_status_section_s
 {
-  psiconv_bool_t show_tabs;
-  psiconv_bool_t show_spaces;
-  psiconv_bool_t show_paragraph_ends;
-  psiconv_bool_t show_line_breaks;
-  psiconv_bool_t show_hard_minus;
-  psiconv_bool_t show_hard_space;
-  psiconv_bool_t show_full_pictures;
-  psiconv_bool_t show_full_graphs;
-  psiconv_bool_t show_top_toolbar;
-  psiconv_bool_t show_side_toolbar;
-  psiconv_bool_t fit_lines_to_screen;
-  psiconv_u32 cursor_position;
-  psiconv_u32 display_size;
+  psiconv_bool_t show_tabs;           /* Show tabs? */
+  psiconv_bool_t show_spaces;         /* Show spaces? */
+  psiconv_bool_t show_paragraph_ends; /* Show paragraph ends? */
+  psiconv_bool_t show_line_breaks;    /* Show line breaks */
+  psiconv_bool_t show_hard_minus;     /* Show hard dashes? */
+  psiconv_bool_t show_hard_space;     /* Show hard spaces? */
+  psiconv_bool_t show_full_pictures;  /* Show embedded pictures (or iconize)? */
+  psiconv_bool_t show_full_graphs;    /* Show embedded graphs (or iconize)? */
+  psiconv_bool_t show_top_toolbar;    /* Show top toolbar? */
+  psiconv_bool_t show_side_toolbar;   /* Show side toolbar? */
+  psiconv_bool_t fit_lines_to_screen; /* Wrap lines? */
+  psiconv_u32 cursor_position;        /* Cursor position (character number) */
+  psiconv_u32 display_size;           /* Zooming level */
 } *psiconv_word_status_section;
 
+/* A Word Style.
+   All information about a single Style.
+   A builtin style may not be changed in the Word program.
+   Outline level is zero if unused. */
 typedef struct psiconv_word_style_s
 {
-  psiconv_character_layout character;
-  psiconv_paragraph_layout paragraph;
-  psiconv_u8 hotkey;
-  psiconv_string_t name;
-  psiconv_bool_t built_in;
-  psiconv_u32 outline_level;
+  psiconv_character_layout character; /* character-level layout */
+  psiconv_paragraph_layout paragraph; /* paragraph-level layout */
+  psiconv_ucs2 hotkey;                /* The hotkey */
+  psiconv_string_t name;              /* Style name */
+  psiconv_bool_t built_in;            /* Builtin style? */
+  psiconv_u32 outline_level;          /* Outline level */
 } *psiconv_word_style;
 
-typedef psiconv_list psiconv_word_style_list; /* Of style */
+/* A list of Word Styles */
+typedef psiconv_list psiconv_word_style_list; 
+                                         /* Of struct psiconv_word_style_s */
 
+/* A Word Styles Section
+   All information about styles. */
 typedef struct psiconv_word_styles_section_s
 {
-  psiconv_word_style normal;
-  psiconv_word_style_list styles;
+  psiconv_word_style normal;      /* The normal (unspecified) style */
+  psiconv_word_style_list styles; /* All other defined styles */
 } *psiconv_word_styles_section;
 
+/* A Word File
+   All information about a Word File.
+   Note that a section can be NULL if it is not present. */
 typedef struct psiconv_word_f_s
 {
-  psiconv_page_layout_section page_sec;
-  psiconv_text_and_layout paragraphs;
-  psiconv_word_status_section status_sec;
-  psiconv_word_styles_section styles_sec;
+  psiconv_page_layout_section page_sec;    /* Page layout */
+  psiconv_text_and_layout paragraphs;      /* Text and text layout */
+  psiconv_word_status_section status_sec;  /* Internal Word program settings */
+  psiconv_word_styles_section styles_sec;  /* Styles */
 } *psiconv_word_f;
 
+/* A TextEd File
+   All information about a TextEd File.
+   Note that a section can be NULL if it is not present. */
 typedef struct psiconv_texted_f_s
 {
-  psiconv_page_layout_section page_sec;
-  psiconv_texted_section texted_sec;
+  psiconv_page_layout_section page_sec;    /* Page layout */
+  psiconv_texted_section texted_sec;       /* Text and text layout */
 } *psiconv_texted_f;
 
+/* A Jumptable Section.
+   A simple list of offsets.
+   This is never included in a regular psiconv_file structure, as the 
+   information is too low-level. It is used internally, though. */
 typedef psiconv_list psiconv_jumptable_section; /* of psiconv_u32 */
 
-/* Normalized values [0..1] for each component 
+/* A Paint Data Section
+   A collection of pixels.
+   Normalized values [0..1] for each color component.
    Origin is (x,y)=(0,0), to get pixel at (X,Y) use index [Y*xsize+X] */
 typedef struct psiconv_paint_data_section_s
 {
-  psiconv_u32 xsize;
-  psiconv_u32 ysize;
+  psiconv_u32 xsize;          /* Number of pixels in a row */
+  psiconv_u32 ysize;          /* Number of pixels in a column */
   psiconv_length_t pic_xsize; /* 0 if not specified */
   psiconv_length_t pic_ysize; /* 0 if not specified */
-  float *red;
+  float *red;                 
   float *green;
   float *blue;
 } *psiconv_paint_data_section;
 
+/* A collection of Paint Data Sections */
 typedef psiconv_list psiconv_pictures; 
-            /* of struct psiconv_paint_data_section */
+            /* of struct psiconv_paint_data_section_s */
 
+/* A MBM file 
+   All information about a MBM file
+   MBM files contain one or more pictures. */
 typedef struct psiconv_mbm_f_s 
 {
   psiconv_pictures sections;
@@ -430,7 +588,7 @@
   psiconv_paint_data_section picture;
 } * psiconv_clipart_section;
 
-typedef psiconv_list psiconv_cliparts; /* of struct psiconv_clipart_section */
+typedef psiconv_list psiconv_cliparts; /* of struct psiconv_clipart_section_s */
 
 typedef struct psiconv_clipart_f_s 
 {
@@ -542,7 +700,8 @@
   psiconv_u32 ref_formula;
 } *psiconv_sheet_cell;
 
-typedef psiconv_list psiconv_sheet_cell_list;
+typedef psiconv_list psiconv_sheet_cell_list; 
+                                         /* Of struct psiconv_sheet_cell_s */
 
 typedef struct psiconv_sheet_status_section_s
 {