diff options
author | Federico Mena Quintero <federico@gnome.org> | 2019-07-03 20:26:59 +0000 |
---|---|---|
committer | Albert Astals Cid <tsdgeos@yahoo.es> | 2019-07-03 20:26:59 +0000 |
commit | 8d2484c25564b67061031da5c900a8757e30dddc (patch) | |
tree | b53e7baaa60d44295b08e4c915d7b07def06dffc | |
parent | a8dd0a5909c8902881fc382fa52eda462905979d (diff) |
Turn README into README.md and expand it
-rw-r--r-- | README | 39 | ||||
-rw-r--r-- | README.md | 107 |
2 files changed, 107 insertions, 39 deletions
diff --git a/README b/README deleted file mode 100644 index dc3c19ec..00000000 --- a/README +++ /dev/null @@ -1,39 +0,0 @@ -This is poppler, a PDF rendering library. - -Poppler is a fork of the xpdf PDF viewer developed by Derek Noonburg -of Glyph and Cog, LLC. The purpose of forking xpdf is twofold. -First, we want to provide PDF rendering functionality as a shared -library, to centralize the maintenance effort. Today a number of -applications incorporate the xpdf code base, and whenever a security -issue is discovered, all these applications exchange patches and put -out new releases. In turn, all distributions must package and release -new version of these xpdf based viewers. It's safe to say that -there's a lot of duplicated effort with the current situation. Even if -poppler in the short term introduces yet another xpdf derived code -base to the world, we hope that over time these applications will -adopt poppler. After all, we only need one application to use poppler -to break even. - -Second, we would like to move libpoppler forward in a number of areas -that don't fit within the goals of xpdf. By design, xpdf depends on -very few libraries and runs a wide range of X based platforms. This -is a strong feature and reasonable design goal. However, with poppler -we would like to replace parts of xpdf that are now available as -standard components of modern Unix desktop environments. One such -example is fontconfig, which solves the problem of matching and -locating fonts on the system, in a standardized and well understood -way. Another example is cairo, which provides high quality 2D -rendering. See the file TODO for a list of planned changes. - -Please note that xpdf, and thus poppler, is licensed under the GPL, -not the LGPL. Consequently, any application using poppler must also -be licensed under the GPL. If you want to incorporate Xpdf based PDF -rendering in a closed source product, please contact Glyph & Cog -(www.glyphandcog.com) for commercial licensing options. Note that -this only allows you to use xpdf in a closed source product, -not poppler itself. - - Kristian Høgsberg, Feb. 27, 2005 - - -See the README-XPDF for the original xpdf-3.03 README. diff --git a/README.md b/README.md new file mode 100644 index 00000000..3da1dc72 --- /dev/null +++ b/README.md @@ -0,0 +1,107 @@ +Poppler, a PDF rendering library +================================ + +This is Poppler, a library for rendering PDF files, and examining or +modifying their structure. Poppler originally came from the XPDF +sources; please see the file [README-XPDF](README-XPDF) for the +original xpdf-3.03 README. + +Note that **Poppler is licensed under the GPL**, not the LGPL, so +programs which call Poppler must be licensed under the GPL as well. +See the section [History and GPL +licensing](#history-and-gpl-licensing) for more information. + +# Source code + +Poppler's source code is maintained as a Git repository in +[`gitlab.freedesktop.org`][gitlab]. You can fork that repository and +submit merge requests. + +[gitlab]: https://gitlab.freedesktop.org/poppler/poppler + +# Reporting bugs + +Please report bugs at +https://gitlab.freedesktop.org/poppler/poppler/issues + +If you want to report a rendering or parsing bug, or a missing PDF +feature, please provide an example PDF file as an attachment to your +bug report. It really helps if you can minimize the PDF to only the +items required to reproduce the bug or the missing feature, but it is +not absolutely required. **Please be careful** of publishing PDF +files that you don't want other people to see, or files whose +copyright does not allow redistribution; the bug tracker is a public +resource and attachments are visible to everyone. + +# Security + +Poppler is highly sensitive to security bugs, since it deals mainly +with untrusted files downloaded from the Internet. + +If you find a crash in Poppler, or if a tool like +Valgrind/asan/ubsan/msan detect a problem, please report a bug at +https://gitlab.freedesktop.org/poppler/poppler/issues + +# Stable and unstable APIs + +Poppler provides stable, public APIs for its various front-ends, and +an unstable API for Poppler's own internal use. The following +directories in Poppler's source tree have the **stable APIs**: + +* [cpp](cpp) - Stable C++ API for examining the structure of a PDF + file and rendering it to a raster image. + +* [glib](glib) - Stable C API with Glib/GObject idioms, to examine the + structure of a PDF file, and to render its pages to [Cairo] + contexts. + +* [qt5](qt5) - Stable C++ API with [Qt5] idioms, to examine the + structure of a PDF file, and to render its pages to `QPainter` or + `QImage` objects. + +**WARNING:** Poppler also provides direct access to its internals, +since various tools historically use the C++ header files that came +from XPDF and which became the basis for Poppler. + +* [poppler](poppler) - **UNSTABLE, INTERNAL C++ API** to operate + directly on Poppler's internal representation of PDF files. *If you + use this API, you are on your own*. This API may change at any + time, even among minor versions of Poppler! + +[Cairo]: https://www.cairographics.org/ +[Qt5]: https://www.qt.io/ + +# History and GPL licensing + +Poppler is a fork of the xpdf PDF viewer developed by Derek Noonburg +of Glyph and Cog, LLC. The purpose of forking xpdf is twofold. +First, we want to provide PDF rendering functionality as a shared +library, to centralize the maintenance effort. Today a number of +applications incorporate the xpdf code base, and whenever a security +issue is discovered, all these applications exchange patches and put +out new releases. In turn, all distributions must package and release +new version of these xpdf based viewers. It's safe to say that +there's a lot of duplicated effort with the current situation. Even if +poppler in the short term introduces yet another xpdf derived code +base to the world, we hope that over time these applications will +adopt poppler. After all, we only need one application to use poppler +to break even. + +Second, we would like to move libpoppler forward in a number of areas +that don't fit within the goals of xpdf. By design, xpdf depends on +very few libraries and runs a wide range of X based platforms. This +is a strong feature and reasonable design goal. However, with poppler +we would like to replace parts of xpdf that are now available as +standard components of modern Unix desktop environments. One such +example is fontconfig, which solves the problem of matching and +locating fonts on the system, in a standardized and well understood +way. Another example is cairo, which provides high quality 2D +rendering. + +Please note that xpdf, and thus poppler, is licensed under the GPL, +not the LGPL. Consequently, any application using poppler must also +be licensed under the GPL. If you want to incorporate Xpdf based PDF +rendering in a closed source product, please contact Glyph & Cog +(www.glyphandcog.com) for commercial licensing options. Note that +this only allows you to use xpdf in a closed source product, +not poppler itself. |