Add 'mutool run' documentation.

7 files changed, 339 insertions, 0 deletions

diff --git a/docs/mutool/examples/create-thumbnail.js b/docs/mutool/examples/create-thumbnail.js
new file mode 100644
index 00000000..cf7a5886
--- /dev/null
+++ b/docs/mutool/examples/create-thumbnail.js
@@ -0,0 +1,19 @@
+// Create a PDF containing thumbnails of pages rendered from another PDF.
+
+var pdf = new PDFDocument()
+
+var subdoc = new Document("pdfref17.pdf")
+
+var resources = { XObject: {} }
+
+var contents = new Buffer()
+for (var i=0; i < 5; ++i) {
+	var pixmap = subdoc.loadPage(1140+i).toPixmap([0.2,0,0,0.2,0,0], DeviceRGB)
+	resources.XObject["Im" + i] = pdf.addImage(new Image(pixmap))
+	contents.writeLine("q 100 0 0 150 " + (50+100*i) + " 50 cm /Im" + i + " Do Q")
+}
+
+var page = pdf.addPage([0,0,100+i*100,250], 0, resources, contents)
+pdf.insertPage(-1, page)
+
+pdf.save("out.pdf")
diff --git a/docs/mutool/examples/draw-device.js b/docs/mutool/examples/draw-device.js
new file mode 100644
index 00000000..4912e956
--- /dev/null
+++ b/docs/mutool/examples/draw-device.js
@@ -0,0 +1,45 @@
+// Use device interface to draw some graphics and save as a PNG.
+
+var font = new Font("Times-Roman");
+var image = new Image("example.png");
+var path, text;
+
+var pixmap = new Pixmap(DeviceRGB, [0,0,500,600]);
+pixmap.clear(255);
+var device = new DrawDevice(pixmap);
+var transform = [2,0,0,2,0,0]
+{
+	text = new Text();
+	{
+		text.showString(font, [16,0,0,-16,100,30], "Hello, world!");
+		text.showString(font, [0,16,16,0,15,100], "Hello, world!");
+	}
+	device.fillText(text, transform, DeviceGray, [0], 1);
+
+	path = new Path();
+	{
+		path.moveTo(10, 10);
+		path.lineTo(90, 10);
+		path.lineTo(90, 90);
+		path.lineTo(10, 90);
+		path.closePath();
+	}
+	device.fillPath(path, false, transform, DeviceRGB, [1,0,0], 1);
+	device.strokePath(path, {dashes:[5,10], lineWidth:3, lineCap:'Round'}, transform, DeviceRGB, [0,0,0], 1);
+
+	path = new Path();
+	{
+		path.moveTo(100,100);
+		path.curveTo(150,100, 200,150, 200,200);
+		path.curveTo(200,300, 0,300, 100,100);
+		path.closePath();
+	}
+	device.clipPath(path, true, transform);
+	{
+		device.fillImage(image, Concat(transform, [300,0,0,300,0,0]), 1);
+	}
+	device.popClip();
+}
+//device.flush();
+
+pixmap.saveAsPNG("out.png");
diff --git a/docs/mutool/examples/draw-document.js b/docs/mutool/examples/draw-document.js
new file mode 100644
index 00000000..1e285ede
--- /dev/null
+++ b/docs/mutool/examples/draw-document.js
@@ -0,0 +1,9 @@
+// Draw all pages in a document and save them as PNG files.
+
+var doc = new Document(argv[1]);
+var n = doc.countPages();
+for (var i = 0; i < n; ++i) {
+	var page = doc.loadPage(i);
+	var pixmap = page.toPixmap(Identity, DeviceRGB);
+	pixmap.saveAsPNG("out" + (i+1) + ".png");
+}
diff --git a/docs/mutool/examples/pdf-create-lowlevel.js b/docs/mutool/examples/pdf-create-lowlevel.js
new file mode 100644
index 00000000..b55e22cf
--- /dev/null
+++ b/docs/mutool/examples/pdf-create-lowlevel.js
@@ -0,0 +1,63 @@
+// Create a PDF from scratch.
+
+// This example creates a new PDF file from scratch, using only the low level APIs.
+// This assumes a basic working knowledge of the PDF file format.
+
+// Create a new empty document with no pages.
+var pdf = new PDFDocument()
+
+// Create and add a font resource.
+var font = pdf.addObject({
+	Type: "Font",
+	Subtype: "Type1",
+	Encoding: "WinAnsiEncoding",
+	BaseFont: "Times-Roman",
+})
+
+// Create and add an image resource:
+// Allocate a slot for a new object and get a reference to it.
+var image = pdf.createObject()
+// Write a dictionary object into the slot.
+image.writeObject({
+	Type: "XObject",
+	Subtype: "Image",
+	Width: 4,
+	Height: 2,
+	BitsPerComponent: 8,
+	ColorSpace: "DeviceGray",
+	// The compression filter to be used:
+	Filter: "ASCIIHexDecode",
+})
+// Write raw stream data into the slot; hex encoded
+// to match the Filter entry in the dictionary.
+image.writeRawStream("004488CCEEBB7733&gt;")
+
+// Create resource dictionary.
+var resources = pdf.addObject({
+	Font: { Tm: font },
+	XObject: { Im0: image },
+})
+
+// Create content stream.
+var buffer = new Buffer()
+buffer.writeLine("10 10 280 330 re s")
+buffer.writeLine("q 200 0 0 200 50 100 cm /Im0 Do Q")
+buffer.writeLine("BT /Tm 16 Tf 50 50 TD (Hello, world!) Tj ET")
+var contents = pdf.addStream(buffer)
+
+// Create page object.
+var page = pdf.addObject({
+	Type: "Page",
+	MediaBox: [0,0,300,350],
+	Contents: contents,
+	Resources: resources,
+})
+
+// Insert page object into page tree.
+var pagetree = pdf.getTrailer().Root.Pages
+pagetree.Count = 1
+pagetree.Kids = [ page ]
+page.Parent = pagetree
+
+// Save the document.
+pdf.save("out.pdf")
diff --git a/docs/mutool/examples/pdf-create.js b/docs/mutool/examples/pdf-create.js
new file mode 100644
index 00000000..38c193a3
--- /dev/null
+++ b/docs/mutool/examples/pdf-create.js
@@ -0,0 +1,35 @@
+// Create a PDF from scratch using helper functions.
+
+// This example creates a new PDF file from scratch, using helper
+// functions to create resources and page objects.
+// This assumes a basic working knowledge of the PDF file format.
+
+// Create a new empty document with no pages.
+var pdf = new PDFDocument()
+
+// Load built-in font and create WinAnsi encoded simple font resource.
+var font = pdf.addSimpleFont(new Font("Times-Roman"))
+
+// Load PNG file and create image resource.
+var image = pdf.addImage(new Image("example.png"))
+
+// Create resource dictionary.
+var resources = pdf.addObject({
+	Font: { Tm: font },
+	XObject: { Im0: image },
+})
+
+// Create content stream data.
+var contents =
+	"10 10 280 330 re s\n" +
+	"q 200 0 0 200 50 100 cm /Im0 Do Q\n" +
+	"BT /Tm 16 Tf 50 50 TD (Hello, world!) Tj ET\n"
+
+// Create a new page object.
+var page = pdf.addPage([0,0,300,350], 0, resources, contents)
+
+// Insert page object at the end of the document.
+pdf.insertPage(-1, page)
+
+// Save the document to file.
+pdf.save("out.pdf")
diff --git a/docs/mutool/examples/pdf-merge.js b/docs/mutool/examples/pdf-merge.js
new file mode 100644
index 00000000..a468738a
--- /dev/null
+++ b/docs/mutool/examples/pdf-merge.js
@@ -0,0 +1,66 @@
+// A re-implementation of "mutool merge" in JavaScript.
+
+function graftObject(dstDoc, srcDoc, srcObj, map) {
+	var srcNum, dstRef, dstObj
+	if (!map)
+		map = []
+	if (srcObj.isIndirect()) {
+		srcNum = srcObj.toIndirect()
+		if (map[srcNum])
+			return map[srcNum]
+		map[srcNum] = dstRef = dstDoc.createObject()
+		dstRef.writeObject(graftObject(dstDoc, srcDoc, srcObj.resolve(), map))
+		if (srcObj.isStream())
+			dstRef.writeRawStream(srcObj.readRawStream())
+		return dstRef
+	}
+	if (srcObj.isArray()) {
+		dstObj = dstDoc.newArray()
+		srcObj.forEach(function (key, val) {
+			dstObj[key] = graftObject(dstDoc, srcDoc, val, map)
+		})
+		return dstObj
+	}
+	if (srcObj.isDictionary()) {
+		dstObj = dstDoc.newDictionary()
+		srcObj.forEach(function (key, val) {
+			dstObj[key] = graftObject(dstDoc, srcDoc, val, map)
+		})
+		return dstObj
+	}
+	return srcObj /* primitive objects are not bound to a document */
+}
+
+function copyPage(dstDoc, srcDoc, pageNumber, map) {
+	var srcPage, dstPage
+	srcPage = srcDoc.findPage(pageNumber)
+	dstPage = dstDoc.newDictionary()
+	if (srcPage.MediaBox) dstPage.MediaBox = graftObject(dstDoc, srcDoc, srcPage.MediaBox, map)
+	if (srcPage.Rotate) dstPage.Rotate = graftObject(dstDoc, srcDoc, srcPage.Rotate, map)
+	if (srcPage.Resources) dstPage.Resources = graftObject(dstDoc, srcDoc, srcPage.Resources, map)
+	if (srcPage.Contents) dstPage.Contents = graftObject(dstDoc, srcDoc, srcPage.Contents, map)
+	dstDoc.insertPage(-1, dstDoc.addObject(dstPage))
+}
+
+function copyAllPages(dstDoc, srcDoc) {
+	var k, n = srcDoc.countPages()
+	var srcMap = []
+	for (k = 0; k < n; ++k)
+		copyPage(dstDoc, srcDoc, k, srcMap)
+}
+
+function pdfmerge() {
+	var srcDoc, dstDoc, i
+
+	dstDoc = new PDFDocument()
+	for (i = 2; i < argv.length; ++i) {
+		srcDoc = new PDFDocument(argv[i])
+		copyAllPages(dstDoc, srcDoc)
+	}
+	dstDoc.save(argv[1])
+}
+
+if (argv.length < 3)
+	print("usage: mutool run pdf-merge.js output.pdf input1.pdf input2.pdf ...")
+else
+	pdfmerge()
diff --git a/docs/mutool/examples/trace-device.js b/docs/mutool/examples/trace-device.js
new file mode 100644
index 00000000..9d7d4373
--- /dev/null
+++ b/docs/mutool/examples/trace-device.js
@@ -0,0 +1,102 @@
+var Q = JSON.stringify
+
+var pathPrinter = {
+	moveTo: function (x,y) { print("moveTo", x, y) },
+	lineTo: function (x,y) { print("lineTo", x, y) },
+	curveTo: function (x1,y1,x2,y2,x3,y3) { print("curveTo", x1, y1, x2, y2, x3 ,y3) },
+	closePath: function () { print("closePath") },
+}
+
+var textPrinter = {
+	showGlyph: function (f,m,g,u,v,b) { print("glyph",f,m,g,u,v,b) },
+}
+
+var traceDevice = {
+	fillPath: function (path, evenOdd, ctm, colorSpace, color, alpha) {
+		print("fillPath", evenOdd, ctm, colorSpace, color, alpha)
+		path.walk(pathPrinter)
+	},
+	clipPath: function (path, evenOdd, ctm) {
+		print("clipPath", evenOdd, ctm)
+		path.walk(pathPrinter)
+	},
+	strokePath: function (path, stroke, ctm, colorSpace, color, alpha) {
+		print("strokePath", Q(stroke), ctm, colorSpace, color, alpha)
+		path.walk(pathPrinter)
+	},
+	clipStrokePath: function (path, stroke, ctm) {
+		print("clipStrokePath", Q(stroke), ctm)
+		path.walk(pathPrinter)
+	},
+
+	fillText: function (text, ctm, colorSpace, color, alpha) {
+		print("fillText", ctm, colorSpace, color, alpha)
+		text.walk(textPrinter)
+	},
+	clipText: function (text, ctm) {
+		print("clipText", ctm)
+		text.walk(textPrinter)
+	},
+	strokeText: function (text, stroke, ctm, colorSpace, color, alpha) {
+		print("strokeText", Q(stroke), ctm, colorSpace, color, alpha)
+		text.walk(textPrinter)
+	},
+	clipStrokeText: function (text, stroke, ctm) {
+		print("clipStrokeText", Q(stroke), ctm)
+		text.walk(textPrinter)
+	},
+	ignoreText: function (text, ctm) {
+		print("ignoreText", ctm)
+		text.walk(textPrinter)
+	},
+
+	fillShade: function (shade, ctm, alpha) {
+		print("fillShade", shade, ctm, alpha)
+	},
+	fillImage: function (image, ctm, alpha) {
+		print("fillImage", image, ctm, alpha)
+	},
+	fillImageMask: function (image, ctm, colorSpace, color, alpha) {
+		print("fillImageMask", image, ctm, colorSpace, color, alpha)
+	},
+	clipImageMask: function (image, ctm) {
+		print("clipImageMask", image, ctm)
+	},
+
+	beginMask: function (area, luminosity, colorspace, color) {
+		print("beginMask", area, luminosity, colorspace, color)
+	},
+	endMask: function () {
+		print("endMask")
+	},
+
+	popClip: function () {
+		print("popClip")
+	},
+
+	beginGroup: function (area, isolated, knockout, blendmode, alpha) {
+		print("beginGroup", area, isolated, knockout, blendmode, alpha)
+	},
+	endGroup: function () {
+		print("endGroup")
+	},
+	beginTile: function (area, view, xstep, ystep, ctm, id) {
+		print("beginTile", area, view, xstep, ystep, ctm, id)
+		return 0
+	},
+	endTile: function () {
+		print("endTile")
+	},
+
+	close: function () {
+		print("close")
+	},
+}
+
+if (argv.length != 3)
+	print("usage: mutool run trace-device.js document.pdf pageNumber")
+else {
+	var doc = new Document(argv[1]);
+	var page = doc.loadPage(parseInt(argv[2])-1);
+	page.run(traceDevice, Identity);
+}