Update docos.

This commit is contained in:
Michael R Sweet 2021-09-27 08:11:53 -04:00
parent 7473bc3cd9
commit ba9d03ecac
No known key found for this signature in database
GPG Key ID: BE67C75EC81F3244
5 changed files with 233 additions and 10 deletions

View File

@ -102,8 +102,8 @@ Visual Studio Project
---------------------
The Visual Studio solution ("pdfio.sln") is provided for Windows developers and
generates both a static library and DLL. You can also use NuGet to install the
`pdfio_native` package.
generates the PDFIO1 DLL. You can also use NuGet to install the `pdfio_native`
package.
Xcode Project

View File

@ -1,4 +1,4 @@
.TH pdfio 3 "pdf read/write library" "2021-08-30" "pdf read/write library"
.TH pdfio 3 "pdf read/write library" "2021-09-27" "pdf read/write library"
.SH NAME
pdfio \- pdf read/write library
.SH Introduction
@ -171,7 +171,7 @@ In a makefile you can add the necessary compiler and linker options with:
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.
On Windows, you need to link to the PDFIO1.LIB (DLL) library and include the zlib_native NuGet package dependency. You can also use the published pdfio_native NuGet package.
.SS Header Files
.PP
PDFio provides a primary header file that is always used:
@ -270,6 +270,15 @@ You create a new PDF file using the pdfioFileCreate function:
.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). The units for the media and crop boxes are points (1/72nd of an inch).
.PP
Alternately you can stream a PDF file using the pdfioFileCreateOutput 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 }; // w/0.5" margins
pdfio_file_t *pdf = pdfioFileCreateOutput(output_cb, output_ctx, "2.0", &media_box, &crop_box, error_cb, error_data);
.fi
.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.
@ -1995,6 +2004,20 @@ pdfio_file_t * pdfioFileCreate (
void *error_data
);
.fi
.PP
This function creates a new PDF file. The "filename" argument specifies the
name of the PDF file to create.
.PP
The "version" argument specifies the PDF version number for the file or
\fBNULL\fR for the default ("2.0").
.PP
The "media_box" and "crop_box" arguments specify the default MediaBox and
CropBox for pages in the PDF file - if \fBNULL\fR then a default "Universal" size
of 8.27x11in (the intersection of US Letter and ISO A4) is used.
.PP
The "error_cb" and "error_data" arguments specify an error handler callback
and its data pointer - if not specified the default error handler is used
that writes error messages to \fBstderr\fR.
.SS pdfioFileCreateArrayObj
Create a new object in a PDF file containing an array.
.PP
@ -2137,6 +2160,51 @@ pdfio_obj_t * pdfioFileCreateObj (
pdfio_dict_t *dict
);
.fi
.SS pdfioFileCreateOutput
Create a PDF file through an output callback.
.PP
.nf
pdfio_file_t * pdfioFileCreateOutput (
pdfio_output_cb_t output_cb,
void *output_ctx,
const char *version,
pdfio_rect_t *media_box,
pdfio_rect_t *crop_box,
pdfio_error_cb_t error_cb,
void *error_data
);
.fi
.PP
This function creates a new PDF file that is streamed though an output
callback. The "output_cb" and "output_ctx" arguments specify the output
callback and its context pointer which is called whenever data needs to be
written:
.PP
.nf
ssize_t
output_cb(void *output_ctx, const void *buffer, size_t bytes)
{
// Write buffer to output and return the number of bytes written
}
.fi
The "version" argument specifies the PDF version number for the file or
\fBNULL\fR for the default ("2.0").
.PP
The "media_box" and "crop_box" arguments specify the default MediaBox and
CropBox for pages in the PDF file - if \fBNULL\fR then a default "Universal" size
of 8.27x11in (the intersection of US Letter and ISO A4) is used.
.PP
The "error_cb" and "error_data" arguments specify an error handler callback
and its data pointer - if not specified the default error handler is used
that writes error messages to \fBstderr\fR.
.PP
.IP 5
\fINote\fR: Files created using this API are slightly larger than those
.IP 5
created using the \fIpdfioFileCreate\fR function since stream lengths are
.IP 5
stored as indirect object references.
.SS pdfioFileCreatePage
Create a page in a PDF file.
.PP
@ -2282,6 +2350,12 @@ pdfio_file_t * pdfioFileOpen (
void *error_data
);
.fi
.PP
This function opens an existing PDF file. The "filename" argument specifies
the name of the PDF file to create. The "error_cb" and "error_data"
arguments specify an error handler callback and its data pointer - if not
specified the default error handler is used that writes error messages to
\fBstderr\fR.
.SS pdfioFileSetAuthor
Set the author for a PDF file.
.PP
@ -2698,6 +2772,12 @@ Numbered object in PDF file
.nf
typedef struct _pdfio_obj_s pdfio_obj_t;
.fi
.SS pdfio_output_cb_t
Output callback for pdfioFileCreateOutput
.PP
.nf
typedef ssize_t(*)(void *ctx const void *data size_t datalen) pdfio_output_cb_t;
.fi
.SS pdfio_rect_t
PDF rectangle
.PP

