Turn README into README.md and expand it
diff --git a/README b/README
deleted file mode 100644
index dc3c19e..0000000
--- 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 0000000..3da1dc7
--- /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.
