Doc changes with new streaming API

2026-01-25 16:06:44 +00:00 · 2014-03-23 19:48:09 -07:00 · 2014-03-23 19:48:09 -07:00 · 6e1a0da170
commit 6e1a0da170
parent 325096951c
4 changed files with 23 additions and 13 deletions
--- a/docs/getting_started.html
+++ b/docs/getting_started.html
@ -1,4 +1,4 @@
-<!DOCTYPE html><html><head><meta charset="utf-8"><title>Getting Started with PDFKit</title><link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Source+Code+Pro:400,700|Alegreya:700|Merriweather"><link rel="stylesheet" href="/docs/css/index.css"><link rel="stylesheet" href="/docs/css/github.css"></head><body><nav class="sidebar"><ul><li><a href="/">Home</a></li><li><a href="/docs/../index.html">Documentation</a><ul><li><a href="/docs/getting_started.html" class="selected">Getting Started </a><ul><li><a href="#installation">Installation</a></li><li><a href="#creating_a_document">Creating a document</a></li><li><a href="#adding_pages">Adding pages</a></li><li><a href="#setting_document_metadata">Setting document metadata</a></li><li><a href="#adding_content">Adding content</a></li><li><a href="#saving_the_document">Saving the document</a></li></ul></li><li><a href="/docs/vector.html">Vector Graphics </a></li><li><a href="/docs/text.html">Text </a></li><li><a href="/docs/images.html">Images </a></li><li><a href="/docs/annotations.html">Annotations </a></li></ul></li><li><a href="/docs/guide.pdf">PDF Guide</a></li><li><a href="/demo/out.pdf">Example PDF</a></li><li><a href="http://github.com/devongovett/pdfkit">Source Code</a></li></ul></nav><div class="main"><h1 id="getting_started_with_pdfkit">Getting Started with PDFKit</h1>
+<!DOCTYPE html><html><head><meta charset="utf-8"><title>Getting Started with PDFKit</title><link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Source+Code+Pro:400,700|Alegreya:700|Merriweather"><link rel="stylesheet" href="/docs/css/index.css"><link rel="stylesheet" href="/docs/css/github.css"></head><body><nav class="sidebar"><ul><li><a href="/">Home</a></li><li><a href="/docs/../index.html">Documentation</a><ul><li><a href="/docs/getting_started.html" class="selected">Getting Started </a><ul><li><a href="#installation">Installation</a></li><li><a href="#creating_a_document">Creating a document</a></li><li><a href="#adding_pages">Adding pages</a></li><li><a href="#setting_document_metadata">Setting document metadata</a></li><li><a href="#adding_content">Adding content</a></li></ul></li><li><a href="/docs/vector.html">Vector Graphics </a></li><li><a href="/docs/text.html">Text </a></li><li><a href="/docs/images.html">Images </a></li><li><a href="/docs/annotations.html">Annotations </a></li></ul></li><li><a href="/docs/guide.pdf">PDF Guide</a></li><li><a href="/demo/out.pdf">Example PDF</a></li><li><a href="http://github.com/devongovett/pdfkit">Source Code</a></li></ul></nav><div class="main"><h1 id="getting_started_with_pdfkit">Getting Started with PDFKit</h1>

 <h2 id="installation">Installation</h2>

@ -16,6 +16,20 @@ in your CoffeeScript or JavaScript source file and create an instance of the
 <pre><code>PDFDocument = require &#39;pdfkit&#39;
 doc = new PDFDocument</code></pre>

+<p><code>PDFDocument</code> instances are readable Node streams. They don&#39;t get saved anywhere automatically,
+but you can call the <code>pipe</code> method to send the output of the PDF document to another
+writable Node stream as it is being written. When you&#39;re done with your document, call
+the <code>end</code> method to finalize it. Here is an example showing how to pipe to a file or an HTTP response.</p>
+
+<pre><code>doc.pipe fs.createWriteStream(&#39;/path/to/file.pdf&#39;) # write to PDF
+doc.pipe fs.createWriteStream(res)                 # HTTP response
+
+# add stuff to PDF here using methods described below...
+
+doc.end() # finalize the PDF and end the stream</code></pre>
+
+<p>The <code>write</code> and <code>output</code> methods found in PDFKit before version 0.5 are now deprecated.</p>
+
 <h2 id="adding_pages">Adding pages</h2>

 <p>The first page of a PDFKit document is added for you automatically when you
@ -53,8 +67,6 @@ doc.addPage
 doc.addPage
  margins: { top: 50, bottom: 50, left: 72, right: 72 }</code></pre>

-<hr/>
-
 <h2 id="setting_document_metadata">Setting document metadata</h2>

 <p>PDF documents can have various metadata associated with them, such as the
@ -71,16 +83,9 @@ capitalized.</p>
 <h2 id="adding_content">Adding content</h2>

 <p>Once you&#39;ve created a <code>PDFDocument</code> instance, you can add content to the
-document. Check out the other sections to the left under &quot;Documentation&quot; to
+document. Check out the other sections described in this document to
 learn about each type of content you can add.</p>

-<h2 id="saving_the_document">Saving the document</h2>
-
-<p>When you are ready to write the PDF document to a file, just call the <code>write</code>
-method with a filename. If you want to send the document in response to an
-HTTP request, or just need a string representation of the document, just call
-the <code>output</code> method.</p>
-
 <p>That&#39;s the basics! Now let&#39;s move on to PDFKit&#39;s powerful vector graphics
 abilities.</p><nav><a href="/docs/../index.html" class="previous">Previous</a><a href="/docs/vector.html" class="next">Next</a></nav></div><script src="https://ajax.googleapis.com/ajax/libs/jquery/1.6.2/jquery.min.js"></script><script src="/docs/js/scroll.js"></script><script src="/docs/js/highlight.pack.js"></script><script>(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
 (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
--- a/docs/img/3.png
+++ b/docs/img/3.png
--- a/docs/img/4.png
+++ b/docs/img/4.png
--- a/index.html
+++ b/index.html
@ -31,8 +31,13 @@ folder.</p>
 <h2 id="example">Example</h2>

 <pre><code>PDFDocument = require &#39;pdfkit&#39;
+
+# Create a document
 doc = new PDFDocument

+# Pipe it&#39;s output somewhere, like to a file or HTTP response
+doc.pipe fs.createWriteStream(&#39;output.pdf&#39;)
+
 # Embed a font, set the font size, and render some text
 doc.font(&#39;fonts/PalatinoBold.ttf&#39;)
   .fontSize(25)
@ -64,8 +69,8 @@ doc.addPage()
   .underline(100, 100, 160, 27, color: &quot;#0000FF&quot;)
   .link(100, 100, 160, 27, &#39;http://google.com/&#39;)

-# Write the PDF file to disk
-doc.write &#39;output.pdf&#39;</code></pre>
+# Finalize PDF file
+doc.end()</code></pre>

 <p><a href="http://pdfkit.org/demo/out.pdf">The PDF output from this example</a> (with a few additions) shows the power of PDFKit — producing 
 complex documents with a very small amount of code.  For more, see the <code>demo</code> folder and the