View File

@ -1,13 +1,13 @@
<!DOCTYPE html>
<html lang="en-US">
<head>
<title>PDFio Programming Manual v1.0b1</title>
<title>PDFio Programming Manual v1.0.0</title>
<meta http-equiv="Content-Type" content="text/html;charset=utf-8">
<meta name="generator" content="codedoc v3.7">
<meta name="author" content="Michael R Sweet">
<meta name="language" content="en-US">
<meta name="copyright" content="Copyright © 2021 by Michael R Sweet">
<meta name="version" content="1.0b1">
<meta name="version" content="1.0.0">
<style type="text/css"><!--
body {
background: white;
@ -245,7 +245,7 @@ span.string {
<body>
<div class="header">
<p><img class="title" src="pdfio-512.png"></p>
<h1 class="title">PDFio Programming Manual v1.0b1</h1>
<h1 class="title">PDFio Programming Manual v1.0.0</h1>
<p>Michael R Sweet</p>
<p>Copyright © 2021 by Michael R Sweet</p>
</div>
@ -381,6 +381,7 @@ span.string {
<li><a href="#pdfioFileCreateImageObjFromData">pdfioFileCreateImageObjFromData</a></li>
<li><a href="#pdfioFileCreateImageObjFromFile">pdfioFileCreateImageObjFromFile</a></li>
<li><a href="#pdfioFileCreateObj">pdfioFileCreateObj</a></li>
<li><a href="#pdfioFileCreateOutput">pdfioFileCreateOutput</a></li>
<li><a href="#pdfioFileCreatePage">pdfioFileCreatePage</a></li>
<li><a href="#pdfioFileFindObj">pdfioFileFindObj</a></li>
<li><a href="#pdfioFileGetAuthor">pdfioFileGetAuthor</a></li>
@ -445,6 +446,7 @@ span.string {
<li><a href="#pdfio_linejoin_t">pdfio_linejoin_t</a></li>
<li><a href="#pdfio_matrix_t[3][2]">pdfio_matrix_t[3][2]</a></li>
<li><a href="#pdfio_obj_t">pdfio_obj_t</a></li>
<li><a href="#pdfio_output_cb_t">pdfio_output_cb_t</a></li>
<li><a href="#pdfio_rect_t">pdfio_rect_t</a></li>
<li><a href="#pdfio_stream_t">pdfio_stream_t</a></li>
<li><a href="#pdfio_textrendering_t">pdfio_textrendering_t</a></li>
@ -557,7 +559,7 @@ fi
<pre><code class="language-make">CFLAGS += `pkg-config --cflags pdfio`
LIBS += `pkg-config --libs pdfio`
</code></pre>
<p>On Windows, you need to link to the <code>PDFIO.LIB</code> (static) or <code>PDFIO1.LIB</code> (DLL) libraries and include the &quot;zlib&quot; NuGet package dependency.</p>
<p>On Windows, you need to link to the <code>PDFIO1.LIB</code> (DLL) library and include the <code>zlib_native</code> NuGet package dependency. You can also use the published <code>pdfio_native</code> NuGet package.</p>
<h3 class="title" id="header-files">Header Files</h3>
<p>PDFio provides a primary header file that is always used:</p>
<pre><code class="language-c"><span class="directive">#include &lt;pdfio.h&gt;</span>
@ -621,6 +623,12 @@ pdfio_rect_t crop_box = { <span class="number">36.0</span>, <span class="number"
pdfio_file_t *pdf = pdfioFileCreate(<span class="string">&quot;myoutputfile.pdf&quot;</span>, <span class="string">&quot;2.0&quot;</span>, &amp;media_box, &amp;crop_box, error_cb, error_data);
</code></pre>
<p>where the six arguments to the function are the filename (&quot;myoutputfile.pdf&quot;), PDF version (&quot;2.0&quot;), media box (<code>media_box</code>), crop box (<code>crop_box</code>), an optional error callback function (<code>error_cb</code>), and an optional pointer value for the error callback function (<code>error_data</code>). The units for the media and crop boxes are points (1/72nd of an inch).</p>
<p>Alternately you can stream a PDF file using the <a href="#pdfioFileCreateOutput"><code>pdfioFileCreateOutput</code></a> function:</p>
<pre><code class="language-c">pdfio_rect_t media_box = { <span class="number">0.0</span>, <span class="number">0.0</span>, <span class="number">612.0</span>, <span class="number">792.0</span> }; <span class="comment">// US Letter</span>
pdfio_rect_t crop_box = { <span class="number">36.0</span>, <span class="number">36.0</span>, <span class="number">576.0</span>, <span class="number">756.0</span> }; <span class="comment">// w/0.5&quot; margins</span>
pdfio_file_t *pdf = pdfioFileCreateOutput(output_cb, output_ctx, <span class="string">&quot;2.0&quot;</span>, &amp;media_box, &amp;crop_box, error_cb, error_data);
</code></pre>
<p>Once the file is created, use the <a href="#pdfioFileCreateObj"><code>pdfioFileCreateObj</code></a>, <a href="#pdfioFileCreatePage"><code>pdfioFileCreatePage</code></a>, and <a href="#pdfioPageCopy"><code>pdfioPageCopy</code></a> functions to create objects and pages in the file.</p>
<p>Finally, the <a href="#pdfioFileClose"><code>pdfioFileClose</code></a> function writes the PDF cross-reference and &quot;trailer&quot; information, closes the file, and frees all memory that was used for it.</p>
<h3 class="title" id="pdf-objects">PDF Objects</h3>
@ -2444,6 +2452,20 @@ bool pdfioFileClose(<a href="#pdfio_file_t">pdfio_file_t</a> *pdf);</p>
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
<p class="description">PDF file or <code>NULL</code> on error</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">This function creates a new PDF file. The &quot;filename&quot; argument specifies the
name of the PDF file to create.<br>
<br>
The &quot;version&quot; argument specifies the PDF version number for the file or
<code>NULL</code> for the default (&quot;2.0&quot;).<br>
<br>
The &quot;media_box&quot; and &quot;crop_box&quot; arguments specify the default MediaBox and
CropBox for pages in the PDF file - if <code>NULL</code> then a default &quot;Universal&quot; size
of 8.27x11in (the intersection of US Letter and ISO A4) is used.<br>
<br>
The &quot;error_cb&quot; and &quot;error_data&quot; arguments specify an error handler callback
and its data pointer - if not specified the default error handler is used
that writes error messages to <code>stderr</code>.</p>
<h3 class="function"><a id="pdfioFileCreateArrayObj">pdfioFileCreateArrayObj</a></h3>
<p class="description">Create a new object in a PDF file containing an array.</p>
<p class="code">
@ -2621,6 +2643,57 @@ is supported.</blockquote>
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
<p class="description">New object</p>
<h3 class="function"><a id="pdfioFileCreateOutput">pdfioFileCreateOutput</a></h3>
<p class="description">Create a PDF file through an output callback.</p>
<p class="code">
<a href="#pdfio_file_t">pdfio_file_t</a> *pdfioFileCreateOutput(<a href="#pdfio_output_cb_t">pdfio_output_cb_t</a> output_cb, void *output_ctx, const char *version, <a href="#pdfio_rect_t">pdfio_rect_t</a> *media_box, <a href="#pdfio_rect_t">pdfio_rect_t</a> *crop_box, <a href="#pdfio_error_cb_t">pdfio_error_cb_t</a> error_cb, void *error_data);</p>
<h4 class="parameters">Parameters</h4>
<table class="list"><tbody>
<tr><th>output_cb</th>
<td class="description">Output callback</td></tr>
<tr><th>output_ctx</th>
<td class="description">Output context</td></tr>
<tr><th>version</th>
<td class="description">PDF version number or <code>NULL</code> for default (2.0)</td></tr>
<tr><th>media_box</th>
<td class="description">Default MediaBox for pages</td></tr>
<tr><th>crop_box</th>
<td class="description">Default CropBox for pages</td></tr>
<tr><th>error_cb</th>
<td class="description">Error callback or <code>NULL</code> for default</td></tr>
<tr><th>error_data</th>
<td class="description">Error callback data, if any</td></tr>
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
<p class="description">PDF file or <code>NULL</code> on error</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">This function creates a new PDF file that is streamed though an output
callback. The &quot;output_cb&quot; and &quot;output_ctx&quot; arguments specify the output
callback and its context pointer which is called whenever data needs to be
written:
<pre>
ssize_t
output_cb(void *output_ctx, const void *buffer, size_t bytes)
{
// Write buffer to output and return the number of bytes written
}
</pre>
The &quot;version&quot; argument specifies the PDF version number for the file or
<code>NULL</code> for the default (&quot;2.0&quot;).<br>
<br>
The &quot;media_box&quot; and &quot;crop_box&quot; arguments specify the default MediaBox and
CropBox for pages in the PDF file - if <code>NULL</code> then a default &quot;Universal&quot; size
of 8.27x11in (the intersection of US Letter and ISO A4) is used.<br>
<br>
The &quot;error_cb&quot; and &quot;error_data&quot; arguments specify an error handler callback
and its data pointer - if not specified the default error handler is used
that writes error messages to <code>stderr</code>.<br>
<br>
</p><blockquote>
<em>Note</em>: Files created using this API are slightly larger than those
created using the <a href="#pdfioFileCreate"><code>pdfioFileCreate</code></a> function since stream lengths are
stored as indirect object references.</blockquote>
<h3 class="function"><a id="pdfioFileCreatePage">pdfioFileCreatePage</a></h3>
<p class="description">Create a page in a PDF file.</p>
<p class="code">
@ -2823,6 +2896,12 @@ const char *pdfioFileGetVersion(<a href="#pdfio_file_t">pdfio_file_t</a> *pdf);<
</tbody></table>
<h4 class="returnvalue">Return Value</h4>
<p class="description">PDF file</p>
<h4 class="discussion">Discussion</h4>
<p class="discussion">This function opens an existing PDF file. The &quot;filename&quot; argument specifies
the name of the PDF file to create. The &quot;error_cb&quot; and &quot;error_data&quot;
arguments specify an error handler callback and its data pointer - if not
specified the default error handler is used that writes error messages to
<code>stderr</code>.</p>
<h3 class="function"><a id="pdfioFileSetAuthor">pdfioFileSetAuthor</a></h3>
<p class="description">Set the author for a PDF file.</p>
<p class="code">
@ -3341,6 +3420,11 @@ typedef double pdfio_matrix_t[3][2];
<p class="code">
typedef struct _pdfio_obj_s pdfio_obj_t;
</p>
<h3 class="typedef"><a id="pdfio_output_cb_t">pdfio_output_cb_t</a></h3>
<p class="description">Output callback for pdfioFileCreateOutput</p>
<p class="code">
typedef ssize_t (*pdfio_output_cb_t)(void *ctx const void *data size_t datalen);
</p>
<h3 class="typedef"><a id="pdfio_rect_t">pdfio_rect_t</a></h3>
<p class="description">PDF rectangle</p>
<p class="code">

View File

@ -122,8 +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.
On Windows, you need to link to the `PDFIO1.LIB` (DLL) library and include the
`zlib_native` NuGet package dependency. You can also use the published
`pdfio_native` NuGet package.
Header Files
@ -235,6 +236,16 @@ error callback function (`error_cb`), and an optional pointer value for the
error callback function (`error_data`). The units for the media and crop boxes
are points (1/72nd of an inch).
Alternately you can stream a PDF file using the [`pdfioFileCreateOutput`](@@)
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 }; // w/0.5" margins
pdfio_file_t *pdf = pdfioFileCreateOutput(output_cb, output_ctx, "2.0", &media_box, &crop_box, error_cb, error_data);
```
Once the file is created, use the [`pdfioFileCreateObj`](@@),
[`pdfioFileCreatePage`](@@), and [`pdfioPageCopy`](@@) functions to create
objects and pages in the file.

View File

@ -166,6 +166,20 @@ pdfioFileClose(pdfio_file_t *pdf) // I - PDF file
//
// 'pdfioFileCreate()' - Create a PDF file.
//
// This function creates a new PDF file. The "filename" argument specifies the
// name of the PDF file to create.
//
// The "version" argument specifies the PDF version number for the file or
// `NULL` for the default ("2.0").
//
// The "media_box" and "crop_box" arguments specify the default MediaBox and
// CropBox for pages in the PDF file - if `NULL` then a default "Universal" size
// of 8.27x11in (the intersection of US Letter and ISO A4) is used.
//
// The "error_cb" and "error_data" arguments specify an error handler callback
// and its data pointer - if not specified the default error handler is used
// that writes error messages to `stderr`.
//
pdfio_file_t * // O - PDF file or `NULL` on error
pdfioFileCreate(
@ -402,6 +416,34 @@ _pdfioFileCreateObj(
//
// 'pdfioFileCreateOutput()' - Create a PDF file through an output callback.
//
// This function creates a new PDF file that is streamed though an output
// callback. The "output_cb" and "output_ctx" arguments specify the output
// callback and its context pointer which is called whenever data needs to be
// written:
//
// ```
// ssize_t
// output_cb(void *output_ctx, const void *buffer, size_t bytes)
// {
// // Write buffer to output and return the number of bytes written
// }
// ```
//
// The "version" argument specifies the PDF version number for the file or
// `NULL` for the default ("2.0").
//
// The "media_box" and "crop_box" arguments specify the default MediaBox and
// CropBox for pages in the PDF file - if `NULL` then a default "Universal" size
// of 8.27x11in (the intersection of US Letter and ISO A4) is used.
//
// The "error_cb" and "error_data" arguments specify an error handler callback
// and its data pointer - if not specified the default error handler is used
// that writes error messages to `stderr`.
//
// > *Note*: Files created using this API are slightly larger than those
// > created using the @link pdfioFileCreate@ function since stream lengths are
// > stored as indirect object references.
//
pdfio_file_t * // O - PDF file or `NULL` on error
pdfioFileCreateOutput(
@ -820,6 +862,12 @@ pdfioFileGetVersion(
//
// 'pdfioFileOpen()' - Open a PDF file for reading.
//
// This function opens an existing PDF file. The "filename" argument specifies
// the name of the PDF file to create. The "error_cb" and "error_data"
// arguments specify an error handler callback and its data pointer - if not
// specified the default error handler is used that writes error messages to
// `stderr`.
//
pdfio_file_t * // O - PDF file
pdfioFileOpen(