dany/pdfio
1
0
Fork 0
mirror of https://github.com/michaelrsweet/pdfio.git synced 2026-01-31 15:37:55 +01:00
Code Issues Packages Projects Releases Wiki Activity

Update documentation.

Browse Source
This commit is contained in:
Michael R Sweet
2026-01-29 12:30:10 -05:00
parent ee42352228
commit 14d844e436
10 changed files with 255 additions and 134 deletions
Download Patch File Download Diff File Expand all files Collapse all files

35
CONTRIBUTING.md
View File

@@ -110,10 +110,11 @@ same guidelines as allowed by the language.
### Source Files
All source files names must be 16 characters or less in length to ensure
compatibility with older UNIX filesystems. Source files containing functions
have an extension of ".c" for C source files. All "include" files have an
extension of ".h". Tabs are set to 8 characters or columns.
All source files names must be lowercase and should be 16 characters or less in
length to ensure compatibility with older UNIX filesystems. Source files
containing functions have an extension of ".c" for C source files. All
"include" files have an extension of ".h". Tabs are set every 8 characters,
columns, or spaces, with an indentation of 2 spaces in code.
The top of each source file contains a header giving the purpose or nature of
the source file and the copyright and licensing notice:
@@ -141,8 +142,8 @@ private API header file will include the corresponding public API header file.
All source code utilizes block comments within functions to describe the
operations being performed by a group of statements; avoid putting a comment
per line unless absolutely necessary, and then consider refactoring the code
so that it is not necessary. C source files use the C99 comment format
("// comment"):
so that it is not necessary. C source files typically use the C99 comment
format ("// comment"):
// Clear the state array before we begin...
for (i = 0; i < (sizeof(array) / sizeof(sizeof(array[0])); i ++)
@@ -159,6 +160,17 @@ so that it is not necessary. C source files use the C99 comment format
sleep(1);
} while (i == (sizeof(array) / sizeof(array[0])));
When passing literal argument values to functions, the argument name should be
supplied as an inline comment:
// This function call lacks any inline comments so it is hard to
// know what the numbers mean!
do_something(filename, 1, 42);
// This uses inline comments to specify what the numbers mean and
// makes the code easier to read and maintain:
do_something(filename, /*initial_value*/1, /*count*/42);
### Indentation
@@ -256,16 +268,16 @@ Return/output values are indicated using an "O" prefix, input values are
indicated using the "I" prefix, and values that are both input and output use
the "IO" prefix for the corresponding in-line comment.
The [`codedoc` documentation generator][1] also understands the following
The [`codedoc` documentation generator][CODEDOC] also understands the following
special text in the function description comment:
@deprecated@ - Marks the function as deprecated (not recommended
for new development and scheduled for removal)
@since version@ - Marks the function as new in the specified version.
@since VERSION@ - Marks the function as new in the specified version.
@private@ - Marks the function as private (same as starting the
function name with an underscore)
[1]: https://www.msweet.org/codedoc
[CODEDOC]: https://www.msweet.org/codedoc
### Variables
@@ -373,11 +385,13 @@ The following variables are defined in the makefile:
- `AR`; the static library archiver command,
- `ARFLAGS`; options for the static library archiver,
- `BUILDROOT`: the destination root directory when installing - also picks up
the value of the `DESTDIR`, `DSTROOT`, and/or `RPM_BUILD_ROOT` environment
variables,
- `CC`; the C compiler command,
- `CFLAGS`; options for the C compiler,
- `CODESIGN_IDENTITY`: the code signing identity,
- `CPPFLAGS`; options for the C preprocessor,
- `DESTDIR`/`DSTROOT`: the destination root directory when installing.
- `DSO`; the shared library building command,
- `DSOFLAGS`; options for the shared library building command,
- `LDFLAGS`; options for the linker,
@@ -395,5 +409,6 @@ The following standard targets are defined in the makefile:
- `all`; creates the static library and unit test program.
- `clean`; removes all target programs libraries, documentation files, and
object files,
- `doc`; creates the library documentation files using [`codedoc`][CODEDOC],
- `install`; installs all distribution files in their corresponding locations.
- `test`; runs the unit test program, building it as needed.

21
EXAMPLES.md
View File

