From c60893a66ca092eef4a487c265c0678caf040330 Mon Sep 17 00:00:00 2001 From: Michael R Sweet Date: Mon, 26 Jul 2021 09:05:19 -0400 Subject: [PATCH] Finish initial documentation pass. Still need more examples but we'll add more as we go... (Issue #6) --- doc/pdfio.3 | 228 +++++++++++++++++++++++++++++++- doc/pdfio.html | 116 ++++++++++++++++ doc/pdfio.md | 84 ++++++++++++ pdfio.vcxproj | 8 +- pdfio.xcodeproj/project.pbxproj | 4 +- 5 files changed, 433 insertions(+), 7 deletions(-) diff --git a/doc/pdfio.3 b/doc/pdfio.3 index cef00de..50daaa5 100644 --- a/doc/pdfio.3 +++ b/doc/pdfio.3 @@ -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 diff --git a/doc/pdfio.html b/doc/pdfio.html index 6c41d9b..0aee54d 100644 --- a/doc/pdfio.html +++ b/doc/pdfio.html @@ -783,7 +783,123 @@ pdfio_obj_t *img = pdfioFileCreateImageObjFromData(pdf, data, "myphoto.jpg", /*interpolate*/true);

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:

+

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:

+

Functions

pdfioArrayAppendArray

Add an array value to an array.

diff --git a/doc/pdfio.md b/doc/pdfio.md index 852d509..113651f 100644 --- a/doc/pdfio.md +++ b/doc/pdfio.md @@ -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 diff --git a/pdfio.vcxproj b/pdfio.vcxproj index 92e93be..0cb5088 100644 --- a/pdfio.vcxproj +++ b/pdfio.vcxproj @@ -87,7 +87,7 @@ Level3 true - WIN32;_DEBUG;_CONSOLE;%(PreprocessorDefinitions) + PDFIO_VERSION="1.0b1";WIN32;_DEBUG;_CONSOLE;%(PreprocessorDefinitions) true @@ -101,7 +101,7 @@ true true true - WIN32;NDEBUG;_CONSOLE;%(PreprocessorDefinitions) + PDFIO_VERSION="1.0b1";WIN32;NDEBUG;_CONSOLE;%(PreprocessorDefinitions) true @@ -115,7 +115,7 @@ Level3 true - _DEBUG;_CONSOLE;%(PreprocessorDefinitions) + PDFIO_VERSION="1.0b1";_DEBUG;_CONSOLE;%(PreprocessorDefinitions) true @@ -129,7 +129,7 @@ true true true - NDEBUG;_CONSOLE;%(PreprocessorDefinitions) + PDFIO_VERSION="1.0b1";NDEBUG;_CONSOLE;%(PreprocessorDefinitions) true diff --git a/pdfio.xcodeproj/project.pbxproj b/pdfio.xcodeproj/project.pbxproj index 27c9408..16bad3f 100644 --- a/pdfio.xcodeproj/project.pbxproj +++ b/pdfio.xcodeproj/project.pbxproj @@ -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;