Finish initial documentation pass. Still need more examples but we'll add more

as we go... (Issue #6)
This commit is contained in:
Michael R Sweet 2021-07-26 09:05:19 -04:00
parent eb7e0676cc
commit c60893a66c
No known key found for this signature in database
GPG Key ID: 999559A027815955
5 changed files with 433 additions and 7 deletions

View File

@ -1,4 +1,4 @@
.TH pdfio 3 "pdf read/write library" "2021-07-24" "pdf read/write library"
.TH pdfio 3 "pdf read/write library" "2021-07-26" "pdf read/write library"
.SH NAME
pdfio \- pdf read/write library
.SH Introduction
@ -552,8 +552,234 @@ If you have a JPEG or PNG file, use the pdfioFileCreateImageObjFromFile function
.fi
.PP
Page Dictionary Functions
.PP
PDF pages each have an associated dictionary to specify the images, fonts, and color spaces used by the page. PDFio provides functions to add these resources to the dictionary:
.IP \(bu 5
.PP
pdfioPageDictAddColorSpace adds a named color space to the page dictionary
.IP \(bu 5
.PP
pdfioPageDictAddFont adds a named font to the page dictionary
.IP \(bu 5
.PP
pdfioPageDictAddImage adds a named image to the page dictionary
.PP
Page Stream Functions
.PP
PDF page streams contain textual commands for drawing on the page. PDFio provides many functions for writing these commands with the correct format and escaping, as needed:
.IP \(bu 5
.PP
pdfioContentClip clips future drawing to the current path
.IP \(bu 5
.PP
pdfioContentDrawImage draws an image object
.IP \(bu 5
.PP
pdfioContentFill fills the current path
.IP \(bu 5
.PP
pdfioContentFillAndStroke fills and strokes the current path
.IP \(bu 5
.PP
pdfioContentMatrixConcat concatenates a matrix with the current transform matrix
.IP \(bu 5
.PP
pdfioContentMatrixRotate concatenates a rotation matrix with the current transform matrix
.IP \(bu 5
.PP
pdfioContentMatrixScale concatenates a scaling matrix with the current transform matrix
.IP \(bu 5
.PP
pdfioContentMatrixTranslate concatenates a translation matrix with the current transform matrix
.IP \(bu 5
.PP
pdfioContentPathClose closes the current path
.IP \(bu 5
.PP
pdfioContentPathCurve appends a Bezier curve to the current path
.IP \(bu 5
.PP
pdfioContentPathCurve13 appends a Bezier curve with 2 control points to the current path
.IP \(bu 5
.PP
pdfioContentPathCurve23 appends a Bezier curve with 2 control points to the current path
.IP \(bu 5
.PP
pdfioContentPathLineTo appends a line to the current path
.IP \(bu 5
.PP
pdfioContentPathMoveTo moves the current point in the current path
.IP \(bu 5
.PP
pdfioContentPathRect appends a rectangle to the current path
.IP \(bu 5
.PP
pdfioContentRestore restores a previous graphics state
.IP \(bu 5
.PP
pdfioContentSave saves the current graphics state
.IP \(bu 5
.PP
pdfioContentSetDashPattern sets the line dash pattern
.IP \(bu 5
.PP
pdfioContentSetFillColorDeviceCMYK sets the current fill color using a device CMYK color
.IP \(bu 5
.PP
pdfioContentSetFillColorDeviceGray sets the current fill color using a device gray color
.IP \(bu 5
.PP
pdfioContentSetFillColorDeviceRGB sets the current fill color using a device RGB color
.IP \(bu 5
.PP
pdfioContentSetFillColorGray sets the current fill color using a calibrated gray color
.IP \(bu 5
.PP
pdfioContentSetFillColorRGB sets the current fill color using a calibrated RGB color
.IP \(bu 5
.PP
pdfioContentSetFillColorSpace sets the current fill color space
.IP \(bu 5
.PP
pdfioContentSetFlatness sets the flatness for curves
.IP \(bu 5
.PP
pdfioContentSetLineCap sets how the ends of lines are stroked
.IP \(bu 5
.PP
pdfioContentSetLineJoin sets how connections between lines are stroked
.IP \(bu 5
.PP
pdfioContentSetLineWidth sets the width of stroked lines
.IP \(bu 5
.PP
pdfioContentSetMiterLimit sets the miter limit for stroked lines
.IP \(bu 5
.PP
pdfioContentSetStrokeColorDeviceCMYK sets the current stroke color using a device CMYK color
.IP \(bu 5
.PP
pdfioContentSetStrokeColorDeviceGray sets the current stroke color using a device gray color
.IP \(bu 5
.PP
pdfioContentSetStrokeColorDeviceRGB sets the current stroke color using a device RGB color
.IP \(bu 5
.PP
pdfioContentSetStrokeColorGray sets the current stroke color using a calibrated gray color
.IP \(bu 5
.PP
pdfioContentSetStrokeColorRGB sets the current stroke color using a calibrated RGB color
.IP \(bu 5
.PP
pdfioContentSetStrokeColorSpace sets the current stroke color space
.IP \(bu 5
.PP
pdfioContentSetTextCharacterSpacing sets the spacing between characters for text
.IP \(bu 5
.PP
pdfioContentSetTextFont sets the font and size for text
.IP \(bu 5
.PP
pdfioContentSetTextLeading sets the line height for text
.IP \(bu 5
.PP
pdfioContentSetTextMatrix concatenates a matrix with the current text matrix
.IP \(bu 5
.PP
pdfioContentSetTextRenderingMode sets the text rendering mode
.IP \(bu 5
.PP
pdfioContentSetTextRise adjusts the baseline for text
.IP \(bu 5
.PP
pdfioContentSetTextWordSpacing sets the spacing between words for text
.IP \(bu 5
.PP
pdfioContentSetTextXScaling sets the horizontal scaling for text
.IP \(bu 5
.PP
pdfioContentStroke strokes the current path
.IP \(bu 5
.PP
pdfioContentTextBegin begins a block of text
.IP \(bu 5
.PP
pdfioContentTextEnd ends a block of text
.IP \(bu 5
.PP
pdfioContentTextMoveLine moves to the next line with an offset in a text block
.IP \(bu 5
.PP
pdfioContentTextMoveTo moves within the current line in a text block
.IP \(bu 5
.PP
pdfioContentTextNextLine moves to the beginning of the next line in a text block
.IP \(bu 5
.PP
pdfioContentTextShow draws a literal string in a text block
.IP \(bu 5
.PP
pdfioContentTextShowf draws a formatted string in a text block
.IP \(bu 5
.PP
pdfioContentTextShowJustified draws an array of literal strings with offsets between them
.SH ENUMERATIONS
.SS pdfio_filter_e

View File

@ -783,7 +783,123 @@ pdfio_obj_t *img = pdfioFileCreateImageObjFromData(pdf, data, <span class="comme
pdfio_obj_t *img = pdfioFileCreateImageObjFromFile(pdf, <span class="string">&quot;myphoto.jpg&quot;</span>, <span class="comment">/*interpolate*/</span><span class="reserved">true</span>);
</code></pre>
<h4 id="page-dictionary-functions">Page Dictionary Functions</h4>
<p>PDF pages each have an associated dictionary to specify the images, fonts, and color spaces used by the page. PDFio provides functions to add these resources to the dictionary:</p>
<ul>
<li><p><a href="#pdfioPageDictAddColorSpace"><code>pdfioPageDictAddColorSpace</code></a> adds a named color space to the page dictionary</p>
</li>
<li><p><a href="#pdfioPageDictAddFont"><code>pdfioPageDictAddFont</code></a> adds a named font to the page dictionary</p>
</li>
<li><p><a href="#pdfioPageDictAddImage"><code>pdfioPageDictAddImage</code></a> adds a named image to the page dictionary</p>
</li>
</ul>
<h4 id="page-stream-functions">Page Stream Functions</h4>
<p>PDF page streams contain textual commands for drawing on the page. PDFio provides many functions for writing these commands with the correct format and escaping, as needed:</p>
<ul>
<li><p><a href="#pdfioContentClip"><code>pdfioContentClip</code></a> clips future drawing to the current path</p>
</li>
<li><p><a href="#pdfioContentDrawImage"><code>pdfioContentDrawImage</code></a> draws an image object</p>
</li>
<li><p><a href="#pdfioContentFill"><code>pdfioContentFill</code></a> fills the current path</p>
</li>
<li><p><a href="#pdfioContentFillAndStroke"><code>pdfioContentFillAndStroke</code></a> fills and strokes the current path</p>
</li>
<li><p><a href="#pdfioContentMatrixConcat"><code>pdfioContentMatrixConcat</code></a> concatenates a matrix with the current transform matrix</p>
</li>
<li><p><a href="#pdfioContentMatrixRotate"><code>pdfioContentMatrixRotate</code></a> concatenates a rotation matrix with the current transform matrix</p>
</li>
<li><p><a href="#pdfioContentMatrixScale"><code>pdfioContentMatrixScale</code></a> concatenates a scaling matrix with the current transform matrix</p>
</li>
<li><p><a href="#pdfioContentMatrixTranslate"><code>pdfioContentMatrixTranslate</code></a> concatenates a translation matrix with the current transform matrix</p>
</li>
<li><p><a href="#pdfioContentPathClose"><code>pdfioContentPathClose</code></a> closes the current path</p>
</li>
<li><p><a href="#pdfioContentPathCurve"><code>pdfioContentPathCurve</code></a> appends a Bezier curve to the current path</p>
</li>
<li><p><a href="#pdfioContentPathCurve13"><code>pdfioContentPathCurve13</code></a> appends a Bezier curve with 2 control points to the current path</p>
</li>
<li><p><a href="#pdfioContentPathCurve23"><code>pdfioContentPathCurve23</code></a> appends a Bezier curve with 2 control points to the current path</p>
</li>
<li><p><a href="#pdfioContentPathLineTo"><code>pdfioContentPathLineTo</code></a> appends a line to the current path</p>
</li>
<li><p><a href="#pdfioContentPathMoveTo"><code>pdfioContentPathMoveTo</code></a> moves the current point in the current path</p>
</li>
<li><p><a href="#pdfioContentPathRect"><code>pdfioContentPathRect</code></a> appends a rectangle to the current path</p>
</li>
<li><p><a href="#pdfioContentRestore"><code>pdfioContentRestore</code></a> restores a previous graphics state</p>
</li>
<li><p><a href="#pdfioContentSave"><code>pdfioContentSave</code></a> saves the current graphics state</p>
</li>
<li><p><a href="#pdfioContentSetDashPattern"><code>pdfioContentSetDashPattern</code></a> sets the line dash pattern</p>
</li>
<li><p><a href="#pdfioContentSetFillColorDeviceCMYK"><code>pdfioContentSetFillColorDeviceCMYK</code></a> sets the current fill color using a device CMYK color</p>
</li>
<li><p><a href="#pdfioContentSetFillColorDeviceGray"><code>pdfioContentSetFillColorDeviceGray</code></a> sets the current fill color using a device gray color</p>
</li>
<li><p><a href="#pdfioContentSetFillColorDeviceRGB"><code>pdfioContentSetFillColorDeviceRGB</code></a> sets the current fill color using a device RGB color</p>
</li>
<li><p><a href="#pdfioContentSetFillColorGray"><code>pdfioContentSetFillColorGray</code></a> sets the current fill color using a calibrated gray color</p>
</li>
<li><p><a href="#pdfioContentSetFillColorRGB"><code>pdfioContentSetFillColorRGB</code></a> sets the current fill color using a calibrated RGB color</p>
</li>
<li><p><a href="#pdfioContentSetFillColorSpace"><code>pdfioContentSetFillColorSpace</code></a> sets the current fill color space</p>
</li>
<li><p><a href="#pdfioContentSetFlatness"><code>pdfioContentSetFlatness</code></a> sets the flatness for curves</p>
</li>
<li><p><a href="#pdfioContentSetLineCap"><code>pdfioContentSetLineCap</code></a> sets how the ends of lines are stroked</p>
</li>
<li><p><a href="#pdfioContentSetLineJoin"><code>pdfioContentSetLineJoin</code></a> sets how connections between lines are stroked</p>
</li>
<li><p><a href="#pdfioContentSetLineWidth"><code>pdfioContentSetLineWidth</code></a> sets the width of stroked lines</p>
</li>
<li><p><a href="#pdfioContentSetMiterLimit"><code>pdfioContentSetMiterLimit</code></a> sets the miter limit for stroked lines</p>
</li>
<li><p><a href="#pdfioContentSetStrokeColorDeviceCMYK"><code>pdfioContentSetStrokeColorDeviceCMYK</code></a> sets the current stroke color using a device CMYK color</p>
</li>
<li><p><a href="#pdfioContentSetStrokeColorDeviceGray"><code>pdfioContentSetStrokeColorDeviceGray</code></a> sets the current stroke color using a device gray color</p>
</li>
<li><p><a href="#pdfioContentSetStrokeColorDeviceRGB"><code>pdfioContentSetStrokeColorDeviceRGB</code></a> sets the current stroke color using a device RGB color</p>
</li>
<li><p><a href="#pdfioContentSetStrokeColorGray"><code>pdfioContentSetStrokeColorGray</code></a> sets the current stroke color using a calibrated gray color</p>
</li>
<li><p><a href="#pdfioContentSetStrokeColorRGB"><code>pdfioContentSetStrokeColorRGB</code></a> sets the current stroke color using a calibrated RGB color</p>
</li>
<li><p><a href="#pdfioContentSetStrokeColorSpace"><code>pdfioContentSetStrokeColorSpace</code></a> sets the current stroke color space</p>
</li>
<li><p><a href="#pdfioContentSetTextCharacterSpacing"><code>pdfioContentSetTextCharacterSpacing</code></a> sets the spacing between characters for text</p>
</li>
<li><p><a href="#pdfioContentSetTextFont"><code>pdfioContentSetTextFont</code></a> sets the font and size for text</p>
</li>
<li><p><a href="#pdfioContentSetTextLeading"><code>pdfioContentSetTextLeading</code></a> sets the line height for text</p>
</li>
<li><p><a href="#pdfioContentSetTextMatrix"><code>pdfioContentSetTextMatrix</code></a> concatenates a matrix with the current text matrix</p>
</li>
<li><p><a href="#pdfioContentSetTextRenderingMode"><code>pdfioContentSetTextRenderingMode</code></a> sets the text rendering mode</p>
</li>
<li><p><a href="#pdfioContentSetTextRise"><code>pdfioContentSetTextRise</code></a> adjusts the baseline for text</p>
</li>
<li><p><a href="#pdfioContentSetTextWordSpacing"><code>pdfioContentSetTextWordSpacing</code></a> sets the spacing between words for text</p>
</li>
<li><p><a href="#pdfioContentSetTextXScaling"><code>pdfioContentSetTextXScaling</code></a> sets the horizontal scaling for text</p>
</li>
<li><p><a href="#pdfioContentStroke"><code>pdfioContentStroke</code></a> strokes the current path</p>
</li>
<li><p><a href="#pdfioContentTextBegin"><code>pdfioContentTextBegin</code></a> begins a block of text</p>
</li>
<li><p><a href="#pdfioContentTextEnd"><code>pdfioContentTextEnd</code></a> ends a block of text</p>
</li>
<li><p><a href="#pdfioContentTextMoveLine"><code>pdfioContentTextMoveLine</code></a> moves to the next line with an offset in a text block</p>
</li>
<li><p><a href="#pdfioContentTextMoveTo"><code>pdfioContentTextMoveTo</code></a> moves within the current line in a text block</p>
</li>
<li><p><a href="#pdfioContentTextNextLine"><code>pdfioContentTextNextLine</code></a> moves to the beginning of the next line in a text block</p>
</li>
<li><p><a href="#pdfioContentTextShow"><code>pdfioContentTextShow</code></a> draws a literal string in a text block</p>
</li>
<li><p><a href="#pdfioContentTextShowf"><code>pdfioContentTextShowf</code></a> draws a formatted string in a text block</p>
</li>
<li><p><a href="#pdfioContentTextShowJustified"><code>pdfioContentTextShowJustified</code></a> draws an array of literal strings with offsets between them</p>
</li>
</ul>
<h2 class="title"><a id="FUNCTIONS">Functions</a></h2>
<h3 class="function"><a id="pdfioArrayAppendArray">pdfioArrayAppendArray</a></h3>
<p class="description">Add an array value to an array.</p>

View File

@ -471,6 +471,90 @@ pdfio_obj_t *img = pdfioFileCreateImageObjFromFile(pdf, "myphoto.jpg", /*interpo
### Page Dictionary Functions
PDF pages each have an associated dictionary to specify the images, fonts, and color spaces used by the page. PDFio provides functions to add these resources
to the dictionary:
- [`pdfioPageDictAddColorSpace`](@@) adds a named color space to the page dictionary
- [`pdfioPageDictAddFont`](@@) adds a named font to the page dictionary
- [`pdfioPageDictAddImage`](@@) adds a named image to the page dictionary
### Page Stream Functions
PDF page streams contain textual commands for drawing on the page. PDFio
provides many functions for writing these commands with the correct format and
escaping, as needed:
- [`pdfioContentClip`](@@) clips future drawing to the current path
- [`pdfioContentDrawImage`](@@) draws an image object
- [`pdfioContentFill`](@@) fills the current path
- [`pdfioContentFillAndStroke`](@@) fills and strokes the current path
- [`pdfioContentMatrixConcat`](@@) concatenates a matrix with the current
transform matrix
- [`pdfioContentMatrixRotate`](@@) concatenates a rotation matrix with the
current transform matrix
- [`pdfioContentMatrixScale`](@@) concatenates a scaling matrix with the
current transform matrix
- [`pdfioContentMatrixTranslate`](@@) concatenates a translation matrix with the
current transform matrix
- [`pdfioContentPathClose`](@@) closes the current path
- [`pdfioContentPathCurve`](@@) appends a Bezier curve to the current path
- [`pdfioContentPathCurve13`](@@) appends a Bezier curve with 2 control points
to the current path
- [`pdfioContentPathCurve23`](@@) appends a Bezier curve with 2 control points
to the current path
- [`pdfioContentPathLineTo`](@@) appends a line to the current path
- [`pdfioContentPathMoveTo`](@@) moves the current point in the current path
- [`pdfioContentPathRect`](@@) appends a rectangle to the current path
- [`pdfioContentRestore`](@@) restores a previous graphics state
- [`pdfioContentSave`](@@) saves the current graphics state
- [`pdfioContentSetDashPattern`](@@) sets the line dash pattern
- [`pdfioContentSetFillColorDeviceCMYK`](@@) sets the current fill color using a
device CMYK color
- [`pdfioContentSetFillColorDeviceGray`](@@) sets the current fill color using a
device gray color
- [`pdfioContentSetFillColorDeviceRGB`](@@) sets the current fill color using a
device RGB color
- [`pdfioContentSetFillColorGray`](@@) sets the current fill color using a
calibrated gray color
- [`pdfioContentSetFillColorRGB`](@@) sets the current fill color using a
calibrated RGB color
- [`pdfioContentSetFillColorSpace`](@@) sets the current fill color space
- [`pdfioContentSetFlatness`](@@) sets the flatness for curves
- [`pdfioContentSetLineCap`](@@) sets how the ends of lines are stroked
- [`pdfioContentSetLineJoin`](@@) sets how connections between lines are stroked
- [`pdfioContentSetLineWidth`](@@) sets the width of stroked lines
- [`pdfioContentSetMiterLimit`](@@) sets the miter limit for stroked lines
- [`pdfioContentSetStrokeColorDeviceCMYK`](@@) sets the current stroke color
using a device CMYK color
- [`pdfioContentSetStrokeColorDeviceGray`](@@) sets the current stroke color
using a device gray color
- [`pdfioContentSetStrokeColorDeviceRGB`](@@) sets the current stroke color
using a device RGB color
- [`pdfioContentSetStrokeColorGray`](@@) sets the current stroke color
using a calibrated gray color
- [`pdfioContentSetStrokeColorRGB`](@@) sets the current stroke color
using a calibrated RGB color
- [`pdfioContentSetStrokeColorSpace`](@@) sets the current stroke color space
- [`pdfioContentSetTextCharacterSpacing`](@@) sets the spacing between
characters for text
- [`pdfioContentSetTextFont`](@@) sets the font and size for text
- [`pdfioContentSetTextLeading`](@@) sets the line height for text
- [`pdfioContentSetTextMatrix`](@@) concatenates a matrix with the current text
matrix
- [`pdfioContentSetTextRenderingMode`](@@) sets the text rendering mode
- [`pdfioContentSetTextRise`](@@) adjusts the baseline for text
- [`pdfioContentSetTextWordSpacing`](@@) sets the spacing between words for text
- [`pdfioContentSetTextXScaling`](@@) sets the horizontal scaling for text
- [`pdfioContentStroke`](@@) strokes the current path
- [`pdfioContentTextBegin`](@@) begins a block of text
- [`pdfioContentTextEnd`](@@) ends a block of text
- [`pdfioContentTextMoveLine`](@@) moves to the next line with an offset in a
text block
- [`pdfioContentTextMoveTo`](@@) moves within the current line in a text block
- [`pdfioContentTextNextLine`](@@) moves to the beginning of the next line in a
text block
- [`pdfioContentTextShow`](@@) draws a literal string in a text block
- [`pdfioContentTextShowf`](@@) draws a formatted string in a text block
- [`pdfioContentTextShowJustified`](@@) draws an array of literal strings with
offsets between them

View File

@ -87,7 +87,7 @@
<ClCompile>
<WarningLevel>Level3</WarningLevel>
<SDLCheck>true</SDLCheck>
<PreprocessorDefinitions>WIN32;_DEBUG;_CONSOLE;%(PreprocessorDefinitions)</PreprocessorDefinitions>
<PreprocessorDefinitions>PDFIO_VERSION="1.0b1";WIN32;_DEBUG;_CONSOLE;%(PreprocessorDefinitions)</PreprocessorDefinitions>
<ConformanceMode>true</ConformanceMode>
</ClCompile>
<Link>
@ -101,7 +101,7 @@
<FunctionLevelLinking>true</FunctionLevelLinking>
<IntrinsicFunctions>true</IntrinsicFunctions>
<SDLCheck>true</SDLCheck>
<PreprocessorDefinitions>WIN32;NDEBUG;_CONSOLE;%(PreprocessorDefinitions)</PreprocessorDefinitions>
<PreprocessorDefinitions>PDFIO_VERSION="1.0b1";WIN32;NDEBUG;_CONSOLE;%(PreprocessorDefinitions)</PreprocessorDefinitions>
<ConformanceMode>true</ConformanceMode>
</ClCompile>
<Link>
@ -115,7 +115,7 @@
<ClCompile>
<WarningLevel>Level3</WarningLevel>
<SDLCheck>true</SDLCheck>
<PreprocessorDefinitions>_DEBUG;_CONSOLE;%(PreprocessorDefinitions)</PreprocessorDefinitions>
<PreprocessorDefinitions>PDFIO_VERSION="1.0b1";_DEBUG;_CONSOLE;%(PreprocessorDefinitions)</PreprocessorDefinitions>
<ConformanceMode>true</ConformanceMode>
</ClCompile>
<Link>
@ -129,7 +129,7 @@
<FunctionLevelLinking>true</FunctionLevelLinking>
<IntrinsicFunctions>true</IntrinsicFunctions>
<SDLCheck>true</SDLCheck>
<PreprocessorDefinitions>NDEBUG;_CONSOLE;%(PreprocessorDefinitions)</PreprocessorDefinitions>
<PreprocessorDefinitions>PDFIO_VERSION="1.0b1";NDEBUG;_CONSOLE;%(PreprocessorDefinitions)</PreprocessorDefinitions>
<ConformanceMode>true</ConformanceMode>
</ClCompile>
<Link>

View File

@ -352,7 +352,7 @@
CLANG_WARN__DUPLICATE_METHOD_MATCH = YES;
CODE_SIGN_IDENTITY = "Developer ID Application";
COPY_PHASE_STRIP = NO;
CURRENT_PROJECT_VERSION = 0.2;
CURRENT_PROJECT_VERSION = 1.0;
DEBUG_INFORMATION_FORMAT = dwarf;
ENABLE_STRICT_OBJC_MSGSEND = YES;
ENABLE_TESTABILITY = YES;
@ -430,7 +430,7 @@
CLANG_WARN__DUPLICATE_METHOD_MATCH = YES;
CODE_SIGN_IDENTITY = "Developer ID Application";
COPY_PHASE_STRIP = NO;
CURRENT_PROJECT_VERSION = 0.2;
CURRENT_PROJECT_VERSION = 1.0;
DEBUG_INFORMATION_FORMAT = "dwarf-with-dsym";
ENABLE_HARDENED_RUNTIME = YES;
ENABLE_NS_ASSERTIONS = NO;