Doco updates.

doc/pdfio.3

@@ -140,10 +140,7 @@ prefix: specifies the installation directory (default "/usr/local")
 
 .SS Visual Studio Project
 .PP
-Note: I haven't yet added this...
-
-.PP
-The Visual Studio solution ("pdfio.sln") is provided for Windows developers generates both a static library and DLL.
+The Visual Studio solution ("pdfio.sln") is provided for Windows developers and generates both a static library and DLL.
 .SS Xcode Project
 .PP
 There is also an Xcode project ("pdfio.xcodeproj") you can use on macOS which generates a static library that will be installed under "/usr/local" with:
@@ -173,6 +170,8 @@ In a makefile you can add the necessary compiler and linker options with:
     CFLAGS  +=      `pkg\-config \-\-cflags pdfio`
     LIBS    +=      `pkg\-config \-\-libs pdfio`
 .fi
+.PP
+On Windows, you need to link to the PDFIO.LIB (static) or PDFIO1.LIB (DLL) libraries and include the "zlib" NuGet package dependency.
 .SS Header Files
 .PP
 PDFio provides a primary header file that is always used:
@@ -181,7 +180,7 @@ PDFio provides a primary header file that is always used:
     #include <pdfio.h>
 .fi
 .PP
-PDFio also provides content helper functions that are defined in a separate header file:
+PDFio also provides helper functions for producing PDF content that are defined in a separate header file:
 .nf
 
     #include <pdfio\-content.h>
@@ -210,10 +209,98 @@ pdfio_obj_t: An object in a PDF file
 pdfio_stream_t: An object stream
 
 
-.SS PDF Files
-.SS PDF Values
+.SS Reading PDF Files
+.PP
+You open an existing PDF file using the pdfioFileOpen function:
+.nf
+
+    pdfio_file_t *pdf = pdfioFileOpen("myinputfile.pdf", error_cb, error_data);
+.fi
+.PP
+where the three arguments to the function are the filename ("myinputfile.pdf"), an optional error callback function (error_cb), and an optional pointer value for the error callback function (error_data). The error callback is called for both errors and warnings and accepts the pdfio_file_t pointer, a message string, and the callback pointer value, for example:
+.nf
+
+    bool
+    error_cb(pdfio_file_t *pdf, const char *message, void *data)
+    {
+      (void)data; // This callback does not use the data pointer
+    
+      fprintf(stderr, "%s: %s\\n", pdfioFileGetName(pdf), message);
+    
+      // Return false to treat warnings as errors
+      return (false);
+    }
+.fi
+.PP
+The default error callback (NULL) does the equivalent of the above.
+.PP
+Each PDF file contains one or more pages. The pdfioFileGetNumPages function returns the number of pages in the file while the pdfioFileGetPage function gets the specified page in the PDF file:
+.nf
+
+    pdfio_file_t *pdf;   // PDF file
+    size_t       i;      // Looping var
+    size_t       count;  // Number of pages
+    pdfio_obj_t  *page;  // Current page
+    
+    // Iterate the pages in the PDF file
+    for (i = 0, count = pdfioFileGetNumPages(pdf); i < count; i ++)
+    {
+      page = pdfioFileGetPage(pdf, i);
+      // do something with page
+    }
+.fi
+.PP
+Each page is represented by a "page tree" object (what pdfioFileGetPage returns) that specifies information about the page and one or more "content" objects that contain the images, fonts, text, and graphics that appear on the page.
+.PP
+The pdfioFileClose function closes a PDF file and frees all memory that was used for it:
+.nf
+
+    pdfioFileClose(pdf);
+.fi
+.SS Writing PDF Files
+.PP
+You create a new PDF file using the pdfioFileCreate function:
+.nf
+
+    pdfio_rect_t media_box = { 0.0, 0.0, 612.0, 792.0 };  // US Letter
+    pdfio_rect_t crop_box = { 36.0, 36.0, 576.0, 756.0 }; // 0.5" margins
+    
+    pdfio_file_t *pdf = pdfioFileCreate("myoutputfile.pdf", "2.0", &media_box, &crop_box, error_cb, error_data);
+.fi
+.PP
+where the six arguments to the function are the filename ("myoutputfile.pdf"), PDF version ("2.0"), media box (media_box), crop box (crop_box), an optional error callback function (error_cb), and an optional pointer value for the error callback function (error_data).
+.PP
+Once the file is created, use the pdfioFileCreateObj, pdfioFileCreatePage, and pdfioPageCopy functions to create objects and pages in the file.
+.PP
+Finally, the pdfioFileClose function writes the PDF cross\-reference and "trailer" information, closes the file, and frees all memory that was used for it.
 .SS PDF Objects
+.PP
+PDF objects are identified using two numbers \- the object number (1 to N) and the object generation (0 to 65535) that specifies a particular version of an object. An object's numbers are returned by the pdfioObjGetNumber and pdfioObjGetGeneration functions. You can find a numbered object using the pdfioFileFindObj function.
+.PP
+Objects contain values (typically dictionaries) and usually an associated data stream containing images, fonts, ICC profiles, and page content. PDFio provides several accessor functions to get the value(s) associated with an object:
+.IP \(bu 5
+.PP
+pdfioObjGetArray returns an object's array value, if any
+
+.IP \(bu 5
+.PP
+pdfioObjGetDict returns an object's dictionary value, if any
+
+.IP \(bu 5
+.PP
+pdfioObjGetLength returns the length of the data stream, if any
+
+.IP \(bu 5
+.PP
+pdfioObjGetSubtype returns the sub\-type name of the object, for example "Image" for an image object.
+
+.IP \(bu 5
+.PP
+pdfioObjGetType returns the type name of the object, for example "XObject" for an image object.
+
+
 .SS PDF Streams
+.SS PDF Content Helper Functions
 
 .SH ENUMERATIONS
 .SS pdfio_filter_e
@@ -1718,7 +1805,7 @@ char * pdfioStringCreate (
 .fi
 .PP
 This function creates a literal string associated with the PDF file
-"pwg".  The "s" string points to a nul-terminated C string.
+"pdf".  The "s" string points to a nul-terminated C string.
 .PP
 \fBNULL\fR is returned on error, otherwise a \fBchar *\fR that is valid until
 \fBpdfioFileClose\fR is called.
@@ -1734,7 +1821,7 @@ char * pdfioStringCreatef (
 .fi
 .PP
 This function creates a formatted string associated with the PDF file
-"pwg".  The "format" string contains \fBprintf\fR-style format characters.
+"pdf".  The "format" string contains \fBprintf\fR-style format characters.
 .PP
 \fBNULL\fR is returned on error, otherwise a \fBchar *\fR that is valid until
 \fBpdfioFileClose\fR is called.
@@ -1752,12 +1839,6 @@ struct pdfio_rect_s
 };
 .fi
 .SH TYPES
-.SS pdf_value_t
-PDF value of any type
-.PP
-.nf
-typedef struct _pdfio_value_s pdf_value_t;
-.fi
 .SS pdfio_array_t
 Array of PDF values
 .PP