{"id":15286131,"url":"https://github.com/philterpaper/perl-pdf-builder","last_synced_at":"2025-10-14T11:07:56.529Z","repository":{"id":45398872,"uuid":"92413365","full_name":"PhilterPaper/Perl-PDF-Builder","owner":"PhilterPaper","description":"Extended version of the popular PDF::API2 Perl-based PDF library for creating, reading, and modifying PDF documents","archived":false,"fork":false,"pushed_at":"2025-10-03T17:38:21.000Z","size":71787,"stargazers_count":6,"open_issues_count":60,"forks_count":7,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-10-05T22:46:07.689Z","etag":null,"topics":["pdf","pdf-generation","perl","perl5"],"latest_commit_sha":null,"homepage":"https://www.catskilltech.com/FreeSW/product/PDF%2DBuilder/title/PDF%3A%3ABuilder/freeSW_full","language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PhilterPaper.png","metadata":{"files":{"readme":"README.md","changelog":"Changes","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2017-05-25T14:47:18.000Z","updated_at":"2025-10-03T17:38:25.000Z","dependencies_parsed_at":"2025-02-03T22:22:30.234Z","dependency_job_id":"1518fdfb-5d88-4fa9-add3-3a107d118fa6","html_url":"https://github.com/PhilterPaper/Perl-PDF-Builder","commit_stats":{"total_commits":454,"total_committers":6,"mean_commits":75.66666666666667,"dds":"0.13436123348017626","last_synced_commit":"d2ada70bc50421f7ecad487fccc4a939b56a42df"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/PhilterPaper/Perl-PDF-Builder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PhilterPaper%2FPerl-PDF-Builder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PhilterPaper%2FPerl-PDF-Builder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PhilterPaper%2FPerl-PDF-Builder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PhilterPaper%2FPerl-PDF-Builder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PhilterPaper","download_url":"https://codeload.github.com/PhilterPaper/Perl-PDF-Builder/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PhilterPaper%2FPerl-PDF-Builder/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279019053,"owners_count":26086512,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-14T02:00:06.444Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["pdf","pdf-generation","perl","perl5"],"created_at":"2024-09-30T15:10:42.150Z","updated_at":"2025-10-14T11:07:56.499Z","avatar_url":"https://github.com/PhilterPaper.png","language":"Perl","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PDF::Builder release 3.028\n\nA Perl library to create and modify PDF (Portable Document Format) files\n\n## What is it?\n\nPDF::Builder is a **fork** of the popular PDF::API2\\* Perl library. It\nprovides a library of modules and functions so that a PDF file (document) may\nbe built and maintained from Perl programs (it can also read in, modify, and\nwrite back out existing PDF files). It is not a WYSIWYG editor; nor is it a\ncanned utility or converter. It does _not_ have a GUI or command line interface\n-- it is driven by _your_ Perl program. It is a set of **building blocks**\n(methods) with which you can perform a wide variety of operations, ranging\nfrom basic operations (such as selecting a font face), to defining an entire\npage at a time in the document (using a large subset of either Markdown or HTML\nmarkup languages). You can call it from arbitrary Perl programs, which may even\ncreate content on-the-fly (or read it in from other sources). Quite a few code\nexamples are provided, to help you to get started with the process of creating\na PDF document. Many enhancements are in the pipeline to make PDF::Builder even\nmore powerful and versatile.\n\n\\*Note that PDF::Builder is **not** built on PDF::API2, and does **not**\nrequire that it be installed. The two libraries are completely independent of\neach other and one will not interfere with the other if both are installed.\nHowever, you should _not_ try mixing the two libraries within one running\nprogram, as they still share many routine names!\n\n[Home Page](https://www.catskilltech.com/FreeSW/product/PDF%2DBuilder/title/PDF%3A%3ABuilder/freeSW_full), including Documentation and Examples.\n\n[![Open Issues](https://img.shields.io/github/issues/PhilterPaper/Perl-PDF-Builder)](https://github.com/PhilterPaper/Perl-PDF-Builder/issues)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://makeapullrequest.com)\n[![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://GitHub.com/PhilterPaper/Perl-PDF-Builder/graphs/commit-activity)\n\nThis archive contains the distribution PDF::Builder.\nSee **Changes** file for the version and list of changes from the previous \nrelease.\n\n## Obtaining and Installing the Package\n\nThe installable Perl package may be obtained from\n\"https://metacpan.org/pod/PDF::Builder\", or via a CPAN installer package. If\nyou install this product, only the run-time modules will be installed. Download\nthe full `.tar.gz` file and unpack it (uncompress, then extract directory --\nhint: on Windows, **7-Zip File Manager** is an excellent tool) to get \nutilities, test buckets, example usage, etc.\n\nAlternatively, you can obtain the full source files from\n\"https://github.com/PhilterPaper/Perl-PDF-Builder\", where the ticket list\n(bugs, enhancement requests, etc.) is also kept. Unlike the installable CPAN\nversion, this will have to be manually installed (copy files; there are no XS\ncompiles at this time).\n\nOther than an installer for standard CPAN packages (such as 'cpan' on\nStrawberry Perl for Windows), no other tools or manually-installed prereqs are\nneeded (worst case, you can unpack the `.tar.gz` file and copy files into\nplace yourself!). Currently there are no compiles and links (Perl extensions)\ndone during the install process, only copying of .pm Perl module files. \n\nA package installer such as \"cpan\" (included with Strawberry Perl and some\nother systems) can retrieve the package, unpack and copy files, and run \ninstallation tests without manual intervention. Not only PDF::Builder itself, \nbut any needed prerequisites, may be quickly installed in this manner. Some \nPerl distributions (e.g., ActiveState) may repackage PDF::Builder and \nprerequisites into their own install format, as may Linux distributions such\nas Red Hat or SUSE. Finally, it is possible to copy files directly from the \nGitHub repository to your system, and manually run the \"t\" (installation) \ntests, all without going through a `.tar.gz` CPAN package. There are many \npossibilities.\n\nNote that there are several \"optional\" libraries (Perl modules) used to extend\nand improve PDF::Builder. Read about the list of optional libraries in\nPDF::Builder::Docs, and decide whether or not you want to install any of them.\nBy default, **none** are installed.\n\n## Requirements\n\n### Perl\n\n**Perl 5.28** or higher. It will likely run on somewhat earlier versions, but\nthe CPAN installer may refuse to install it. The reason this version was\nchosen was so that LTS (Long Term Support) versions of Perl going back about\n6 years are officially supported (by PDF::Builder), and older versions are not\nsupported. The intent is to not waste time and effort trying to fix bugs which\nare an artifact of old Perl releases. \n\nUsually about once a year the minimum level is bumped up, but this depends on \nwhether Strawberry releases the newest Perl level. As Strawberry Perl releases \nnew Perl levels, usually on an annual basis, we intend to bump up our required \nminimum Perl level (even-numbered production releases), to keep support for the \nlast 6 calendar years of Perl releases, dropping older ones.\n\n#### Older Perls\n\nIf you MUST install on an older (pre 5.28) Perl, you can try the following for\nStrawberry Perl (Windows). NO PROMISES! Something similar MAY work for other\nOS's and Perl installations:\n\n1. Unpack installation file (`.tar.gz`, via a utility such as 7-Zip) into a directory, and cd to that directory\n1. Edit META.json and change 5.028000 to 5.016000 or whatever level desired\n1. Edit META.yml and change 5.028000 to 5.016000 or whatever level desired\n1. Edit Makefile.PL and change `use 5.028000;` to `use 5.016000;`, change `$PERL_version` from `5.028000` to `5.016000`\n1. `cpan .`\n\nNote that some Perl installers MAY have a means to override or suppress the\nPerl version check. That may be easier to use. Or, you may have to repack the\nedited directory back into a `.tar.gz` installable. YMMV.\n\nIf all goes well, PDF::Builder will be installed on your system. Whether or\nnot it will RUN is another matter. Please do NOT open a bug report (ticket)\nunless you're absolutely sure that the problem is not a result of using an old\nPerl release, e.g., PDF::Builder is using a feature introduced in Perl 5.022\nand you're trying to run Perl 5.012!\n\n### Libraries used\n\nThese libraries are available from CPAN.\n\n#### REQUIRED\n\nThese libraries should be automatically installed...\n\n* Compress::Zlib\n* Font::TTF\n* Test::Exception (needed only for installation tests)\n* Test::Memory::Cycle (needed only for installation tests)\n\n#### OPTIONAL\n\nThese libraries are _recommended_ for improved functionality and performance.\nThe default behavior is **not** to attempt to install them during PDF::Builder\ninstallation, in order to speed up the testing process and not clutter up\nmatters, especially if an optional package fails to install. You can always\nmanually install them later, if you desire to make use of their added\nfunctionality.\n\n* Perl::Critic (1.150 or higher, need if running tools/1\\_pc.pl)\n* Graphics::TIFF (19 or higher, recommended if using TIFF image functions)\n* Image::PNG::Libpng (0.57 or higher, recommended for enhanced PNG image function processing)\n* HarfBuzz::Shaper (0.024 or higher, needed for Latin script ligatures and kerning, as well as for any complex script such as Arabic, Indic scripts, or Khmer)\n* Text::Markdown (1.000031 or higher, needed if using 'md1' markup)\n* HTML::TreeBuilder (5.07 or higher, needed if using 'html' or 'md1' markup)\n* Pod::Simple::XHTML (3.45 or higher, needed if using buildDoc.pl utility to create HTML documentation)\n* SVGPDF (0.087 or higher, needed if using SVG image functions)\n\nIf an optional package is needed for cetain extended functionality, but not\ninstalled, sometimes PDF::Builder\nwill be able to fall back to built-in partial functionality (TIFF and PNG\nimages), but other times will fail. After installing the missing package, you\nmay wish to then run the t-test suite for that library to confirm that it is\nproperly running, as well as running the examples.\n\n**Note** that some of these packages, in turn, make use of various open source\nlibraries (DLLs/shared libs) that you may need to hunt around for, and install\non your system before you can install a given package. That is, they may not\nnecessarily come with your Operating System or Perl installation. Some such\npackages may try to use \"Alien\" to build such prereqs, if missing. Other\npackages are \"pure Perl\" and should install without trouble.\n\n#### Fixes needed to OPTIONAL packages\n\nSometimes fixes or patches are needed for optional prerequisites. See the file\n**INFO/Prereq\\_fixes.md** for a list of known issues.\n\n### External utilities\n\nt/tiff.t (install testing for TIFF support) makes use of GhostScript and \nImageMagick (convert utility). You may need to install these in order to get\nfull testing (tests that need them will be skipped if they are not installed).\nNote that it has been reported that some versions of Mac Perl systems have\na 'convert' utility that is missing the default Arial font, and thus will fail\n(see ticket 223).\n\n## Manually building\n\nAs is the usual practice with building such a package (from the command line),\nthe steps are:\n\n1. perl Makefile.PL\n1. make\n1. make test\n1. make install\n\nIf you have your system configured to run Perl for a .pl/.PL file, you may be\nable to omit \"perl\" from the first command, which creates a Makefile. \"make\"\nis the generic command to run (it feeds on the Makefile produced by\nMakefile.PL), but your system may have it under a different name, such as\ndmake, gmake (e.g., Strawberry Perl on Windows), or nmake.\n\nPDF::Builder does not currently compile and link anything, so `gcc`, `g++`,\netc. will not be used. The build process merely copies .pm files into place,\nand runs the \"t\" tests to confirm the proper installation.\n\n## Copyright\n\nThis software is Copyright (c) 2017-2025 by Phil M. Perry.\n\nPrevious copyrights are held by others (Steve Simms, Alfred Reibenschuh, \net al.). See The HISTORY section of the documentation for more information.\n\nWe would like to acknowledge the efforts and contributions of a number of\nusers of PDF::Builder (and its predecessor, PDF::API2), who have given their\ntime to report issues, ask for new features, and have even contributed code.\nGenerally, you will find their names listed in the Changes and/or issue tickets\nrelated to some particular item. See the **INFO/ACKNOWLEDGE.md** and\n**INFO/SPONSORS** files.\n\n## License\n\nThis is free software, licensed under:\n\n`The GNU Lesser General Public License, Version 2.1, February 1999`\n\nEXCEPT for some files which are explicitly under other, compatible, licenses\n(the Perl License and the MIT License). You are permitted (at your option) to\nredistribute and/or modify this software (those portions under LGPL) at an\nLGPL version greater than 2.1. See INFO/LICENSE for more information on the\nlicenses and warranty statement.\n\n### Carrying On...\n\nPDF::Builder is Open Source software, built upon the efforts not only of the\ncurrent maintainer, but also of many people before me. Therefore, it's perfectly\nfair to make use of the algorithms and even code (within the terms of the\nLICENSE). That's exactly how the State of the\nArt progresses! Just please be considerate and acknowledge the work of others\nthat you are building on, as well as pointing back to this package. Drop us a\nnote with news of your project (if based on the code and algorithms in\nPDF::Builder, or even just heavily inspired by it) and we'll be happy to make\na pointer to _your_ work. The more cross-pollination, the better!\n\n## See Also\n\n* INFO/SUPPORT file for information on reporting bugs, etc. via GitHub Issues\n* INFO/DEPRECATED file for information on deprecated features\n* INFO/KNOWN\\_INCOMP file for known incompatibilities with PDF::API2\n* INFO/Prereq\\_fixes.md possible patches for prerequisites\n* CONTRIBUTING file for how to contribute to the project\n* LICENSE file for more on the license term\n* INFO/RoadMap file for the PDF::Builder road map\n* INFO/ACKNOWLEDGE.md for \"thank yous\" to those who contributed to this product\n* INFO/SPONSORS for \"thank yous\" to those who financially sponsored this product\n* INFO/CONVERSION file for how to convert from PDF::API2 to PDF::Builder\n* INFO/Changes\\* files for older change logs\n* INFO/PATENTS file for information on patents\n\n`INFO/old/` also has some build and test tool files that are not currently used.\n\n## Documentation\n\nTo build the full HTML documentation (all the POD), get the full installation\nand go to the `docs/` directory. Run `buildDoc.pl --all` to generate the full\ntree of documentation. There's a lot of additional information in the\nPDF::Builder::Docs module (it's all documentation).\n\nYou may find it more convenient to point your browser to our\n[Home Page](https://www.catskilltech.com/FreeSW/product/PDF-Builder/title/PDF%3A%3ABuilder/freeSW_full)\nto see the full documentation build (as well as most of the example outputs).\n\nWe admit that the documentation is a bit light on \"how to\" task orientation.\nWe hope to more fully address this in the future, but for now, get the full\ninstallation and look at the `examples/` and `contrib/` directories for sample\ncode that may help you figure out how to do things. The installation tests in\nthe `t/` and `xt/` directories might also be useful to you.\n\n### A Note on Paper Sizes\n\nPer PDF specifications, the default paper (media) size set in PDF::Builder\nis 'US Letter' (8.5in x 11in, 216mm x 279mm). If you're in the civilized world,\nand don't measure things in \"bananas\",\nyou may wish to specify 'A4' instead, in the `$pdf-\u003emediabox('A4');` call.\nNote that A4 is narrower and taller than Letter. If you want to ensure that\nyour output will be printable around the world, consider using the _universal_\npaper size: `$pdf-\u003emediabox('universal');`.\nThis will result in some wasted\nspace at the top of a printed A4 page, or some wasted right margin on a printed\nLetter page, but it's better than having content cut off! It may also be\nsatisfactory to leave sufficient _margins_ around document content on standard\nUS Letter _or_ A4 media, with the following **minimum** margins (allowing\n3mm/.125\" for paper handling, plus extra for media size differences):\n```\nbottom: 3mm = .125\" = 9pt  (bottom same for all media)\nleft:   3mm = .125\" = 9pt  (left same for all media)\n\nA4 top:     21mm = .83\" = 60pt (A4 taller than Letter) \nLetter top: 3mm = .125\" = 9pt\n\nLetter right:  9mm = .375\" = 27pt (Letter wider than A4)\nA4 right:      3mm = .125\" = 9pt\n```\nIf not using the _Universal_ size, you can choose _Letter_ size, with an\nextra-wide right margin of at least 27pt, or _A4_ size media with an extra\ndeep top margin of at least 60pt. In both cases, allow a minimum of 9pt for\nleft and bottom margins, for paper-handling purposes. This should give you\nresults printable on either US Letter or A4 media, anywhere in the world,\nwithout accidentally losing content.\n\nPlease see the discussion on `mediabox()` and other \"box\" calls, about how\nmuch of a page can actually be _printed_ on, allowing for pinch rollers and\nother paper transport mechanisms. The above suggested margins assume, in\naddition to Letter paper being .25\" wider and .7\" shorter than A4, that 1/8\"\n(9pt, 3mm) of paper is unprintable around the edges; your printer may vary.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphilterpaper%2Fperl-pdf-builder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphilterpaper%2Fperl-pdf-builder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphilterpaper%2Fperl-pdf-builder/lists"}