@@ -2,17 +2,12 @@ PDFio Examples
==============
The "examples" subdirectory contains example code showing how to do different
things with PDFio.
things with PDFio:
code128.c
---------
This example shows how to embed and use a barcode font.
md2pdf.c
--------
This example shows how to generate pages with multiple fonts, embedded images,
and headers and footers.
- `code128.c`: Shows how to embed and use a barcode font.
- `image2pdf.c`: Shows how to embed and use an image file.
- `md2pdf.c`: Shows how to generate pages with multiple fonts, embedded images,
and headers and footers.
- `pdf2text.c`: Shows how to extract plain text from a PDF.
- `pdfioinfo.c`: Shows how to extract metadata from a PDF.
- `pdfiomerge.c`: Shows how to merge two or more PDFs.

135
INSTALL.md Normal file
View File

@@ -0,0 +1,135 @@
Building, Testing, and Installing PDFio
=======================================
This file describes how to compile, test, and install the PDFio library from
source code. For more information on PDFio see the file called `README.md`.
Getting the Code
----------------
> Note: Do not use the ZIP file available via the Github "Code" button on the
> main project page, as that archive is missing the TTF submodule and will not
> compile.
The source code is available in release tarballs or via the Github repository.
For a release tarball, run the following commands:
tar xvzf pdfio-VERSION.tar.gz
cd pdfio-VERSION
Similarly, the release ZIP file can be extracted with the following commands:
unzip pdfio-VERSION.zip
cd pdfio-VERSION
From the Github sources, clone the repository with the `--recurse-submodules`
option *or* use the `git submodule` command:
git clone --recurse-submodules git@github.com:michaelrsweet/pdfio.git
cd pdfio
git clone git@github.com:michaelrsweet/pdfio.git
cd pdfio
git submodule update --init --recursive
To update an already-cloned repository:
git pull
git submodule update --init --recursive
Requirements
------------
PDFio requires the following to build the software:
- A C99 compiler such as Clang, GCC, or MS Visual C
- A POSIX-compliant `make` program
- A POSIX-compliant `sh` program
- libpng (<https://www.libpng.org/>) 1.6 or later for full PNG image support
(optional)
- libwebp (<https://developers.google.com/speed/webp>) 1.0 or later for WebP
image support (optional)
- ZLIB (<https://www.zlib.net/>) 1.1 or later for compression support
IDE files for Xcode (macOS/iOS) and Visual Studio (Windows) are also provided.
On a stock Ubuntu install, the following command will install the various
prerequisites:
sudo apt-get install build-essential libpng-dev libwebp-dev zlib1g-dev
Building and Installing on Linux/Unix
-------------------------------------
PDFio uses a configure script on Unix systems to generate a makefile:
./configure
If you want a shared library, run:
./configure --enable-shared
The default installation location is "/usr/local". Pass the `--prefix` option
to make to install it to another location:
./configure --prefix=/some/other/directory
Other configure options can be discovered by using the `--help` option:
./configure --help
Once configured, run the following command to build the library:
make all
Finally, run the following command to install the library, documentation, and
examples on the local system:
sudo make install
Use the `BUILDROOT` variable to install to an alternate root directory:
sudo make BUILDROOT=/some/other/root/directory install
> Note: PDFio also supports the GNU `DSTROOT`, Apple/Darwin `DESTDIR`, and
> Red Hat `RPM_BUILD_ROOT` variables to specify an alternate root directory.
### Running the Unit Tests
PDFio includes a unit test program that thoroughly tests the library. Type the
following to run the unit tests:
make test
Detailed test results are saved to the "test.log" file.
Building on Windows with Visual Studio
--------------------------------------
The Visual Studio solution (`pdfio.sln`) is provided for Windows developers and
generates the PDFIO1 DLL. You can also use NuGet to install the `pdfio_native`
package.
You can build and run the `testpdfio` unit tests target from within Visual
Studio to verify the functioning of the library.
Building on macOS with Xcode
----------------------------
The Xcode project (`pdfio.xcodeproj`) is provided for macOS developer which
generates a static library that will be installed under "/usr/local". Run the
following command to build and install PDFio on macOS:
sudo xcodebuild install
Alternately you can add the Xcode project to a workspace and reference the PDFio
library target as a dependency in your own project.
You can build and run the `testpdfio` unit tests target from within Xcode to
verify the functioning of the library.

4
Makefile.in
View File

@@ -248,13 +248,13 @@ testpdfio: testpdfio.o libpdfio.a
# Dependencies
$(OBJS): pdfio.h pdfio-private.h Makefile
pdfio-content.o: pdfio-content.h
testpdfio.o: test.h
testpdfio.o: test-internal.h
# Make documentation using Codedoc <https://www.msweet.org/codedoc>
DOCFLAGS = \
--author "Michael R Sweet" \
--copyright "Copyright (c) 2021-2025 by Michael R Sweet" \
--copyright "Copyright (c) 2021-2026 by Michael R Sweet" \
--docversion $(PDFIO_VERSION)
.PHONY: doc

100
README.md
View File

@@ -1,4 +1,4 @@
pdfio - PDF Read/Write Library
PDFio - PDF Read/Write Library
==============================
![Version](https://img.shields.io/github/v/release/michaelrsweet/pdfio?include_prereleases)
@@ -20,88 +20,30 @@ goals of PDFio are:
PDFio is *not* concerned with rendering or viewing a PDF file, although a PDF
RIP or viewer could be written using it.
Requirements
------------
PDFio requires the following to build the software:
- A C99 compiler such as Clang, GCC, or MS Visual C
- A POSIX-compliant `make` program
- A POSIX-compliant `sh` program
- libpng (<https://www.libpng.org/>) 1.6 or later for full PNG image support
(optional)
- libwebp (<https://developers.google.com/speed/webp>) 1.0 or later for WebP
image support (optional)
- ZLIB (<https://www.zlib.net/>) 1.1 or later
IDE files for Xcode (macOS/iOS) and Visual Studio (Windows) are also provided.
PDFio is Copyright © 2021-2026 by Michael R Sweet and is licensed under the
Apache License Version 2.0 with an (optional) exception to allow linking against
GNU GPL2-only software. See the files `LICENSE` and `NOTICE` for more
information.
Documentation
-------------
Reading the Documentation
-------------------------
See the man page (`pdfio.3`) and full HTML documentation (`pdfio.html`) for
information on using PDFio.
Initial documentation to get you started is provided in the root directory of
the PDFio sources:
- `CHANGES.md`: A list of changes for each release of PDFio.
- `CODE_OF_CONDUCT.md`: Code of conduct for the project.
- `CONTRIBUTING.md`: Guidelines for contributing to the project.
- `INSTALL.md`: Instructions for building, testing, and installing PDFio.
- `LICENSE`: The PDFio license agreement (Apache 2.0).
- `NOTICE`: Copyright notices and exceptions to the PDFio license agreement.
- `README.md`: This file.
- `SECURITY.md`: How (and when) to report security issues.
Installing PDFio
----------------
You will find the PDFio documentation in HTML, EPUB, and man formats in the
`doc` directory.
PDFio uses a configure script on Unix systems to generate a makefile:
Examples can be found in the `examples` directory.
./configure
If you want a shared library, run:
./configure --enable-shared
The default installation location is "/usr/local". Pass the `--prefix` option
to make to install it to another location:
./configure --prefix=/some/other/directory
Once configured, run the following to make the library:
make all
To test it, run:
make test
To install it, run:
sudo make install
On a stock Ubuntu or Debian installation, the following command will install
the required build prerequisites:
sudo apt install build-essential libpng-dev zlib1g-dev
Visual Studio Project
---------------------
The Visual Studio solution ("pdfio.sln") is provided for Windows developers and
generates the PDFIO1 DLL. You can also use NuGet to install the `pdfio_native`
package.
Xcode Project
-------------
There is also an Xcode project ("pdfio.xcodeproj") you can use on macOS which
generates a static library that will be installed under "/usr/local" with:
sudo xcodebuild install
Legal Stuff
-----------
PDFio is Copyright © 2021-2026 by Michael R Sweet.
This software is licensed under the Apache License Version 2.0 with an
(optional) exception to allow linking against GPL2/LGPL2 software. See the
files "LICENSE" and "NOTICE" for more information.
*Please read the documentation before asking questions.*

28
doc/pdfio.3
View File

@@ -1,4 +1,4 @@
.TH pdfio 3 "pdf read/write library" "2026-01-18" "pdf read/write library"
.TH pdfio 3 "pdf read/write library" "2026-01-29" "pdf read/write library"
.SH NAME
pdfio \- pdf read/write library
.SH Introduction
@@ -60,12 +60,18 @@ libwebp (https://developers.google.com/speed/webp) 1.0 or later for WebP image s
.IP \(bu 5
.PP
ZLIB (https://www.zlib.net/) 1.1 or later
ZLIB (https://www.zlib.net/) 1.1 or later for compression support
.PP
IDE files for Xcode (macOS/iOS) and Visual Studio (Windows) are also provided.
.SS Installing PDFio
.PP
On a stock Ubuntu install, the following command will install the various prerequisites:
.nf
sudo apt\-get install build\-essential libpng\-dev libwebp\-dev zlib1g\-dev
.fi
.SS Building and Installing PDFio on Linux/Unix
.PP
PDFio comes with a configure script that creates a portable makefile that will work on any POSIX\-compliant system with ZLIB installed. To make it, run:
.nf
@@ -105,16 +111,22 @@ Other configure options can be found using the \-\-help option:
\./configure \-\-help
.fi
.SS Visual Studio Project
.SS Building on Windows with Visual Studio
.PP
The Visual Studio solution ("pdfio.sln") is provided for Windows developers and generates both a static library and DLL.
.SS Xcode Project
The Visual Studio solution ("pdfio.sln") is provided for Windows developers and generates the PDFIO1 DLL. You can also use NuGet to install the pdfio_native package.
.PP
There is also an Xcode project ("pdfio.xcodeproj") you can use on macOS which generates a static library that will be installed under "/usr/local" with:
You can build and run the testpdfio unit tests target from within Visual Studio to verify the functioning of the library.
.SS Building on macOS with Xcode
.PP
The Xcode project (pdfio.xcodeproj) is provided for macOS developer which generates a static library that will be installed under "/usr/local". Run the following command to build and install PDFio on macOS:
.nf
sudo xcodebuild install
.fi
.PP
Alternately you can add the Xcode project to a workspace and reference the PDFio library target as a dependency in your own project.
.PP
You can build and run the testpdfio unit tests target from within Xcode to verify the functioning of the library.
.SS Detecting PDFio
.PP
PDFio can be detected using the pkg\-config command, for example:
@@ -5337,4 +5349,4 @@ typedef enum pdfio_valtype_e pdfio_valtype_t;
Michael R Sweet
.SH COPYRIGHT
.PP
Copyright (c) 2021-2025 by Michael R Sweet
Copyright (c) 2021-2026 by Michael R Sweet

28
doc/pdfio.html
View File

@@ -6,7 +6,7 @@
<meta name="generator" content="codedoc v3.8">
<meta name="author" content="Michael R Sweet">
<meta name="language" content="en-US">
<meta name="copyright" content="Copyright © 2021-2025 by Michael R Sweet">
<meta name="copyright" content="Copyright © 2021-2026 by Michael R Sweet">
<meta name="version" content="1.7.0">
<style type="text/css"><!--
body {
@@ -271,16 +271,16 @@ span.string {
<p><img class="title" src="pdfio-512.png"></p>
<h1 class="title">PDFio Programming Manual v1.7.0</h1>
<p>Michael R Sweet</p>
<p>Copyright © 2021-2025 by Michael R Sweet</p>
<p>Copyright © 2021-2026 by Michael R Sweet</p>
</div>
<div class="contents">
<h2 class="title">Contents</h2>
<ul class="contents">
<li><a href="#introduction">Introduction</a><ul class="subcontents">
<li><a href="#requirements">Requirements</a></li>
<li><a href="#installing-pdfio">Installing PDFio</a></li>
<li><a href="#visual-studio-project">Visual Studio Project</a></li>
<li><a href="#xcode-project">Xcode Project</a></li>
<li><a href="#building-and-installing-pdfio-on-linuxunix">Building and Installing PDFio on Linux/Unix</a></li>
<li><a href="#building-on-windows-with-visual-studio">Building on Windows with Visual Studio</a></li>
<li><a href="#building-on-macos-with-xcode">Building on macOS with Xcode</a></li>
<li><a href="#detecting-pdfio">Detecting PDFio</a></li>
<li><a href="#header-files">Header Files</a></li>
<li><a href="#understanding-pdf-files">Understanding PDF Files</a></li>
@@ -574,11 +574,14 @@ span.string {
</li>
<li><p>libwebp (<a href="https://developers.google.com/speed/webp">https://developers.google.com/speed/webp</a>) 1.0 or later for WebP image support (optional)</p>
</li>
<li><p>ZLIB (<a href="https://www.zlib.net/">https://www.zlib.net/</a>) 1.1 or later</p>
<li><p>ZLIB (<a href="https://www.zlib.net/">https://www.zlib.net/</a>) 1.1 or later for compression support</p>
</li>
</ul>
<p>IDE files for Xcode (macOS/iOS) and Visual Studio (Windows) are also provided.</p>
<h3 class="title" id="installing-pdfio">Installing PDFio</h3>
<p>On a stock Ubuntu install, the following command will install the various prerequisites:</p>
<pre><code>sudo apt-get install build-essential libpng-dev libwebp-dev zlib1g-dev
</code></pre>
<h3 class="title" id="building-and-installing-pdfio-on-linuxunix">Building and Installing PDFio on Linux/Unix</h3>
<p>PDFio comes with a configure script that creates a portable makefile that will work on any POSIX-compliant system with ZLIB installed. To make it, run:</p>
<pre><code>./configure
make
@@ -600,12 +603,15 @@ sudo make install
<p>Other configure options can be found using the <code>--help</code> option:</p>
<pre><code>./configure --help
</code></pre>
<h3 class="title" id="visual-studio-project">Visual Studio Project</h3>
<p>The Visual Studio solution (&quot;pdfio.sln&quot;) is provided for Windows developers and generates both a static library and DLL.</p>
<h3 class="title" id="xcode-project">Xcode Project</h3>
<p>There is also an Xcode project (&quot;pdfio.xcodeproj&quot;) you can use on macOS which generates a static library that will be installed under &quot;/usr/local&quot; with:</p>
<h3 class="title" id="building-on-windows-with-visual-studio">Building on Windows with Visual Studio</h3>
<p>The Visual Studio solution (&quot;pdfio.sln&quot;) is provided for Windows developers and generates the PDFIO1 DLL. You can also use NuGet to install the <code>pdfio_native</code> package.</p>
<p>You can build and run the <code>testpdfio</code> unit tests target from within Visual Studio to verify the functioning of the library.</p>
<h3 class="title" id="building-on-macos-with-xcode">Building on macOS with Xcode</h3>
<p>The Xcode project (<code>pdfio.xcodeproj</code>) is provided for macOS developer which generates a static library that will be installed under &quot;/usr/local&quot;. Run the following command to build and install PDFio on macOS:</p>
<pre><code>sudo xcodebuild install
</code></pre>
<p>Alternately you can add the Xcode project to a workspace and reference the PDFio library target as a dependency in your own project.</p>
<p>You can build and run the <code>testpdfio</code> unit tests target from within Xcode to verify the functioning of the library.</p>
<h3 class="title" id="detecting-pdfio">Detecting PDFio</h3>
<p>PDFio can be detected using the <code>pkg-config</code> command, for example:</p>
<pre><code>if pkg-config --exists pdfio; then

36
doc/pdfio.md
View File

@@ -32,13 +32,18 @@ PDFio requires the following to build the software:
(optional)
- libwebp (<https://developers.google.com/speed/webp>) 1.0 or later for WebP
image support (optional)
- ZLIB (<https://www.zlib.net/>) 1.1 or later
- ZLIB (<https://www.zlib.net/>) 1.1 or later for compression support
IDE files for Xcode (macOS/iOS) and Visual Studio (Windows) are also provided.
On a stock Ubuntu install, the following command will install the various
prerequisites:
Installing PDFio
----------------
sudo apt-get install build-essential libpng-dev libwebp-dev zlib1g-dev
Building and Installing PDFio on Linux/Unix
-------------------------------------------
PDFio comes with a configure script that creates a portable makefile that will
work on any POSIX-compliant system with ZLIB installed. To make it, run:
@@ -70,21 +75,32 @@ Other configure options can be found using the `--help` option:
./configure --help
Visual Studio Project
---------------------
Building on Windows with Visual Studio
--------------------------------------
The Visual Studio solution ("pdfio.sln") is provided for Windows developers and
generates both a static library and DLL.
generates the PDFIO1 DLL. You can also use NuGet to install the `pdfio_native`
package.
You can build and run the `testpdfio` unit tests target from within Visual
Studio to verify the functioning of the library.
Xcode Project
-------------
Building on macOS with Xcode
----------------------------
There is also an Xcode project ("pdfio.xcodeproj") you can use on macOS which
generates a static library that will be installed under "/usr/local" with:
The Xcode project (`pdfio.xcodeproj`) is provided for macOS developer which
generates a static library that will be installed under "/usr/local". Run the
following command to build and install PDFio on macOS:
sudo xcodebuild install
Alternately you can add the Xcode project to a workspace and reference the PDFio
library target as a dependency in your own project.
You can build and run the `testpdfio` unit tests target from within Xcode to
verify the functioning of the library.
Detecting PDFio
---------------

0
test.h → test-internal.h
View File

2
testpdfio.c
View File

@@ -20,7 +20,7 @@
#include "pdfio-private.h"
#include "pdfio-content.h"
#include "test.h"
#include "test-internal.h"
#include <math.h>
#include <locale.h>
#ifndef M_PI