Starting to add some documentation.

docs/getting-started.md

Index: docs/getting-started.md
diff --git a/docs/getting-started.md b/docs/getting-started.md
new file mode 100644
index 0000000000000000000000000000000000000000..72bcc070e84009cb86d1dd9d4814c48a94b300d2
--- /dev/null
+++ b/docs/getting-started.md
@@ -0,0 +1,184 @@
+# Getting Started with PDFium
+
+[TOC]
+
+This guide walks through some examples of using the PDFium library. For an
+example of using PDFium see the [Chromium PDF Plugin][chrome-plugin].
+
+## Prerequisites
+
+You will need the PDFium library on your computer. You can see the
+[README](/README.md) for instructions on getting and installing PDFium.
+
+*** note
+You must compile PDFium without both V8 and XFA support for the examples
+here to work. V8 can be compiled out by providing
+`GYP_DEFINES="pdf_enable_v8=0 pdf_enable_xfa=0" build/gyp_pdfium`.
+
+See the [V8 Getting Started][pdfium-v8] guide for how to
+initialize PDFium when V8 is compiled into the binary.
+***
+
+## PDFium Headers
+
+PDFium's API has been broken up over several headers. You only need to include
+the headers for functionality you use in your application. The full set of
+headers can be found in the [public/ folder of the repository][pdfium-public].
+
+In all cases you'll need to include `fpdfview.h` as it defines the needed
+methods for initialization and destruction of the library.
+
+## Initializing PDFium
+
+The first step to using PDFium is to initialize the library. Having done so,
+you'll need to destroy the library when you're finished. When initializing the
+library you provide the `FPDF_LIBRARY_CONFIG` parameters to
+`FPDF_InitLibraryWithConfig`.
+
+```c
+#include <fpdfview.h>
+
+int main() {
+  FPDF_LIBRARY_CONFIG config;
+  config.version = 2;
+  config.m_pUserFontPaths = NULL;
+  config.m_pIsolate = NULL;
+  config.m_v8EmbedderSlot = 0;
+
+  FPDF_InitLibraryWithConfig(&config);
+
+  FPDF_DestroyLibrary();
+  return 0;
+}
+```
+
+Currently the `config.version` must be set to `2`. `m_pUserFontPaths` can be
+used to override the font paths searched by PDFium. If you wish to use your
+own font paths pass a `NULL` terminated list of `const char*` paths to use.
+
+`m_pIsolate` and `m_v8EmbedderSlot` are both used to configure the V8
+javascript engine. In the first case, you can provide an isolate through
+`m_pIsolate` for PDFium to use to store per-isolate data. Passing `NULL` will
+case PDFium to allocate a new isolate. `m_v8EmbedderSlot` is the embedder data
+slot to use in the v8::Isolate to store PDFium data. The value must be between
+0 and v8::Internals::kNumIsolateDataSlots. Typically, 0 is a good choice.
+
+For more information on using Javascript see the [V8 Getting Started][pdfium-v8]
+guide.
+
+*** aside
+PDFium is built as a set of static libraries. You'll need to specify them all on
+the link line in order to compile. My build line was:
+
+```
+PDF_LIBS="-lpdfium -lfpdfapi -lfxge -lfpdfdoc -lfxcrt -lfx_agg \
+-lfxcodec -lfx_lpng -lfx_libopenjpeg -lfx_lcms2 -lfx_freetype -ljpeg \
+-lfx_zlib -lfdrm -lpdfwindow -lbigint -lformfiller -ljavascript \
+-lfxedit"
+PDF_DIR=<path/to/pdfium>
+
+clang -I $PDF_DIR/public -o init init.c -L $PDF_DIR/out/Debug -lstdc++ -framework AppKit $PDF_LIBS
+```
+
+The `-framework AppKit` as needed as I'm building on a Mac. Internally PDFium
+uses C++, which is why `-lstdc++` is required on the link line.
+***
+
+## Loading a Document

[dsinclair, 2016/03/29 01:55:29]

Added the start of a loading section.

+
+One of the main objects in PDFium is the `FPDF_DOCUMENT`. The object will allow
+access to information from PDFs. There are four ways to to create a
+`FPDF_DOCUMENT`. `FPDF_CreateNewDocument` will create an empty object which
+can be used to create PDFs. For more information see the
+[PDF Editing Guide][pdfium-edit-guide].
+
+Loading an existing document is done in one of three ways, loading from file,

[Tom Sepez, 2016/04/01 00:06:19]

three ways:

