Commit 8d2484c2 authored by Federico Mena Quintero's avatar Federico Mena Quintero Committed by Albert Astals Cid

Turn README into README.md and expand it

parent a8dd0a59
Pipeline #46469 passed with stages
in 16 minutes and 19 seconds
This is poppler, a PDF rendering library.
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.
......@@ -23,7 +96,7 @@ 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.
rendering.
Please note that xpdf, and thus poppler, is licensed under the GPL,
not the LGPL. Consequently, any application using poppler must also
......@@ -32,8 +105,3 @@ 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.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment