From b005175003c4d855e048e5af97a6b20cd8edb5eb Mon Sep 17 00:00:00 2001 From: Michael R Sweet Date: Mon, 7 Jun 2021 17:06:13 -0400 Subject: [PATCH] Doco updates. --- README.md | 2 +- doc/pdfio.3 | 111 ++++++++++++++++++++++++++++++++++++++------- doc/pdfio.html | 84 +++++++++++++++++++++++++++------- doc/pdfio.md | 119 +++++++++++++++++++++++++++++++++++++++++++++---- pdfio-string.c | 4 +- pdfio.h | 2 - 6 files changed, 276 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index dad54fb..46ccbc6 100644 --- a/README.md +++ b/README.md @@ -105,7 +105,7 @@ Visual Studio Project > Note: I haven't yet added this... -The Visual Studio solution ("pdfio.sln") is provided for Windows developers +The Visual Studio solution ("pdfio.sln") is provided for Windows developers and generates both a static library and DLL. diff --git a/doc/pdfio.3 b/doc/pdfio.3 index 237898b..9299744 100644 --- a/doc/pdfio.3 +++ b/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 .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 @@ -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 diff --git a/doc/pdfio.html b/doc/pdfio.html index 9724306..ff8778f 100644 --- a/doc/pdfio.html +++ b/doc/pdfio.html @@ -261,10 +261,11 @@ span.string {
  • Header Files
  • API Overview
  • Functions
  • Data Types

    Visual Studio Project

    -
    -

    Note: I haven't yet added this...

    -
    -

    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.

    Xcode Project

    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:

    sudo xcodebuild install
@@ -530,11 +527,12 @@ fi
 
    CFLAGS  +=      `pkg-config --cflags pdfio`
 LIBS    +=      `pkg-config --libs pdfio`
 
    
+
    On Windows, you need to link to the PDFIO.LIB (static) or PDFIO1.LIB (DLL) libraries and include the "zlib" NuGet package dependency.
    
 
    Header Files
    
 
    PDFio provides a primary header file that is always used:
    
 
    #include <pdfio.h>
 
    
-
    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:
    
 
    #include <pdfio-content.h>
 
    
 
    API Overview
    
@@ -551,10 +549,67 @@ LIBS    +=      `pkg-config --libs pdfio`
 
  • pdfio_stream_t: An object stream
    
 
    • 
 
-
    PDF Files
    
-
    PDF Values
    
+
    Reading PDF Files
    
+
    You open an existing PDF file using the pdfioFileOpen function:
    
+
    pdfio_file_t *pdf = pdfioFileOpen("myinputfile.pdf", error_cb, error_data);
+
    
+
    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:
    
+
    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);
+}
+
    
+
    The default error callback (NULL) does the equivalent of the above.
    
+
    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:
    
+
    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
+}
+
    
+
    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.
    
+
    The pdfioFileClose function closes a PDF file and frees all memory that was used for it:
    
+
    pdfioFileClose(pdf);
+
    
+
    Writing PDF Files
    
+
    You create a new PDF file using the pdfioFileCreate function:
    
+
    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);
+
    
+
    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).
    
+
    Once the file is created, use the pdfioFileCreateObj, pdfioFileCreatePage, and pdfioPageCopy functions to create objects and pages in the file.
    
+
    Finally, the pdfioFileClose function writes the PDF cross-reference and "trailer" information, closes the file, and frees all memory that was used for it.
    
 
    PDF Objects
    
+
    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.
    
+
    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:
    
+
      
+
    • pdfioObjGetArray returns an object's array value, if any
      
+
      • 
+
    • pdfioObjGetDict returns an object's dictionary value, if any
      
+
      • 
+
    • pdfioObjGetLength returns the length of the data stream, if any
      
+
      • 
+
    • pdfioObjGetSubtype returns the sub-type name of the object, for example "Image" for an image object.
      
+
      • 
+
    • pdfioObjGetType returns the type name of the object, for example "XObject" for an image object.
      
+
      • 
+
    
 
    PDF Streams
    
+
    PDF Content Helper Functions
    
 
    Functions
    
 
    pdfioArrayAppendArray
    
 
    Add an array value to an array.
    
