mirror of
https://github.com/michaelrsweet/pdfio.git
synced 2025-08-29 15:22:06 +02:00
Update docos.
This commit is contained in:
70
doc/pdfio.3
70
doc/pdfio.3
@@ -1,4 +1,4 @@
|
||||
.TH pdfio 3 "pdf read/write library" "2025-04-12" "pdf read/write library"
|
||||
.TH pdfio 3 "pdf read/write library" "2025-04-24" "pdf read/write library"
|
||||
.SH NAME
|
||||
pdfio \- pdf read/write library
|
||||
.SH Introduction
|
||||
@@ -325,7 +325,7 @@ where the five arguments to the function are the filename ("myinputfile.pdf"), a
|
||||
}
|
||||
.fi
|
||||
.PP
|
||||
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:
|
||||
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. It returns true to continue processing the file or false to stop, for example:
|
||||
.nf
|
||||
|
||||
bool
|
||||
@@ -335,12 +335,15 @@ The error callback is called for both errors and warnings and accepts the pdfio_
|
||||
|
||||
fprintf(stderr, "%s: %s\\n", pdfioFileGetName(pdf), message);
|
||||
|
||||
// Return false to treat warnings as errors
|
||||
return (false);
|
||||
// Return true for warning messages (continue) and false for errors (stop)
|
||||
return (!strncmp(message, "WARNING:", 8));
|
||||
}
|
||||
.fi
|
||||
.PP
|
||||
The default error callback (NULL) does the equivalent of the above.
|
||||
.PP
|
||||
Note: Many errors are unrecoverable, so PDFio ignores the return value from the error callback and always stops processing the PDF file. Warning messages start with the prefix "WARNING:" while errors have no prefix.
|
||||
|
||||
.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
|
||||
@@ -2477,7 +2480,7 @@ PDFIO_ENCRYPTION_RC4_128
|
||||
.TP 5
|
||||
PDFIO_ENCRYPTION_RC4_40
|
||||
.br
|
||||
40-bit RC4 encryption (PDF 1.3)
|
||||
40-bit RC4 encryption (PDF 1.3, reading only)
|
||||
.SS pdfio_filter_e
|
||||
Compression/decompression filters for streams
|
||||
.TP 5
|
||||
@@ -2947,6 +2950,8 @@ bool pdfioArrayRemove (
|
||||
size_t n
|
||||
);
|
||||
.fi
|
||||
.PP
|
||||
|
||||
.SS pdfioContentClip
|
||||
Clip output to the current path.
|
||||
.PP
|
||||
@@ -3083,6 +3088,8 @@ bool pdfioContentPathEnd (
|
||||
pdfio_stream_t *st
|
||||
);
|
||||
.fi
|
||||
.PP
|
||||
|
||||
.SS pdfioContentPathLineTo
|
||||
Add a straight line to the current path.
|
||||
.PP
|
||||
@@ -3423,6 +3430,8 @@ double pdfioContentTextMeasure (
|
||||
This function measures the given text string "s" and returns its width based
|
||||
on "size". The text string must always use the UTF-8 (Unicode) encoding but
|
||||
any control characters (such as newlines) are ignored.
|
||||
|
||||
|
||||
.SS pdfioContentTextMoveLine
|
||||
Move to the next line and offset.
|
||||
.PP
|
||||
@@ -3451,6 +3460,8 @@ bool pdfioContentTextNewLine (
|
||||
pdfio_stream_t *st
|
||||
);
|
||||
.fi
|
||||
.PP
|
||||
|
||||
.SS pdfioContentTextNewLineShow
|
||||
Move to the next line and show text.
|
||||
.PP
|
||||
@@ -3468,6 +3479,8 @@ This function moves to the next line and then shows some text with optional
|
||||
word and character spacing in a PDF content stream. The "unicode" argument
|
||||
specifies that the current font maps to full Unicode. The "s" argument
|
||||
specifies a UTF-8 encoded string.
|
||||
|
||||
|
||||
.SS pdfioContentTextNewLineShowf
|
||||
Show formatted text.
|
||||
.PP
|
||||
@@ -3486,6 +3499,8 @@ This function moves to the next line and shows some formatted text with
|
||||
optional word and character spacing in a PDF content stream. The "unicode"
|
||||
argument specifies that the current font maps to full Unicode. The "format"
|
||||
argument specifies a UTF-8 encoded \fBprintf\fR-style format string.
|
||||
|
||||
|
||||
.SS pdfioContentTextShow
|
||||
Show text.
|
||||
.PP
|
||||
@@ -3536,6 +3551,8 @@ bool pdfioDictClear (
|
||||
const char *key
|
||||
);
|
||||
.fi
|
||||
.PP
|
||||
|
||||
.SS pdfioDictCopy
|
||||
Copy a dictionary to a PDF file.
|
||||
.PP
|
||||
@@ -3608,6 +3625,8 @@ const char * pdfioDictGetKey (
|
||||
size_t n
|
||||
);
|
||||
.fi
|
||||
.PP
|
||||
|
||||
.SS pdfioDictGetName
|
||||
Get a key name value from a dictionary.
|
||||
.PP
|
||||
@@ -3625,6 +3644,8 @@ size_t pdfioDictGetNumPairs (
|
||||
pdfio_dict_t *dict
|
||||
);
|
||||
.fi
|
||||
.PP
|
||||
|
||||
.SS pdfioDictGetNumber
|
||||
Get a key number value from a dictionary.
|
||||
.PP
|
||||
@@ -3697,6 +3718,8 @@ function "cb":
|
||||
|
||||
The iteration continues as long as the callback returns \fBtrue\fR or all keys
|
||||
have been iterated.
|
||||
|
||||
|
||||
.SS pdfioDictSetArray
|
||||
Set a key array in a dictionary.
|
||||
.PP
|
||||
@@ -3852,8 +3875,9 @@ CropBox for pages in the PDF file - if \fBNULL\fR then a default "Universal" siz
|
||||
of 8.27x11in (the intersection of US Letter and ISO A4) is used.
|
||||
.PP
|
||||
The "error_cb" and "error_cbdata" arguments specify an error handler callback
|
||||
and its data pointer - if \fBNULL\fR the default error handler is used that
|
||||
writes error messages to \fBstderr\fR.
|
||||
and its data pointer - if \fBNULL\fR then the default error handler is used that
|
||||
writes error messages to \fBstderr\fR. The error handler callback should return
|
||||
\fBtrue\fR to continue writing the PDF file or \fBfalse\fR to stop.
|
||||
.SS pdfioFileCreateArrayObj
|
||||
Create a new object in a PDF file containing an array.
|
||||
.PP
|
||||
@@ -4011,6 +4035,8 @@ pdfio_obj_t * pdfioFileCreateNameObj (
|
||||
.PP
|
||||
This function creates a new object with a name value in a PDF file.
|
||||
You must call \fIpdfioObjClose\fR to write the object to the file.
|
||||
|
||||
|
||||
.SS pdfioFileCreateNumberObj
|
||||
Create a new object in a PDF file containing a number.
|
||||
.PP
|
||||
@@ -4023,6 +4049,8 @@ pdfio_obj_t * pdfioFileCreateNumberObj (
|
||||
.PP
|
||||
This function creates a new object with a number value in a PDF file.
|
||||
You must call \fIpdfioObjClose\fR to write the object to the file.
|
||||
|
||||
|
||||
.SS pdfioFileCreateObj
|
||||
Create a new object in a PDF file.
|
||||
.PP
|
||||
@@ -4071,8 +4099,9 @@ CropBox for pages in the PDF file - if \fBNULL\fR then a default "Universal" siz
|
||||
of 8.27x11in (the intersection of US Letter and ISO A4) is used.
|
||||
.PP
|
||||
The "error_cb" and "error_cbdata" arguments specify an error handler callback
|
||||
and its data pointer - if \fBNULL\fR the default error handler is used that
|
||||
writes error messages to \fBstderr\fR.
|
||||
and its data pointer - if \fBNULL\fR then the default error handler is used that
|
||||
writes error messages to \fBstderr\fR. The error handler callback should return
|
||||
\fBtrue\fR to continue writing the PDF file or \fBfalse\fR to stop.
|
||||
.PP
|
||||
.IP 5
|
||||
\fINote\fR: Files created using this API are slightly larger than those
|
||||
@@ -4101,6 +4130,8 @@ pdfio_obj_t * pdfioFileCreateStringObj (
|
||||
.PP
|
||||
This function creates a new object with a string value in a PDF file.
|
||||
You must call \fIpdfioObjClose\fR to write the object to the file.
|
||||
|
||||
|
||||
.SS pdfioFileCreateTemporary
|
||||
|
||||
.PP
|
||||
@@ -4294,8 +4325,18 @@ cancel the open. If \fBNULL\fR is specified for the callback function and the
|
||||
PDF file requires a password, the open will always fail.
|
||||
.PP
|
||||
The "error_cb" and "error_cbdata" arguments specify an error handler callback
|
||||
and its data pointer - if \fBNULL\fR the default error handler is used that
|
||||
writes error messages to \fBstderr\fR.
|
||||
and its data pointer - if \fBNULL\fR then the default error handler is used that
|
||||
writes error messages to \fBstderr\fR. The error handler callback should return
|
||||
\fBtrue\fR to continue reading the PDF file or \fBfalse\fR to stop.
|
||||
.PP
|
||||
.IP 5
|
||||
Note: Error messages starting with "WARNING:" are actually warning
|
||||
.IP 5
|
||||
messages - the callback should normally return \fBtrue\fR to allow PDFio to
|
||||
.IP 5
|
||||
try to resolve the issue. In addition, some errors are unrecoverable and
|
||||
.IP 5
|
||||
ignore the return value of the error callback.
|
||||
.SS pdfioFileSetAuthor
|
||||
Set the author for a PDF file.
|
||||
.PP
|
||||
@@ -4474,6 +4515,8 @@ const char * pdfioObjGetName (
|
||||
pdfio_obj_t *obj
|
||||
);
|
||||
.fi
|
||||
.PP
|
||||
|
||||
.SS pdfioObjGetNumber
|
||||
Get the object's number.
|
||||
.PP
|
||||
@@ -4677,8 +4720,9 @@ bool pdfioStreamPrintf (
|
||||
.fi
|
||||
.PP
|
||||
This function writes a formatted string to a stream. In addition to the
|
||||
standard \fBprintf\fR format characters, you can use "%N" to format a PDF name
|
||||
value ("/Name") and "%S" to format a PDF string ("(String)") value.
|
||||
standard \fBprintf\fR format characters, you can use "%H" to format a HTML/XML
|
||||
string value, "%N" to format a PDF name value ("/Name"), and "%S" to format
|
||||
a PDF string ("(String)") value.
|
||||
.SS pdfioStreamPutChar
|
||||
Write a single character to a stream.
|
||||
.PP
|
||||
|
Reference in New Issue
Block a user