From 3c9a52a824b494e801f3d81fa1d2d76dc8d4fb1c Mon Sep 17 00:00:00 2001 From: Michael R Sweet Date: Sun, 5 Oct 2025 15:35:23 -0400 Subject: [PATCH] Update docos. --- doc/pdfio.3 | 73 ++++++++++++++++++++++++++++------ doc/pdfio.html | 105 +++++++++++++++++++++++++++++++++++++++++-------- 2 files changed, 151 insertions(+), 27 deletions(-) diff --git a/doc/pdfio.3 b/doc/pdfio.3 index d16995b..d2d3fad 100644 --- a/doc/pdfio.3 +++ b/doc/pdfio.3 @@ -1,4 +1,4 @@ -.TH pdfio 3 "pdf read/write library" "2025-09-30" "pdf read/write library" +.TH pdfio 3 "pdf read/write library" "2025-10-05" "pdf read/write library" .SH NAME pdfio \- pdf read/write library .SH Introduction @@ -3999,8 +3999,31 @@ 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"). The value "PCLm-1.0" can be specified to -produce the PCLm subset of PDF. +\fBNULL\fR for the default ("2.0"). The following values are recognized: +.PP +.IP \(bu 5 +"1.3", "1.4", "1.5", "1.6", "1.7", "2.0": Generic PDF files of the + specified versions. +.IP \(bu 5 +"PCLm-1.0": The PCLm (raster) subset of PDF supported by some printers. +.IP \(bu 5 +"PDF/A-1a": PDF/A-1a:2005 +.IP \(bu 5 +"PDF/A-1b": PDF/A-1b:2005 +.IP \(bu 5 +"PDF/A-2a": PDF/A-2a:2011 +.IP \(bu 5 +"PDF/A-2b": PDF/A-2b:2011 +.IP \(bu 5 +"PDF/A-2u": PDF/A-2u:2011 +.IP \(bu 5 +"PDF/A-3a": PDF/A-3a:2012 +.IP \(bu 5 +"PDF/A-3b": PDF/A-3b:2012 +.IP \(bu 5 +"PDF/A-3u": PDF/A-3u:2012 +.IP \(bu 5 +"PDF/A-4": PDF/A-4:2020 .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 @@ -4083,6 +4106,9 @@ specifies the font nane: Aside from "Symbol" and "Zapf-Dingbats", Base fonts use the Windows CP1252 (ISO-8859-1 with additional characters such as the Euro symbol) subset of Unicode. +.PP +.IP 5 +Note: This function cannot be used when producing PDF/A files. .SS pdfioFileCreateFontObjFromData Add a font in memory to a PDF file. .PP @@ -4166,8 +4192,12 @@ the image is encoded in the corresponding device color space. The "interpolate" parameter specifies whether to interpolate when scaling the image on the page. .PP +.IP 5 Note: When creating an image object with alpha, a second image object is -created to hold the "soft mask" data for the primary image. +.IP 5 +created to hold the "soft mask" data for the primary image. PDF/A-1 +.IP 5 +files do not support alpha-based transparency. .SS pdfioFileCreateImageObjFromFile Add an image object to a PDF file from a file. .PP @@ -4185,11 +4215,9 @@ the "interpolate" parameter specifies whether to interpolate when scaling the image on the page. .PP .IP 5 -Note: Currently PNG support is limited to grayscale, RGB, or indexed files +Note: PNG files containing transparency cannot be used when producing .IP 5 -without interlacing or alpha. Transparency (masking) based on color/index -.IP 5 -is supported. +PDF/A files. .SS pdfioFileCreateNameObj Create a new object in a PDF file containing a name. .PP @@ -4257,9 +4285,32 @@ written: .fi The "version" argument specifies the PDF version number for the file or -\fBNULL\fR for the default ("2.0"). Unlike \fIpdfioFileCreate\fR and -\fIpdfioFileCreateTemporary\fR, it is generally not safe to pass the -"PCLm-1.0" version string. +\fBNULL\fR for the default ("2.0"). The following values are recognized: +.PP +.IP \(bu 5 +"1.3", "1.4", "1.5", "1.6", "1.7", "2.0": Generic PDF files of the + specified versions. +.IP \(bu 5 +"PDF/A-1a": PDF/A-1a:2005 +.IP \(bu 5 +"PDF/A-1b": PDF/A-1b:2005 +.IP \(bu 5 +"PDF/A-2a": PDF/A-2a:2011 +.IP \(bu 5 +"PDF/A-2b": PDF/A-2b:2011 +.IP \(bu 5 +"PDF/A-2u": PDF/A-2u:2011 +.IP \(bu 5 +"PDF/A-3a": PDF/A-3a:2012 +.IP \(bu 5 +"PDF/A-3b": PDF/A-3b:2012 +.IP \(bu 5 +"PDF/A-3u": PDF/A-3u:2012 +.IP \(bu 5 +"PDF/A-4": PDF/A-4:2020 +.PP +Unlike \fIpdfioFileCreate\fR and \fIpdfioFileCreateTemporary\fR, it is +generally not safe to pass the "PCLm-1.0" version string. .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 diff --git a/doc/pdfio.html b/doc/pdfio.html index fe2b175..ef982fb 100644 --- a/doc/pdfio.html +++ b/doc/pdfio.html @@ -4222,10 +4222,33 @@ profile using the "cond_id" value. 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 value "PCLm-1.0" can be specified to -produce the PCLm subset of PDF.
-
-The "media_box" and "crop_box" arguments specify the default MediaBox and +NULL for the default ("2.0"). The following values are recognized: + +