@@ -2597,7 +2652,7 @@ char *pdfioStringCreate(pdfio_file_t *pdf, const cha
 
    Durable string pointer or NULL on error
    
 
    Discussion
    
 
    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.
    
 
    
 NULL is returned on error, otherwise a char * that is valid until
 pdfioFileClose is called.
    
@@ -2618,16 +2673,11 @@ char *pdfioStringCreatef(pdfio_file_t *pdf, const ch
 
    Durable string pointer or NULL on error
    
 
    Discussion
    
 
    This function creates a formatted string associated with the PDF file
-"pwg".  The "format" string contains printf-style format characters.
    
+"pdf".  The "format" string contains printf-style format characters.
    
 
    
 NULL is returned on error, otherwise a char * that is valid until
 pdfioFileClose is called.
    
 
    Data Types
    
-
    pdf_value_t
    
-
    PDF value of any type
    
-
    
-typedef struct _pdfio_value_s pdf_value_t;
-
    
 
    pdfio_array_t
    
 
    Array of PDF values
    
 
    
diff --git a/doc/pdfio.md b/doc/pdfio.md
index 6e9c54f..04cb422 100644
--- a/doc/pdfio.md
+++ b/doc/pdfio.md
@@ -89,9 +89,7 @@ command or as environment variables:
 Visual Studio Project
 ---------------------
 
-> Note: I haven't yet added this...
-
-The Visual Studio solution ("pdfio.sln") is provided for Windows developers
+The Visual Studio solution ("pdfio.sln") is provided for Windows developers and
 generates both a static library and DLL.
 
 
@@ -124,6 +122,9 @@ CFLAGS  +=      `pkg-config --cflags pdfio`
 LIBS    +=      `pkg-config --libs pdfio`
 ```
 
+On Windows, you need to link to the `PDFIO.LIB` (static) or `PDFIO1.LIB` (DLL)
+libraries and include the "zlib" NuGet package dependency.
+
 
 Header Files
 ------------
@@ -134,8 +135,8 @@ PDFio provides a primary header file that is always used:
 #include 
 ```
 
-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:
 
 ```c
 #include 
@@ -154,17 +155,117 @@ PDFio exposes several types:
 - `pdfio_stream_t`: An object stream
 
 
-PDF Files
----------
+Reading PDF Files
+-----------------
 
+You open an existing PDF file using the `pdfioFileOpen` function:
 
-PDF Values
-----------
+```c
+pdfio_file_t *pdf = pdfioFileOpen("myinputfile.pdf", error_cb, error_data);
+
+```
+
+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:
+
+```c
+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);
+}
+```
+
+The default error callback (`NULL`) does the equivalent of the above.
+
+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:
+
+```c
+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
+}
+```
+
+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.
+
+The `pdfioFileClose` function closes a PDF file and frees all memory that was
+used for it:
+
+```c
+pdfioFileClose(pdf);
+```
+
+Writing PDF Files
+-----------------
+
+You create a new PDF file using the `pdfioFileCreate` function:
+
+```c
+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);
+```
+
+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`).
+
+Once the file is created, use the `pdfioFileCreateObj`, `pdfioFileCreatePage`,
+and `pdfioPageCopy` functions to create objects and pages in the file.
+
+Finally, the `pdfioFileClose` function writes the PDF cross-reference and
+"trailer" information, closes the file, and frees all memory that was used for
+it.
 
 
 PDF Objects
 -----------
 
+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.
+
+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:
+
+- `pdfioObjGetArray` returns an object's array value, if any
+- `pdfioObjGetDict` returns an object's dictionary value, if any
+- `pdfioObjGetLength` returns the length of the data stream, if any
+- `pdfioObjGetSubtype` returns the sub-type name of the object, for example
+  "Image" for an image object.
+- `pdfioObjGetType` returns the type name of the object, for example "XObject"
+  for an image object.
+
 
 PDF Streams
 -----------
+
+
+PDF Content Helper Functions
+----------------------------
+
diff --git a/pdfio-string.c b/pdfio-string.c
index 68c175c..05d210c 100644
--- a/pdfio-string.c
+++ b/pdfio-string.c
@@ -25,7 +25,7 @@ static int	compare_strings(char **a, char **b);
 // 'pdfioStringCreate()' - Create a durable literal string.
 //
 // 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.
 //
 // `NULL` is returned on error, otherwise a `char *` that is valid until
 // `pdfioFileClose` is called.
@@ -85,7 +85,7 @@ pdfioStringCreate(
 // 'pdfioStringCreatef()' - Create a durable formatted string.
 //
 // This function creates a formatted string associated with the PDF file
-// "pwg".  The "format" string contains `printf`-style format characters.
+// "pdf".  The "format" string contains `printf`-style format characters.
 //
 // `NULL` is returned on error, otherwise a `char *` that is valid until
 // `pdfioFileClose` is called.
diff --git a/pdfio.h b/pdfio.h
index 6f1dc44..4798961 100644
--- a/pdfio.h
+++ b/pdfio.h
@@ -93,8 +93,6 @@ typedef enum pdfio_valtype_e		// PDF value types
   PDFIO_VALTYPE_NUMBER,			// Number (integer or real)
   PDFIO_VALTYPE_STRING			// String
 } pdfio_valtype_t;
-typedef struct _pdfio_value_s pdf_value_t;
-					// PDF value of any type
 
 
 //