[dsinclair, 2016/04/01 13:08:52]

Done.

+loading from memory and a custom loader. In all three cases you'll provide a

[Tom Sepez, 2016/04/01 00:06:19]

memory, or loading via a custom loader.

[dsinclair, 2016/04/01 13:08:52]

Done.

+`FPDF_BYTESTRING` which is the password needed to unlock the PDF, if encrypted.
+If the file is not encrypted the password maybe `NULL`.

[Tom Sepez, 2016/04/01 00:06:19]

can be

[dsinclair, 2016/04/01 13:08:52]

Done.

+
+The two simplest methods are loading from disk and from memory. To load from

[Tom Sepez, 2016/04/01 00:06:19]

"loading from file and loading from memory" 

we said "file" above, not disk, so s/disk/file/ throughout.

[dsinclair, 2016/04/01 13:08:52]

Done.

+disk, provide the file to open, including extension. For loading from memory

[Tom Sepez, 2016/04/01 00:06:19]

file, you'll provide the name of the file

[dsinclair, 2016/04/01 13:08:52]

Done.

+provide the data buffer containing the PDF and the length.

[Tom Sepez, 2016/04/01 00:06:19]

you'll provide a data buffer ... and its length.

[dsinclair, 2016/04/01 13:08:52]

Done.

+
+```c
+FPDF_STRING test_doc = "test_doc.pdf";
+FPDF_DOCUMENT doc = FPDF_LoadDocument(test_doc, NULL);
+if (!doc) {
+  return 1;
+}
+
+FPDF_CloseDocument(doc);
+
+```
+
+In all three cases, `FPDF_LoadDocument`, `FPDF_LoadMemDocument`,
+`FPDF_LoadCustomDocument` a return of `NULL` indicates an error opening the
+document or the file was not found.

[Tom Sepez, 2016/04/01 00:06:20]

or that the file

[dsinclair, 2016/04/01 13:08:52]

Done.

+
+You can use `FPDF_GetLastError` to determine what went wrong.
+
+```c
+#include <fpdfview.h>
+#include <unistd.h>
+#include <stdio.h>
+
+int main() {
+  FPDF_LIBRARY_CONFIG config;
+  config.version = 2;
+  config.m_pUserFontPaths = NULL;
+  config.m_pIsolate = NULL;
+  config.m_v8EmbedderSlot = 0;
+
+  FPDF_InitLibraryWithConfig(&config);
+
+  FPDF_DOCUMENT doc = FPDF_LoadDocument(test_doc, NULL);
+  if (!doc) {
+    unsigned long err = FPDF_GetLastError();
+    fprintf(stderr, "Load pdf docs unsuccessful: ");
+    switch (err) {
+      case FPDF_ERR_SUCCESS:
+        fprintf(stderr, "Success");
+        break;
+      case FPDF_ERR_UNKNOWN:
+        fprintf(stderr, "Unknown error");
+        break;
+      case FPDF_ERR_FILE:
+        fprintf(stderr, "File not found or could not be opened");
+        break;
+      case FPDF_ERR_FORMAT:
+        fprintf(stderr, "File not in PDF format or corrupted");
+        break;
+      case FPDF_ERR_PASSWORD:
+        fprintf(stderr, "Password required or incorrect password");
+        break;
+      case FPDF_ERR_SECURITY:
+        fprintf(stderr, "Unsupported security scheme");
+        break;
+      case FPDF_ERR_PAGE:
+        fprintf(stderr, "Page not found or content error");
+        break;
+      default:
+        fprintf(stderr, "Unknown error %ld", err);
+    }
+    fprintf(stderr, ".\n");
+    goto EXIT;
+  }
+
+  FPDF_CloseDocument(doc);
+EXIT:
+  FPDF_DestroyLibrary();
+  return 0;
+```
+
+The more interesting open is custom loading. Using a custom loader it's possible

[Tom Sepez, 2016/04/01 00:06:19]

While the above are simple, the preferable technique is to use a custom loader. 
This makes it possible to load pieces of the document only as needed

[dsinclair, 2016/04/01 13:08:52]

Done.

+to load the pieces of the document as needed. This is useful for loading
+documents over the network.
+
+
+
+
+[chrome-plugin]: https://chromium.googlesource.com/chromium/src/+/master/pdf/
+[pdfium-public]: https://pdfium.googlesource.com/pdfium/+/master/public/
+[pdfium-v8]: /docs/v8-getting-started.md
+[pdfium-edit-guide]: /docs/pdfium-edit-guide.md