+

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.

@@ -4312,7 +4335,10 @@ specifies the font nane:

Aside from "Symbol" and "Zapf-Dingbats", Base fonts use the Windows CP1252 (ISO-8859-1 with additional characters such as the Euro symbol) subset of -Unicode.

+Unicode.
+
+

+Note: This function cannot be used when producing PDF/A files.

 PDFio v1.6 pdfioFileCreateFontObjFromData

Add a font in memory to a PDF file.

@@ -4428,8 +4454,10 @@ the image is encoded in the corresponding device color space. The "interpolate" parameter specifies whether to interpolate when scaling the image on the page.

+

Note: When creating an image object with alpha, a second image object is -created to hold the "soft mask" data for the primary image.

+created to hold the "soft mask" data for the primary image. PDF/A-1 +files do not support alpha-based transparency.

pdfioFileCreateImageObjFromFile

Add an image object to a PDF file from a file.

@@ -4452,9 +4480,8 @@ the "interpolate" parameter specifies whether to interpolate when scal image on the page.

-Note: Currently PNG support is limited to grayscale, RGB, or indexed files -without interlacing or alpha. Transparency (masking) based on color/index -is supported.
+Note: PNG files containing transparency cannot be used when producing +PDF/A files.

 PDFio v1.4 pdfioFileCreateNameObj

Create a new object in a PDF file containing a name.

@@ -4542,9 +4569,32 @@ output_cb(void *output_cbdata, const void *buffer, size_t bytes) The "version" argument specifies the PDF version number for the file or -NULL for the default ("2.0"). Unlike pdfioFileCreate and -pdfioFileCreateTemporary, it is generally not safe to pass the -"PCLm-1.0" version string.
+NULL for the default ("2.0"). The following values are recognized: + +

+

Unlike pdfioFileCreate and pdfioFileCreateTemporary, it is +generally not safe to pass the "PCLm-1.0" version string.

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 @@ -4632,10 +4682,33 @@ temporary directory. The temporary file is stored in the string "buffer&qu will have a ".pdf" extension.

The "version" argument specifies the PDF version number for the file or -NULL for the default ("2.0"). The value "PCLm-1.0" can be specified to -produce the PCLm subset of PDF.
-
-The "media_box" and "crop_box" arguments specify the default MediaBox and +NULL for the default ("2.0"). The following values are recognized: + +

+

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.