From 14d844e4365ec3c3c4d7ad08264aac3ff2807bc9 Mon Sep 17 00:00:00 2001 From: Michael R Sweet Date: Thu, 29 Jan 2026 12:30:10 -0500 Subject: [PATCH] Update documentation. --- CONTRIBUTING.md | 35 +++++++--- EXAMPLES.md | 21 +++--- INSTALL.md | 135 ++++++++++++++++++++++++++++++++++++++ Makefile.in | 4 +- README.md | 100 ++++++---------------------- doc/pdfio.3 | 28 +++++--- doc/pdfio.html | 28 ++++---- doc/pdfio.md | 36 +++++++--- test.h => test-internal.h | 0 testpdfio.c | 2 +- 10 files changed, 255 insertions(+), 134 deletions(-) create mode 100644 INSTALL.md rename test.h => test-internal.h (100%) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 77ca4b3..a7de94a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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. diff --git a/EXAMPLES.md b/EXAMPLES.md index 3607a12..05c1cba 100644 --- a/EXAMPLES.md +++ b/EXAMPLES.md @@ -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. diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 0000000..0b155dd --- /dev/null +++ b/INSTALL.md @@ -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 () 1.6 or later for full PNG image support + (optional) +- libwebp () 1.0 or later for WebP + image support (optional) +- ZLIB () 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. diff --git a/Makefile.in b/Makefile.in index a1e21a8..cf07081 100644 --- a/Makefile.in +++ b/Makefile.in @@ -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 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 diff --git a/README.md b/README.md index fb1a7a8..21df2be 100644 --- a/README.md +++ b/README.md @@ -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 () 1.6 or later for full PNG image support - (optional) -- libwebp () 1.0 or later for WebP - image support (optional) -- ZLIB () 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.* diff --git a/doc/pdfio.3 b/doc/pdfio.3 index f50d35a..d3fb3a9 100644 --- a/doc/pdfio.3 +++ b/doc/pdfio.3 @@ -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 diff --git a/doc/pdfio.html b/doc/pdfio.html index 6a31759..5e2354a 100644 --- a/doc/pdfio.html +++ b/doc/pdfio.html @@ -6,7 +6,7 @@ - +