diff options
| author | Tor Andersson <tor.andersson@artifex.com> | 2017-04-07 16:18:53 +0200 |
|---|---|---|
| committer | Tor Andersson <tor.andersson@artifex.com> | 2017-04-13 13:52:16 +0200 |
| commit | c88941abc6f0fe91a41dc35dcaa1874d4de2c429 (patch) | |
| tree | 51ff32d773f80219922a0458ec76f401ba21e138 /docs | |
| parent | 9c805cc9f934cd12e89014db8ad70e3191cdaf2d (diff) | |
| download | mupdf-c88941abc6f0fe91a41dc35dcaa1874d4de2c429.tar.xz | |
Organize docs into HTML files.
Diffstat (limited to 'docs')
27 files changed, 2188 insertions, 515 deletions
diff --git a/docs/android-build-viewer.html b/docs/android-build-viewer.html new file mode 100644 index 00000000..dea1c4fa --- /dev/null +++ b/docs/android-build-viewer.html @@ -0,0 +1,166 @@ +<!DOCTYPE html> +<html> +<head> +<title>How to build the MuPDF viewer for Android</title> +<link rel="stylesheet" href="style.css" type="text/css"> +<meta name="viewport" content="width=device-width, initial-scale=1"> +</head> + +<body> + +<header> +<h1>How to build the MuPDF viewer for Android</h1> +</header> + +<nav> +<a href="http://mupdf.com/index.html">ABOUT</a> +<a href="http://mupdf.com/news.html">NEWS</a> +<a href="index.html">DOCUMENTATION</a> +<a href="http://mupdf.com/downloads/">DOWNLOAD</a> +<a href="http://git.ghostscript.com/?p=mupdf.git;a=summary">SOURCE</a> +<a href="https://bugs.ghostscript.com/">BUGS</a> +</nav> + +<article> + +<h2>Prerequisites</h2> + +<p> +You need a working Android development environment, consisting of the Android +SDK and the Android NDK. The easiest way is to use Android Studio to download +and install the SDK and NDK. Make sure that the Android/Sdk/tools and +Android/Sdk/ndk-bundle directories are on your path. + +<p> +You also need Oracle's Java JDK (OpenJDK is not compatible with Android). +You also need the Apache Ant build system. +You also need Git, GNU Make, and a C compiler. + +<p> +If everything is working, you should be able to run these commands +from the command line: + +<blockquote> + Android SDK tools: android, emulator, and adb.<br> + Android NDK tools: ndk-build.<br> + Oracle Java JDK 8: java, and javac.<br> + Apache Ant: ant.<br> + Git: git.<br> + GNU Make: make, or gmake.<br> + C compiler: cc, gcc, or clang. +</blockquote> + +<h2>Building</h2> + +<p> +Download the project using Git (and don't forget the --recursive flag): + +<pre> +$ git clone --recursive git://git.ghostscript.com/mupdf-android-viewer-mini.git +</pre> + +If all tools have been installed as per the prerequisites, build the app +using make: + +<pre> +$ make +</pre> + +The makefile will take care of setting up the android project and +configuration files. This is of course assuming that you have set +up the pre-requisites properly. + +<h2>Running</h2> + +<p> +To run the app in the android emulator, first you'll need to set up an +"Android Virtual Device" for the emulator. Run "android avd" and create +a new device. You can also use Android Studio to set up a virtual device. +Use the x86 ABI for best emulator performance. + +<p> +Then launch the emulator, or connect a device with USB debugging enabled: + +<pre> +$ emulator -avd MyVirtualDevice & +</pre> + +<p> +Then copy some test files to the device: + +<pre> +$ adb push file.pdf /mnt/sdcard/Download +</pre> + +<p> +Then install the app on the device: + +<pre> +$ make install +</pre> + +<p> +In order to build, install, and launch the app in one step: + +<pre> +$ make run +</pre> + +<p> +To see the error and debugging message log: + +<pre> +$ adb logcat +</pre> + +<h2>Release</h2> + +<p> +To release you <b>MUST</b> first change the package name. +Do <b>NOT</b> use the com.artifex domain for your custom app! + +<pre> +$ mv src/com/artifex src/com/YourCompanyName +</pre> + +<p> +Change all references to com.artifex.mupdf.mini into +com.YourCompanyName.mupdf.mini in the Java source files and XML resources. + +<p> +In order to sign a release build, you will need to create a key and a key store. + +<pre> +$ keytool -genkey -v -keystore android.keystore -alias MyKey \ + -validity 3650 -keysize 2048 -keyalg RSA +</pre> + +<p> +Then add the following entries to local.properties: + +<pre> +key.store=android.keystore +key.store.password=<i>your keystore password</i> +key.alias=MyKey +key.alias.password=<i>your key password</i> +</pre> + +<p> +If your keystore has been set up properly, you can now build a release APK. + +<pre> +$ make release +</pre> + +<p> +Good Luck! + +</article> + +<footer> +<a href="http://artifex.com"><img src="artifex-logo.png" align="right"></a> +Copyright © 2006-2017 Artifex Software Inc. +</footer> + +</body> +</html> diff --git a/docs/artifex-logo.png b/docs/artifex-logo.png Binary files differnew file mode 100644 index 00000000..af610a06 --- /dev/null +++ b/docs/artifex-logo.png diff --git a/docs/building.html b/docs/building.html new file mode 100644 index 00000000..c6ed344d --- /dev/null +++ b/docs/building.html @@ -0,0 +1,113 @@ +<!DOCTYPE html> +<html> +<head> +<title>How to build MuPDF</title> +<link rel="stylesheet" href="style.css" type="text/css"> +<meta name="viewport" content="width=device-width, initial-scale=1"> +</head> + +<body> + +<header> +<h1>How to build MuPDF</h1> +</header> + +<nav> +<a href="http://mupdf.com/index.html">ABOUT</a> +<a href="http://mupdf.com/news.html">NEWS</a> +<a href="index.html">DOCUMENTATION</a> +<a href="http://mupdf.com/downloads/">DOWNLOAD</a> +<a href="http://git.ghostscript.com/?p=mupdf.git;a=summary">SOURCE</a> +<a href="https://bugs.ghostscript.com/">BUGS</a> +</nav> + +<article> + +<h2>License</h2> + +<p> +MuPDF is Copyright (c) 2006-2017 Artifex Software, Inc. + +<p> +This program is free software: you can redistribute it and/or modify it under +the terms of the GNU Affero General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. + +<p> +This program is distributed in the hope that it will be useful, but WITHOUT ANY +WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A +PARTICULAR PURPOSE. See the GNU General Public License for more details. + +<p> +You should have received a copy of the GNU Affero General Public License along +with this program. If not, see <http://www.gnu.org/licenses/>. + +<p> +For commercial licensing, including our "Indie Dev" friendly options, +please contact sales@artifex.com. + +<h2>Download</h2> + +<p> +The latest development source is available directly from the git repository: + +<pre> +git clone --recursive git://git.ghostscript.com/mupdf.git +</pre> + +<p> +In the mupdf directory, update the third party libraries: + +<pre> +git submodule update --init +</pre> + +<h2>Compiling on Windows</h2> + +<p> +On Windows there is a Visual Studio project file in <tt>platform/win32/mupdf.vcproj</tt>. + +<h2>Compiling on Linux</h2> + +<p> +If you are compiling from source you will need several third party libraries: +freetype2, jbig2dec, libjpeg, openjpeg, and zlib. These libraries are contained +in the source archive. If you are using git, they are included as git +submodules. + +<p> +You will also need the X11 headers and libraries if you're building on Linux. +These can typically be found in the xorg-dev package. Alternatively, if you +only want the command line tools, you can build with HAVE_X11=no. + +<p> +The new OpenGL-based viewer also needs OpenGL headers and libraries. If you're +building on Linux, install the mesa-common-dev and libgl1-mesa-dev packages. +You'll also need several X11 development packages: xorg-dev, libxcursor-dev, +libxrandr-dev, and libxinerama-dev. To skip building the OpenGL viewer, build +with HAVE_GLFW=no. + +<p> +To install the viewer, command line tools, libraries, and header files on your system: + +<pre> +make prefix=/usr/local install +</pre> + +<p> +To install only the command line tools, libraries, and headers invoke make like this: + +<pre> +make HAVE_X11=no HAVE_GLFW=no prefix=/usr/local install +</pre> + +</article> + +<footer> +<a href="http://artifex.com"><img src="artifex-logo.png" align="right"></a> +Copyright © 2006-2017 Artifex Software Inc. +</footer> + +</body> +</html> diff --git a/docs/overview.txt b/docs/coding-overview.html index 0a194948..3ab1fff1 100644 --- a/docs/overview.txt +++ b/docs/coding-overview.html @@ -1,246 +1,318 @@ -Contents -======== - -* Basic MuPDF usage example -* Common function arguments -* Error Handling -* Multi-threading -* Cloning the context -* Bound contexts - +<!DOCTYPE html> +<html> +<head> +<title>MuPDF Overview</title> +<link rel="stylesheet" href="style.css" type="text/css"> +<meta name="viewport" content="width=device-width, initial-scale=1"> +</head> + +<body> + +<header> +<h1>MuPDF Overview</h1> +</header> + +<nav> +<a href="http://mupdf.com/index.html">ABOUT</a> +<a href="http://mupdf.com/news.html">NEWS</a> +<a href="index.html">DOCUMENTATION</a> +<a href="http://mupdf.com/downloads/">DOWNLOAD</a> +<a href="http://git.ghostscript.com/?p=mupdf.git;a=summary">SOURCE</a> +<a href="https://bugs.ghostscript.com/">BUGS</a> +</nav> + +<article> + +<h2>Contents</h2> + +<ul> +<li><a href="#basic-mupdf-usage-example">Basic MuPDF usage example</a> +<li><a href="#common-function-arguments">Common function arguments</a> +<li><a href="#error-handling">Error Handling</a> +<li><a href="#multi-threading">Multi-threading</a> +<li><a href="#cloning-the-context">Cloning the context</a> +</ul> + +<h2><a id="basic-mupdf-usage-example"> Basic MuPDF usage example -========================= +</a></h2> +<p> For an example of how to use MuPDF in the most basic way, see -doc/example.c. To limit the complexity and give an easier introduction +<a href="examples/example.c">docs/examples/example.c</a>. +To limit the complexity and give an easier introduction this code has no error handling at all, but any serious piece of code using MuPDF should use the error handling strategies described below. +<h2><a id="common-function-arguments"> Common function arguments -========================= +</a></h2> +<p> Most functions in MuPDF's interface take a context argument. +<p> A context contains global state used by MuPDF inside functions when parsing or rendering pages of the document. It contains for example: - an exception stack (see error handling below), - - a memory allocator (allowing for custom allocators) - - a resource store (for caching of images, fonts, etc.) - - a set of locks and (un-)locking functions (for multi-threading) +<ul> +<li> an exception stack (see error handling below), +<li> a memory allocator (allowing for custom allocators) +<li> a resource store (for caching of images, fonts, etc.) +<li> a set of locks and (un-)locking functions (for multi-threading) +</ul> +<p> Without the set of locks and accompanying functions the context and its proxies may only be used in a single-threaded application. +<h2><a id="error-handling"> Error handling -============== +</a></h2> +<p> MuPDF uses a set of exception handling macros to simplify error return and cleanup. Conceptually, they work a lot like C++'s try/catch system, but do not require any special compiler support. +<p> The basic formulation is as follows: - fz_try(ctx) - { - // Try to perform a task. Never 'return', 'goto' or - // 'longjmp' out of here. 'break' may be used to - // safely exit (just) the try block scope. - } - fz_always(ctx) - { - // Any code here is always executed, regardless of - // whether an exception was thrown within the try or - // not. Never 'return', 'goto' or longjmp out from - // here. 'break' may be used to safely exit (just) the - // always block scope. - } - fz_catch(ctx) - { - // This code is called (after any always block) only - // if something within the fz_try block (including any - // functions it called) threw an exception. The code - // here is expected to handle the exception (maybe - // record/report the error, cleanup any stray state - // etc) and can then either exit the block, or pass on - // the exception to a higher level (enclosing) fz_try - // block (using fz_throw, or fz_rethrow). - } - +<pre> +fz_try(ctx) +{ + // Try to perform a task. Never 'return', 'goto' or + // 'longjmp' out of here. 'break' may be used to + // safely exit (just) the try block scope. +} +fz_always(ctx) +{ + // Any code here is always executed, regardless of + // whether an exception was thrown within the try or + // not. Never 'return', 'goto' or longjmp out from + // here. 'break' may be used to safely exit (just) the + // always block scope. +} +fz_catch(ctx) +{ + // This code is called (after any always block) only + // if something within the fz_try block (including any + // functions it called) threw an exception. The code + // here is expected to handle the exception (maybe + // record/report the error, cleanup any stray state + // etc) and can then either exit the block, or pass on + // the exception to a higher level (enclosing) fz_try + // block (using fz_throw, or fz_rethrow). +} +</pre> + +<p> The fz_always block is optional, and can safely be omitted. +<p> The macro based nature of this system has 3 main limitations: -1) Never return from within try (or 'goto' or longjmp out of it). +<ol> +<li> <p> + Never return from within try (or 'goto' or longjmp out of it). This upsets the internal housekeeping of the macros and will cause problems later on. The code will detect such things happening, but by then it is too late to give a helpful error report as to where the original infraction occurred. -2) The fz_try(ctx) { ... } fz_always(ctx) { ... } fz_catch(ctx) { ... } +<li> <p> + The fz_try(ctx) { ... } fz_always(ctx) { ... } fz_catch(ctx) { ... } is not one atomic C statement. That is to say, if you do: - - if (condition) - fz_try(ctx) { ... } - fz_catch(ctx) { ... } - +<pre> +if (condition) + fz_try(ctx) { ... } + fz_catch(ctx) { ... } +</pre> then you will not get what you want. Use the following instead: - - if (condition) { - fz_try(ctx) { ... } - fz_catch(ctx) { ... } - } - -3) The macros are implemented using setjmp and longjmp, and so +<pre> +if (condition) { + fz_try(ctx) { ... } + fz_catch(ctx) { ... } +} +</pre> + +<li> <p> + The macros are implemented using setjmp and longjmp, and so the standard C restrictions on the use of those functions apply to fz_try/fz_catch too. In particular, any "truly local" variable that is set between the start of fz_try and something in fz_try throwing an exception may become undefined as part of the process of throwing that exception. + <p> As a way of mitigating this problem, we provide a fz_var() macro that tells the compiler to ensure that that variable is not unset by the act of throwing the exception. +</ol> +<p> A model piece of code using these macros then might be: - house build_house(plans *p) - { - material m = NULL; - walls w = NULL; - roof r = NULL; - house h = NULL; - tiles t = make_tiles(); +<pre> +house build_house(plans *p) +{ + material m = NULL; + walls w = NULL; + roof r = NULL; + house h = NULL; + tiles t = make_tiles(); - fz_var(w); - fz_var(r); - fz_var(h); + fz_var(w); + fz_var(r); + fz_var(h); + fz_try(ctx) + { fz_try(ctx) { - fz_try(ctx) - { - m = make_bricks(); - } - fz_catch(ctx) - { - // No bricks available, make do with straw? - m = make_straw(); - } - w = make_walls(m, p); - r = make_roof(m, t); - // Note, NOT: return combine(w,r); - h = combine(w, r); - } - fz_always(ctx) - { - drop_walls(w); - drop_roof(r); - drop_material(m); - drop_tiles(t); + m = make_bricks(); } fz_catch(ctx) { - fz_throw(ctx, "build_house failed"); + // No bricks available, make do with straw? + m = make_straw(); } - return h; + w = make_walls(m, p); + r = make_roof(m, t); + // Note, NOT: return combine(w,r); + h = combine(w, r); } + fz_always(ctx) + { + drop_walls(w); + drop_roof(r); + drop_material(m); + drop_tiles(t); + } + fz_catch(ctx) + { + fz_throw(ctx, "build_house failed"); + } + return h; +} +</pre> +<p> Things to note about this: -a) If make_tiles throws an exception, this will immediately be +<ol> +<li> If make_tiles throws an exception, this will immediately be handled by some higher level exception handler. If it succeeds, t will be set before fz_try starts, so there is no need to fz_var(t); -b) We try first off to make some bricks as our building material. +<li> We try first off to make some bricks as our building material. If this fails, we fall back to straw. If this fails, we'll end up in the fz_catch, and the process will fail neatly. -c) We assume in this code that combine takes new reference to +<li> We assume in this code that combine takes new reference to both the walls and the roof it uses, and therefore that w and r need to be cleaned up in all cases. -d) We assume the standard C convention that it is safe to destroy +<li> We assume the standard C convention that it is safe to destroy NULL things. +</ol> +<h2><a id="multi-threading"> Multi-threading -=============== +</a></h2> -First off, study the basic usage example in doc/example.c and make -sure you understand how it works as the data structures manipulated -there will be refered to in this section too. +<p> +First off, study the basic usage example in +<a href="examples/example.c">docs/examples/example.c</a> +and make sure you understand how it works as the data structures manipulated +there will be referred to in this section too. +<p> MuPDF can usefully be built into a multi-threaded application without the library needing to know anything threading at all. If the library opens a document in one thread, and then sits there as a 'server' requesting pages and rendering them for other threads that need them, then the library is only ever being called from this one thread. +<p> Other threads can still be used to handle UI requests etc, but as far as MuPDF is concerned it is only being used in a single threaded way. In this instance, there are no threading issues with MuPDF at all, and it can safely be used without any locking, as described in the previous sections. +<p> This section will attempt to explain how to use MuPDF in the more complex case; where we genuinely want to call the MuPDF library concurrently from multiple threads within a single application. +<p> MuPDF can be invoked with a user supplied set of locking functions. It uses these to take mutexes around operations that would conflict if performed concurrently in multiple threads. By leaving the exact implementation of locks to the caller MuPDF remains threading library agnostic. +<p> The following simple rules should be followed to ensure that multi-threaded operations run smoothly: -1) "No simultaneous calls to MuPDF in different threads are +<ol> +<li> <p> + "No simultaneous calls to MuPDF in different threads are allowed to use the same context." + <p> Most of the time it is simplest to just use a different context for every thread; just create a new context at the same time as you create the thread. For more details see "Cloning the context" below. -2) "No simultaneous calls to MuPDF in different threads are +<li> <p> + "No simultaneous calls to MuPDF in different threads are allowed to use the same document." + <p> Only one thread can be accessing a document at a time, but once display lists are created from that document, multiple threads at a time can operate on them. + <p> The document can be used from several different threads as long as there are safeguards in place to prevent the usages being simultaneous. -3) "No simultaneous calls to MuPDF in different threads are +<li> <p> + "No simultaneous calls to MuPDF in different threads are allowed to use the same device." + <p> Calling a device simultaneously from different threads will cause it to get confused and may crash. Calling a device from several different threads is perfectly acceptable as long as there are safeguards in place to prevent the calls being simultaneous. +</ol> +<p> So, how does a multi-threaded example differ from a non-multithreaded one? +<p> Firstly, when we create the first context, we call fz_new_context as before, but the second argument should be a pointer to a set of locking functions. +<p> The calling code should provide FZ_LOCK_MAX mutexes, which will be locked/unlocked by MuPDF calling the lock/unlock function pointers in the supplied structure with the user pointer from the structure -and the lock number, i (0 <= i < FZ_LOCK_MAX). These mutexes can +and the lock number, i (0 <= i < FZ_LOCK_MAX). These mutexes can safely be recursive or non-recursive as MuPDF only calls in a non- recursive style. +<p> To make subsequent contexts, the user should NOT call fz_new_context again (as this will fail to share important resources such as the store and glyphcache), but should rather call fz_clone_context. @@ -249,16 +321,19 @@ usual. They will share the important data structures (like store, glyph cache etc) with the original context, but will have their own exception stacks. +<p> To open a document, call fz_open_document as usual, passing a context and a filename. It is important to realise that only one thread at a time can be accessing the documents itself. +<p> This means that only one thread at a time can perform operations such as fetching a page, or rendering that page to a display list. Once a display list has been obtained however, it can be rendered from any other thread (or even from several threads simultaneously, giving banded rendering). +<p> This means that an implementer has 2 basic choices when constructing an application to use MuPDF in multi-threaded mode. Either he can construct it so that a single nominated thread opens the document @@ -267,17 +342,22 @@ to render, or he can add his own mutex around calls to mupdf that use the document. The former is likely to be far more efficient in the long run. -For an example of how to do multi-threading see doc/multi-threaded.c +<p> +For an example of how to do multi-threading see +<a href="examples/multi-threaded.c">docs/examples/multi-threaded.c</a> which has a main thread and one rendering thread per page. +<h2><a id="cloning-the-context"> Cloning the context -=================== +</a></h2> +<p> As described above, every context contains an exception stack which is manipulated during the course of nested fz_try/fz_catches. For obvious reasons the same exception stack cannot be used from more than one thread at a time. +<p> If, however, we simply created a new context (using fz_new_context) for every thread, we would end up with separate stores/glyph caches etc, which is not (generally) what is desired. MuPDF therefore provides a @@ -285,6 +365,17 @@ mechanism for "cloning" a context. This creates a new context that shares everything with the given context, except for the exception stack. +<p> A commonly used general scheme is therefore to create a 'base' context at program start up, and to clone this repeatedly to get new contexts that can be used on new threads. + +</article> + +<footer> +<a href="http://artifex.com"><img src="artifex-logo.png" align="right"></a> +Copyright © 2006-2017 Artifex Software Inc. +</footer> + +</body> +</html> diff --git a/docs/coding-progressive.html b/docs/coding-progressive.html new file mode 100644 index 00000000..fb9ea78d --- /dev/null +++ b/docs/coding-progressive.html @@ -0,0 +1,378 @@ +<!DOCTYPE html> +<html> +<head> +<title>MuPDF Progressive Loading</title> +<link rel="stylesheet" href="style.css" type="text/css"> +<meta name="viewport" content="width=device-width, initial-scale=1"> +</head> + +<body> + +<header> +<h1>MuPDF Progressive Loading</h1> +</header> + +<nav> +<a href="http://mupdf.com/index.html">ABOUT</a> +<a href="http://mupdf.com/news.html">NEWS</a> +<a href="index.html">DOCUMENTATION</a> +<a href="http://mupdf.com/downloads/">DOWNLOAD</a> +<a href="http://git.ghostscript.com/?p=mupdf.git;a=summary">SOURCE</a> +<a href="https://bugs.ghostscript.com/">BUGS</a> +</nav> + +<article> + +<p> +How to do progressive loading with MuPDF. + +<h2>What is progressive loading?</h2> + + +<p> +The idea of progressive loading is that as you download a PDF file +into a browser, you can display the pages as they appear. + +<p> +MuPDF can make use of 2 different mechanisms to achieve this. The +first relies on the file being "linearized", the second relies on +the caller of MuPDF having fine control over the http fetch and on +the server supporting byte-range fetches. + +<p> +For optimum performance a file should be both linearized and be +available over a byte-range supporting link, but benefits can still +be had with either one of these alone. + +<h2>Progressive download using "linearized" files</h2> + +<p> +Adobe defines "linearized" PDFs as being ones that have both a +specific layout of objects and a small amount of extra +information to help avoid seeking within a file. The stated aim +is to deliver the first page of a document in advance of the whole +document downloading, whereupon subsequent pages will become +available. Adobe also refers to these as "Optimized for fast web +view" or "Web Optimized". + +<p> +In fact, the standard outlines (poorly) a mechanism by which 'hints' +can be included that enable the subsequent pages to be found within +the file too. Unfortunately this is very poorly supported with +many tools, and so the hints have to be treated with suspicion. + +<p> +MuPDF will attempt to use hints if they are available, but will also +use a linear search of the file to discover pages if not. This means +that the first page will be displayed quickly, and then subsequent +ones will appear with 'incomplete' renderings that improve over time +as more and more resources are gradually delivered. + +<p> +Essentially the file starts with a slightly modified header, and the +first object in the file is a special one (the linearization object) +that a) indicates that the file is linearized, and b) gives some +useful information (like the number of pages in the file etc). + +<p> +This object is then followed by all the objects required for the +first page, then the "hint stream", then sets of object for each +subsequent page in turn, then shared objects required for those +pages, then various other random things. + +<p> +[Yes, really. While page 1 is sent with all the objects that it +uses, shared or otherwise, subsequent pages do not get shared +resources until after all the unshared page objects have been +sent.] + +<h2>The Hint Stream</h2> + +<p> +Adobe intended Hint Stream to be useful to facilitate the display +of subsequent pages, but it has never used it. Consequently you +can't trust people to write it properly - indeed Adobe outputs +something that doesn't quite conform to the spec. + +<p> +Consequently very few people actually use it. MuPDF will use it +after sanity checking the values, and should cope with illegal/ +incorrect values. + +<h2>So how does MuPDF handle progressive loading?</h2> + +<p> +MuPDF has made various extensions to its mechanisms for handling +progressive loading. + +<ul> + <li> Progressive streams + + <p> + At its lowest level MuPDF reads file data from a fz_stream, + using the fz_open_document_with_stream call. (fz_open_document + is implemented by calling this). We have extended the fz_stream + slightly, giving the system a way to ask for meta information + (or perform meta operations) on a stream. + + <p> + Using this mechanism MuPDF can query: + + <ul> + <li> whether a stream is progressive or not (i.e. whether the + entire stream is accessible immediately) + <li> what the length of a stream should ultimately be (which an + http fetcher should know from the Content-Length header), + </ul> + + <p> + With this information MuPDF can decide whether to use its normal + object reading code, or whether to make use of a linearized + object. Knowing the length enables us to check with the length + value given in the linearized object - if these differ, the + assumption is that an incremental save has taken place, thus the + file is no longer linearized. + + <p> + When data is pulled from a progressive stream, if we attempt to + read data that is not currently available, the stream should + throw a FZ_ERROR_TRYLATER error. This particular error code + will be interpreted by the caller as an indication that it + should retry the parsing of the current objects at a later time. + + <p> + When a MuPDF call is made on a progressive stream, such as + fz_open_document_with_stream, or fz_load_page, the caller should + be prepared to handle a FZ_ERROR_TRYLATER error as meaning that + more data is required before it can continue. No indication is + directly given as to exactly how much more data is required, but + as the caller will be implementing the progressive fz_stream + that it has passed into MuPDF to start with, it can reasonably + be expected to figure out an estimate for itself. + + <li> Cookie + + <p> + Once a page has been loaded, if its contents are to be 'run' + as normal (using e.g. fz_run_page) any error (such as failing + to read a font, or an image, or even a content stream belonging + to the page) will result in a rendering that aborts with an + FZ_ERROR_TRYLATER error. The caller can catch this and display + a placeholder instead. + + <p> + If each pages data was entirely self-contained and sent in + sequence this would perhaps be acceptable, with each page + appearing one after the other. Unfortunately, the linearization + procedure as laid down by Adobe does NOT do this: objects shared + between multiple pages (other than the first) are not sent with + the pages themselves, but rather AFTER all the pages have been + sent. + + <p> + This means that a document that has a title page, then contents + that share a font used on pages 2 onwards, will not be able to + correctly display page 2 until after the font has arrived in + the file, which will not be until all the page data has been + sent. + + <p> + To mitigate against this, MuPDF provides a way whereby callers + can indicate that they are prepared to accept an 'incomplete' + rendering of the file (perhaps with missing images, or with + substitute fonts). + + <p> + Callers prepared to tolerate such renderings should set the + 'incomplete_ok' flag in the cookie, then call fz_run_page etc + as normal. If a FZ_ERROR_TRYLATER error is thrown at any point + during the page rendering, the error will be swallowed, the + 'incomplete' field in the cookie will become non-zero and + rendering will continue. When control returns to the caller + the caller can check the value of the 'incomplete' field and + know that the rendering it received is not authoritative. + +</ul> + +<h2>Progressive loading using byte range requests</h2> + +<p> +If the caller has control over the http fetch, then it is possible +to use byte range requests to fetch the document 'out of order'. +This enables non-linearized files to be progressively displayed as +they download, and fetches complete renderings of pages earlier than +would otherwise be the case. This process requires no changes within +MuPDF itself, but rather in the way the progressive stream learns +from the attempts MuPDF makes to fetch data. + +<p> +Consider for example, an attempt to fetch a hypothetical file from +a server. + +<ul> + <li><p> + The initial http request for the document is sent with a "Range:" + header to pull down the first (say) 4k of the file. + + <li><p> + As soon as we get the header in from this initial request, we can + respond to meta stream operations to give the length, and whether + byte requests are accepted. + + <ul> + <li><p> + If the header indicates that byte ranges are acceptable the + stream proceeds to go into a loop fetching chunks of the file + at a time (not necessarily in-order). Otherwise the server + will ignore the Range: header, and just serve the whole file. + + <li><p> + If the header indicates a content-length, the stream returns + that. + </ul> + + <li><p> + MuPDF can then decide how to proceed based upon these flags and + whether the file is linearized or not. (If the file contains a + linearized object, and the content length matches, then the file + is considered to be linear, otherwise it is not). + + <p> + If the file is linear: + + <ul> + <li><p> + We proceed to read objects out of the file as it downloads. + This will provide us the first page and all its resources. It + will also enable us to read the hint streams (if present). + + <li><p> + Once we have read the hint streams, we unpack (and sanity + check) them to give us a map of where in the file each object + is predicted to live, and which objects are required for each + page. If any of these values are out of range, we treat the + file as if there were no hint streams. + + <li><p> + If we have hints, any attempt to load a subsequent page will + cause MuPDF to attempt to read exactly the objects required. + This will cause a sequence of seeks in the fz_stream followed + by reads. If the stream does not have the data to satisfy that + request yet, the stream code should remember the location that + was fetched (and fetch that block in the background so that + future retries will succeed) and should raise an + FZ_ERROR_TRYLATER error. + + <p> + [Typically therefore when we jump to a page in a linear file + on a byte request capable link, we will quickly see a rough + rendering, which will improve fairly fast as images and fonts + arrive.] + + <li><p> + Regardless of whether we have hints or byte requests, on every + fz_load_page call MuPDF will attempt to process more of the + stream (that is assumed to be being downloaded in the + background). As linearized files are guaranteed to have pages + in order, pages will gradually become available. In the absence + of byte requests and hints however, we have no way of getting + resources early, so the renderings for these pages will remain + incomplete until much more of the file has arrived. + + <p> + [Typically therefore when we jump to a page in a linear file + on a non byte request capable link, we will see a rough + rendering for that page as soon as data arrives for it (which + will typically take much longer than would be the case with + byte range capable downloads), and that will improve much more + slowly as images and fonts may not appear until almost the + whole file has arrived.] + + <li><p> + When the whole file has arrived, then we will attempt to read + the outlines for the file. + </ul> + + <p> + For a non-linearized PDF on a byte request capable stream: + + <ul> + <li><p> + MuPDF will immediately seek to the end of the file to attempt + to read the trailer. This will fail with a FZ_ERROR_TRYLATER + due to the data not being here yet, but the stream code should + remember that this data is required and it should be prioritized + in the background fetch process. + + <li><p> + Repeated attempts to open the stream should eventually succeed + therefore. As MuPDF jumps through the file trying to read first + the xrefs, then the page tree objects, then the page contents + themselves etc, the background fetching process will be driven + by the attempts to read the file in the foreground. + + <p> + [Typically therefore the opening of a non-linearized file will + be slower than a linearized one, as the xrefs/page trees for a + non-linear file can be 20%+ of the file data. Once past this + initial point however, pages and data can be pulled from the + file almost as fast as with a linearized file.] + </ul> + + <p> + For a non-linearized PDF on a non-byte request capable stream: + + <ul> + <li><p> + MuPDF will immediately seek to the end of the file to attempt + to read the trailer. This will fail with a FZ_ERROR_TRYLATER + due to the data not being here yet. Subsequent retries will + continue to fail until the whole file has arrived, whereupon + the whole file will be instantly available. + + <p> + [This is the worst case situation - nothing at all can be + displayed until the entire file has downloaded.] + </ul> + + <p> + A typical structure for a fetcher process (see curl-stream.c in + mupdf-curl as an example) might therefore look like this: + + <ul> + <li><p> + We consider the file as an (initially empty) buffer which we are + filling by making requests. In order to ensure that we make + maximum use of our download link, we ensure that whenever + one request finishes, we immediately launch another. Further, to + avoid the overheads for the request/response headers being too + large, we may want to divide the file into 'chunks', perhaps 4 or 32k + in size. + + <li><p> + We can then have a receiver process that sits there in a loop + requesting chunks to fill this buffer. In the absence of + any other impetus the receiver should request the next 'chunk' + of data from the file that it does not yet have, following the last + fill point. Initially we start the fill point at the beginning of + the file, but this will move around based on the requests made of + the progressive stream. + + <li><p> + Whenever MuPDF attempts to read from the stream, we check to see if + we have data for this area of the file already. If we do, we can + return it. If not, we remember this as the next "fill point" for our + receiver process and throw a FZ_ERROR_TRYLATER error. + </ul> + +</ul> + +</article> + +<footer> +<a href="http://artifex.com"><img src="artifex-logo.png" align="right"></a> +Copyright © 2006-2017 Artifex Software Inc. +</footer> + +</body> +</html> diff --git a/docs/coding-style.html b/docs/coding-style.html new file mode 100644 index 00000000..d9a1602d --- /dev/null +++ b/docs/coding-style.html @@ -0,0 +1,127 @@ +<!DOCTYPE html> +<html> +<head> +<title>MuPDF Coding Style</title> +<link rel="stylesheet" href="style.css" type="text/css"> +<meta name="viewport" content="width=device-width, initial-scale=1"> +</head> + +<body> + +<header> +<h1>MuPDF Coding Style</h1> +</header> + +<nav> +<a href="http://mupdf.com/index.html">ABOUT</a> +<a href="http://mupdf.com/news.html">NEWS</a> +<a href="index.html">DOCUMENTATION</a> +<a href="http://mupdf.com/downloads/">DOWNLOAD</a> +<a href="http://git.ghostscript.com/?p=mupdf.git;a=summary">SOURCE</a> +<a href="https://bugs.ghostscript.com/">BUGS</a> +</nav> + +<article> + +<h2>Names</h2> + +<p> +Functions should be named according to one of the following schemes: + +<ul> +<li> verb_noun +<li> verb_noun_with_noun +<li> noun_attribute +<li> set_noun_attribute +<li> noun_from_noun -- convert from one type to another (avoid noun_to_noun) +</ul> + +<p> +Prefixes are mandatory for exported functions, macros, enums, globals and types. + +<ul> +<li> fz for common code +<li> pdf, xps, etc., for interpreter specific code +</ul> + +<p> +Prefixes are optional (but encouraged) for private functions and types. + +<p> +Avoid using 'get' as this is a meaningless and redundant filler word. + +<p> +These words are reserved for reference counting schemes: + +<ul> +<li> new, find, load, open, keep -- return objects that you are responsible for freeing. + +<li> drop -- relinquish ownership of the object passed in. +</ul> + +<p> +When searching for an object or value, the name used depends on whether +returning the value is passing ownership: + +<ul> +<li> lookup -- return a value or borrowed pointer +<li> find -- return an object that the caller is responsible for freeing +</ul> + +<h2>Types</h2> + +<p> +Various different integer types are used throughout MuPDF. + +<p> +In general: + +<ul> +<li> int is assumed to be 32bit at least. +<li> short is assumed to be exactly 16 bits. +<li> char is assumed to be exactly 8 bits. +<li> array sizes, string lengths, and allocations are measured using size_t. + size_t is 32bit in 32bit builds, and 64bit on all 64bit builds. +<li> buffers of data use unsigned chars (or uint8_t). +<li> Offsets within files/streams are represented using fz_off_t. + fz_off_t is 64bits in 64bit builds, or in 32bit builds with FZ_LARGEFILE defined. + Otherwise it is a native int (so 32bit in 32bit builds). +</ul> + +<p> +In addition, we use floats (and avoid doubles when possible), assumed to be IEEE compliant. + +<h2>Reference counting</h2> + +<p> +Reference counting uses special words in functions to make it easy to remember +and follow the rules. + +<p> +Words that take ownership: new, find, load, open, keep. + +<p> +Words that release ownership: drop. + +<p> +If an object is returned by a function with one of the special words that take +ownership, you are responsible for freeing it by calling "drop" or "free", or +"close" before you return. You may pass ownership of an owned object by return +it only if you name the function using one of the special words. + +<p> +Any objects returned by functions that do not have any of these special words, +are borrowed and have a limited life time. Do not hold on to them past the +duration of the current function, or stow them away inside structs. If you need +to keep the object for longer than that, you have to either "keep" it or make +your own copy. + +</article> + +<footer> +<a href="http://artifex.com"><img src="artifex-logo.png" align="right"></a> +Copyright © 2006-2017 Artifex Software Inc. +</footer> + +</body> +</html> diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 00000000..3a773d21 --- /dev/null +++ b/docs/index.html @@ -0,0 +1,140 @@ +<!DOCTYPE html> +<html> +<head> +<title>MuPDF Documentation</title> +<link rel="stylesheet" href="style.css" type="text/css"> +<meta name="viewport" content="width=device-width, initial-scale=1"> +</head> + +<body> + +<header> +<h1>MuPDF Documentation</h1> +</header> + +<nav> +<a href="http://mupdf.com/index.html">ABOUT</a> +<a href="http://mupdf.com/news.html">NEWS</a> +<a href="index.html">DOCUMENTATION</a> +<a href="http://mupdf.com/downloads/">DOWNLOAD</a> +<a href="http://git.ghostscript.com/?p=mupdf.git;a=summary">SOURCE</a> +<a href="https://bugs.ghostscript.com/">BUGS</a> +</nav> + +<article> + +<p> +MuPDF is an open source software framework for viewing and converting PDF, XPS, and E-book documents. +There are viewers for various platforms, +several command line tools, +and a software library for building tools and applications. + +<h2>Viewers</h2> + +<p> +For Linux and Windows there are two viewers. One is a very basic viewer using x11 and win32, respectively. +It has been supplanted by a newer viewer using OpenGL for rendering, which has more features +such as table of contents, unicode search, etc. +We keep the old viewers around for older systems where OpenGL is not available. + +<p> +Read the <a href="manual-mupdf-gl.html">manual for the new Linux and Windows viewer</a>. + +<p> +Android currently has several different viewers with varying degrees of complexity: + +<dl> +<dt><a href="https://play.google.com/store/apps/details?id=com.artifex.mupdf.mini">MuPDF mini</a> +<dd>A minimal code example of a document viewer. +<dt><a href="https://play.google.com/store/apps/details?id=com.artifex.mupdfdemo">MuPDF demo</a> +<dd>The main app on Google Play. Supports forms and annotations. +<dt>MuPDF NUI +<dd>A viewer that matches the look & feel of SmartOffice. This product is still in early development. +</dl> + +<p> +The iOS viewer is available on the <a href="https://itunes.apple.com/us/app/mupdf/id482941798">App Store</a>. + +<h2>Command Line Tools</h2> + +<p> +The command line tools are all gathered into one umbrella command: mutool. + +<p> +For rendering and converting documents there are two commands available: + +<dl> +<dt><a href="manual-mutool-draw.html">mutool draw</a> +<dd>This is the more customizable tool, but also has a more difficult set of command line options. +It is primarily used for rendering a document to image files. +<dt><a href="manual-mutool-convert.html">mutool convert</a> +<dd>This tool is used for converting documents into other formats, and is easier to use. +</dl> + +<p> +There are also several tools specifically for working with PDF files: + +<dl> +<dt><a href="manual-mutool-show.html">mutool show</a> +<dd>A tool for displaying the internal objects in a PDF file. +<dt><a href="manual-mutool-extract.html">mutool extract</a> +<dd>Extract images and embedded font resources. +<dt><a href="manual-mutool-clean.html">mutool clean</a> +<dd>Rewrite PDF file. Used to fix broken files, or to make a PDF file human editable. +<dt><a href="manual-mutool-merge.html">mutool merge</a> +<dd>Merge pages from multiple input files into a new PDF. +<dt><a href="manual-mutool-create.html">mutool create</a> +<dd>Create a new PDF file from a text file with graphics commands. +<dt><a href="manual-mutool-portfolio.html">mutool portfolio</a> +<dd>Manipulate PDF portfolios. +</dl> + +<p> +And finally, there is a tool for doing anything you can imagine: + +<dl> +<dt><a href="manual-mutool-run.html">mutool run</a> +<dd>A tool for running Javascript programs with access to the MuPDF library functions. +</dl> + +<h2>Library</h2> + +<p> +The library is written in portable C. +<!-- +To learn more about the C interface, read the <a href="book/nav.xhtml">MuPDF Explored</a> book. +The book is also available as a <a href="book.pdf">PDF</a> and <a href="book.epub">EPUB</a> file. +--> + +<ul> +<li><a href="building.html">How to build the library</a>. +<li><a href="coding-overview.html">Overview</a>. +<li><a href="coding-style.html">Coding style</a>. +<li><a href="coding-progressive.html">Progressive loading</a>. +<li><a href="thirdparty.html">List of third party libraries</a>. +</ul> + +<p> +There is also a Java library, which uses JNI to provide access to the C library. +The Java classes provide an interface very similar to that available in the +<a href="manual-mutool-run.html">mutool run</a> command line tool. +This Java library is also how you use MuPDF on Android. + +<p> +If you want to build an application for Android, you have several options. You can base it off one of +the existing viewers, or build a new app using the Java library directly. + +<ul> +<li><a href="android-build-viewer.html">How to build the Android viewer</a>. +<li><a href="android-build-library.html">How to build the Android library</a>. +</ul> + +</article> + +<footer> +<a href="http://artifex.com"><img src="artifex-logo.png" align="right"></a> +Copyright © 2006-2017 Artifex Software Inc. +</footer> + +</body> +</html> diff --git a/docs/man/mupdf.1 b/docs/man/mupdf.1 index d87e54ed..2d2c726f 100644 --- a/docs/man/mupdf.1 +++ b/docs/man/mupdf.1 @@ -162,7 +162,7 @@ Search for text forwards or backwards. Find the next/previous search result. .PP -Miscellanous: +Miscellaneous: .TP .B [, ] Increase/decrease EPUB/XHTML font size. diff --git a/docs/man/mutool.1 b/docs/man/mutool.1 index 33bd0e9e..7f641d68 100644 --- a/docs/man/mutool.1 +++ b/docs/man/mutool.1 @@ -115,7 +115,7 @@ Ignore errors. Low memory mode (avoid caching objects by clearing cache after each page). .TP .B \-P -Run interpretation and rendering at the smae time. +Run interpretation and rendering at the same time. .TP .B pages Comma separated list of page numbers and ranges (for example: 1,5,10-15). @@ -158,7 +158,7 @@ Toggle decompression of font streams. Use in conjunction with -d to leave fonts compressed. .TP .B \-a -ASCII Hex encode binary streams. Use in conjuction with -d and -i or -f to +ASCII Hex encode binary streams. Use in conjunction with -d and -i or -f to ensure that although the images and/or fonts are compressed, the resulting file can still be viewed and edited with a text editor. .TP @@ -368,7 +368,7 @@ See the MuPDF documentation for details about the Javascript interfaces. .SH CONVERT mutool convert [options] file [pages] .PP -The convert commant is used to convert a file from one format to another. +The convert command is used to convert a file from one format to another. .TP .B \-p password Use the specified password if the file is encrypted. diff --git a/docs/manual-mupdf-gl.html b/docs/manual-mupdf-gl.html new file mode 100644 index 00000000..82e37a12 --- /dev/null +++ b/docs/manual-mupdf-gl.html @@ -0,0 +1,121 @@ +<!DOCTYPE html> +<html> +<head> +<title>MuPDF OpenGL Viewer</title> +<link rel="stylesheet" href="style.css" type="text/css"> +<meta name="viewport" content="width=device-width, initial-scale=1"> +</head> + +<body> + +<header> +<h1>MuPDF OpenGL Viewer</h1> +</header> + +<nav> +<a href="http://mupdf.com/index.html">ABOUT</a> +<a href="http://mupdf.com/news.html">NEWS</a> +<a href="index.html">DOCUMENTATION</a> +<a href="http://mupdf.com/downloads/">DOWNLOAD</a> +<a href="http://git.ghostscript.com/?p=mupdf.git;a=summary">SOURCE</a> +<a href="https://bugs.ghostscript.com/">BUGS</a> +</nav> + +<article> + +<p> +The OpenGL based viewer can read PDF, XPS, CBZ, and EPUB documents. +It compiles on any platform that <a href="http://glfw.org/">GLFW</a> supports. +The latest release builds on Linux, Windows, and macOS. + +<h2>Command Line Options</h2> + +<pre> +mupdf-gl [options] document [page] +</pre> + +<dl> +<dt>-p password +<dd>The password needed to open a password protected PDF file. +<dt>-r resolution +<dd>Set the initial zoom level, specified as DPI. The default value is 72. +<dt>-W width +<dd>Set the page width in points for EPUB layout. +<dt>-H height +<dd>Set the page height in points for EPUB layout. +<dt>-S size +<dd>Set the default font size in points for EPUB layout. +<dt>-U stylesheet +<dd>Specify a CSS file containing user styles to load for EPUB layout. +<dt>-X +<dd>Ignore publisher styles for EPUB layout. +</dl> + +<h2>Mouse Bindings</h2> + +<p> +The middle mouse button (scroll wheel button) pans the document view. + +<p> +The right mouse button selects a region and copies the marked text to the clipboard. + +<h2>Key Bindings</h2> + +<p> +Several commands can take a number argument entered before the key, to modify the command. +For example, to zoom to 150 dpi, type "150z". + +<table> +<tr><td>F1<td>Display help. +<tr><td>i<td>Display document metadata. +<tr><td>o<td>Toggle display of outline. +<tr><td>L<td>Toggle display of links. +<tr><td>r<td>Reload document. +<tr><td>q<td>Quit viewer. + +<tr><td> +<tr><td>f<td>Toggle fullscreen. +<tr><td>w<td>Shrinkwrap window to fit page. +<tr><td>W<td>Fit page width to window. +<tr><td>H<td>Fit page height to window. +<tr><td>Z<td>Fit page size to window. +<tr><td>[number] z<td>Set zoom resolution in DPI. +<tr><td>+<td>Zoom in. +<tr><td>-<td>Zoom out. +<tr><td>[<td>Rotate counter-clockwise. +<tr><td>]<td>Rotate clockwise. +<tr><td>[arrows] or h, j, k, l<td>Pan page in small increments. + +<tr><td> +<tr><td>b<td>Smart move one screenful backward. +<tr><td>[space]<td>Smart move one screenful forward. +<tr><td>[comma] or [page up]<td>Go one page backward. +<tr><td>[period] or [page down]<td>Go one page forward. +<tr><td><<td>Go 10 pages backward. +<tr><td>><td>Go 10 pages forward. +<tr><td>[number] g<td>Go to page number. +<tr><td>G<td>Go to last page. + +<tr><td> +<tr><td>m<td>Save current page to navigation history. +<tr><td>t<td>Go back in navigation history. +<tr><td>T<td>Go forward in navigation history. +<tr><td>[number] m<td>Save current page in numbered bookmark. +<tr><td>[number] t<td>Go to numbered bookmark. + +<tr><td> +<tr><td>/<td>Start searching forward. +<tr><td>?<td>Start searching backward. +<tr><td>n<td>Continue searching forward. +<tr><td>N<td>Continue searching backward. +</table> + +</article> + +<footer> +<a href="http://artifex.com"><img src="artifex-logo.png" align="right"></a> +Copyright © 2006-2017 Artifex Software Inc. +</footer> + +</body> +</html> diff --git a/docs/manual-mutool-clean.html b/docs/manual-mutool-clean.html new file mode 100644 index 00000000..bc7989a1 --- /dev/null +++ b/docs/manual-mutool-clean.html @@ -0,0 +1,92 @@ +<!DOCTYPE html> +<html> +<head> +<title>mutool clean</title> +<link rel="stylesheet" href="style.css" type="text/css"> +<meta name="viewport" content="width=device-width, initial-scale=1"> +</head> + +<body> + +<header> +<h1>mutool clean</h1> +</header> + +<nav> +<a href="http://mupdf.com/index.html">ABOUT</a> +<a href="http://mupdf.com/news.html">NEWS</a> +<a href="index.html">DOCUMENTATION</a> +<a href="http://mupdf.com/downloads/">DOWNLOAD</a> +<a href="http://git.ghostscript.com/?p=mupdf.git;a=summary">SOURCE</a> +<a href="https://bugs.ghostscript.com/">BUGS</a> +</nav> + +<article> + +<p> +The clean command pretty prints and rewrites the syntax of a PDF file. +It can be used to repair broken files, expand compressed streams, +filter out a range of pages, etc. + +<pre> +mutool clean [options] input.pdf [output.pdf] [pages] +</pre> + +<p> +If no output file is specified, it will write the cleaned PDF to +"out.pdf" in the current directory. + +<dl> +<dt> -p password +<dd> Use the specified password if the file is encrypted. + +<dt> -g +<dd> Garbage collect objects that have no references from other +objects. Give the option twice to renumber all objects and +compact the cross reference table. Give it three times to merge +and reuse duplicate objects. + +<dt> -s +<dd> Rewrite content streams. + +<dt> -d +<dd> Decompress streams. This will make the output file larger, but +provides easy access for reading and editing the contents with a +text editor. + +<dt> -l +<dd> Linearize output. Create a "Web Optimized" output file. + +<dt> -i +<dd> Toggle decompression of image streams. Use in conjunction with +-d to leave images compressed. + +<dt> -f +<dd> Toggle decompression of font streams. Use in conjunction with -d +to leave fonts compressed. + +<dt> -a +<dd> ASCII Hex encode binary streams. Use in conjunction with -d and +-i or -f to ensure that although the images and/or fonts are +compressed, the resulting file can still be viewed and edited +with a text editor. + +<dt> -z +<dd> Deflate uncompressed streams. If combined with -d, any +decompressed streams will be recompressed. If combined with -a, +the streams will also be hex encoded after compression. + +<dt> pages +<dd> Comma separated list of page numbers and ranges to include. + +</dl> + +</article> + +<footer> +<a href="http://artifex.com"><img src="artifex-logo.png" align="right"></a> +Copyright © 2006-2017 Artifex Software Inc. +</footer> + +</body> +</html> diff --git a/docs/manual-mutool-convert.html b/docs/manual-mutool-convert.html new file mode 100644 index 00000000..692d83d0 --- /dev/null +++ b/docs/manual-mutool-convert.html @@ -0,0 +1,154 @@ +<!DOCTYPE html> +<html> +<head> +<title>mutool convert</title> +<link rel="stylesheet" href="style.css" type="text/css"> +<meta name="viewport" content="width=device-width, initial-scale=1"> +</head> + +<body> + +<header> +<h1>mutool convert</h1> +</header> + +<nav> +<a href="http://mupdf.com/index.html">ABOUT</a> +<a href="http://mupdf.com/news.html">NEWS</a> +<a href="index.html">DOCUMENTATION</a> +<a href="http://mupdf.com/downloads/">DOWNLOAD</a> +<a href="http://git.ghostscript.com/?p=mupdf.git;a=summary">SOURCE</a> +<a href="https://bugs.ghostscript.com/">BUGS</a> +</nav> + +<article> + +<p> +The 'mutool convert' command converts an input file into another format. + +<pre> +mutool convert [options] -o <i>output input</i> [pages] +</pre> + +<p> +The command line options are: + +<dl> +<dt><i>input</i> + <dd>Input file name. + The input can be any of the document formats supported by MuPDF: PDF, XPS, CBZ, unprotected EPUB, FB2, etc. +<dt>[pages] + <dd>Comma separated list of page ranges. The first page is "1", and the last page is "N". The default is "1-N". +<dt>-p <i>password</i> + <dd>Password to use for password protected PDF documents. +</dl> + +<dl> +<dt>-o <i>filename</i> + <dd>The output file name. + The output file name may have a "%d" in the path, which will be replaced with the page number. + If there is no %d, the page number will be appended at the end of the file name for single page formats. +<dt>-F <i>format</i> + <dd>The output format. If missing, it is inferred from the output file name extension. + See below for which formats are supported. +<dt>-O <i>options</i> + <dd>Comma separated list of output options. + The set of available options varies depending on the output format. + See below for details. +</dl> + +<dl> +<dt>-A <i>bits</i> + <dd>Number of bits of anti-aliasing to use (0 to 8) when rendering to image based formats. The default is 8. +<dt>-W <i>width</i> + <dd>Page width in points for EPUB layout. +<dt>-H <i>height</i> + <dd>Page height in points for EPUB layout. +<dt>-S <i>font-size</i> + <dd>Font size in points for EPUB layout. +<dt>-U <i>stylesheet.css</i> + <dd>File name of user style sheet for EPUB layout. +<dt>-X + <dd>Disable document styles for EPUB layout. +</dl> + +<h2> +Image output +</h2> + +<p> +CBZ (comic book zip) is a multi-page image format. + +<p> +The following single page image formats are also supported: PNG, PNM, PAM, TGA, PBM, PKM. +Each page is written to a separate file. + +<p> +The output options (-O flag) for image formats are: + +<dl> +<dt>rotate=<i>N</i> <dd>Rotate rendered pages <i>N</i> degrees counter-clockwise. +<dt>resolution=<i>N</i> <dd>Set both X and Y resolution in pixels per inch. +<dt>x-resolution=<i>N</i> <dd>Set X resolution in pixels per inch. +<dt>y-resolution=<i>N</i> <dd>Set Y resolution in pixels per inch. +<dt>width=<i>N</i> <dd>Render pages to fit <i>N</i> pixels wide (ignore resolution options). +<dt>height=<i>N</i> <dd>Render pages to fit <i>N</i> pixels tall (ignore resolution options). +<dt>colorspace=gray/rgb/cmyk <dd>Render using specified colorspace (if output format supports it). +<dt>alpha <dd>Render pages with an alpha channel and transparent background (if output format supports it). +</dl> + +<h2> +PDF output +</h2> + +<p> +With PDF output, we will create a new PDF file that matches the visual appearance. +The PDF output is still a work in progress, so some features may not work. + +<p> +If the input is PDF, the output will have nothing in common except the visual appearance. +All bookmarks, annotations, forms, etc, will be thrown away. If you want to do a PDF to PDF +conversion, 'mutool clean' is a better tool to use. + +<p> +The PDF output options are: + +<dl> +<dt>decompress <dd> Decompress all streams (except compress-fonts/images). +<dt>compress <dd> Compress all streams. +<dt>compress-fonts <dd> Compress embedded fonts. +<dt>compress-images <dd> Compress images. +<dt>ascii <dd> ASCII hex encode binary streams. +<dt>pretty <dd> Pretty-print objects with indentation. +<dt>linearize <dd> Optimize for web browsers. +<dt>sanitize <dd> Clean up graphics commands in content streams. +<dt>garbage <dd> Garbage collect unused objects. +<dt>garbage=compact <dd> ... and compact cross reference table. +<dt>garbage=deduplicate <dd> ... and remove duplicate objects. +</dl> + +<h2> +SVG output +</h2> + +<p> +SVG output is a single page format, so we will write one SVG file for each input page. + +<p> +The SVG output options are: + +<dl> +<dt>text=text <dd> Emit text as <text> elements (inaccurate fonts). +<dt>text=path <dd> Emit text as <path> elements (accurate fonts). +<dt>no-reuse-images <dd> Do not reuse images using <symbol> definitions. +</dl> + +</article> + +<footer> +<a href="http://artifex.com"><img src="artifex-logo.png" align="right"></a> +Copyright © 2006-2017 Artifex Software Inc. +</footer> + +</body> +</html> diff --git a/docs/manual-mutool-create.html b/docs/manual-mutool-create.html new file mode 100644 index 00000000..0bb29305 --- /dev/null +++ b/docs/manual-mutool-create.html @@ -0,0 +1,127 @@ +<!DOCTYPE html> +<html> +<head> +<title>mutool create</title> +<link rel="stylesheet" href="style.css" type="text/css"> +<meta name="viewport" content="width=device-width, initial-scale=1"> +</head> + +<body> + +<header> +<h1>mutool create</h1> +</header> + +<nav> +<a href="http://mupdf.com/index.html">ABOUT</a> +<a href="http://mupdf.com/news.html">NEWS</a> +<a href="index.html">DOCUMENTATION</a> +<a href="http://mupdf.com/downloads/">DOWNLOAD</a> +<a href="http://git.ghostscript.com/?p=mupdf.git;a=summary">SOURCE</a> +<a href="https://bugs.ghostscript.com/">BUGS</a> +</nav> + +<article> + +<p> +The create command creates a new PDF file with the contents created +from one or more input files containing graphics commands. + +<pre> +mutool create [-o output.pdf] [-O options] page1.txt [page2.txt ...] +</pre> + +<p> +If no output file is specified, it will write the created PDF to "out.pdf" in the current directory. + +<p> +The -O argument is a comma separated list of options for writing the PDF file: + +<dl> +<dt> decompress +<dd> Decompress all object streams. + +<dt> compress +<dd> Compress all object streams. + +<dt> compress-fonts +<dd> Compress object streams for embedded fonts. + +<dt> compress-images +<dd> Compress object streams for images. + +<dt> ascii +<dd> Encode object streams using ASCII hex encoding. + +<dt> pretty +<dd> Pretty-print objects with indentation. + +<dt> linearize +<dd> Optimize document for progressive loading in viewers. + +<dt> sanitize +<dd> Clean up graphics command in content streams. + +<dt> garbage[=compact|deduplicate] +<dd> Garbage collect unused objects. With compact the cross-reference +table will also be compacted. With deduplicate duplicate objects +will also be recombined. +</dl> + +<p> +A page is created for each input file, with the contents of the +file copied into the content stream. Special comments in the +input files are parsed to define the page dimensions and font +and image resources: + +<pre> +%%MediaBox 0 0 500 800 +%%Rotate 90 +%%Font Tm Times-Roman +%%Font Fn0 path/to/font/file.ttf +%%Image Im0 path/to/image.png +</pre> + +<p> +An example input file: + +<pre> +%%MediaBox 0 0 595 842 +%%Font F0 Times-Roman +%%Image I0 logo/mupdf-simplified-logo.png + +% Draw an image. +q +480 0 0 480 50 250 cm +/I0 Do +Q + +% Draw a triangle. +q +1 0 0 rg +50 50 m +100 200 l +200 50 l +f +Q + +% Show some text. +q +0 0 1 rg +BT +/F0 24 Tf +50 760 Td +(Hello, world!) Tj +ET +Q +</pre> + +</article> + +<footer> +<a href="http://artifex.com"><img src="artifex-logo.png" align="right"></a> +Copyright © 2006-2017 Artifex Software Inc. +</footer> + +</body> +</html> diff --git a/docs/manual-mutool-draw.html b/docs/manual-mutool-draw.html new file mode 100644 index 00000000..bdd95170 --- /dev/null +++ b/docs/manual-mutool-draw.html @@ -0,0 +1,149 @@ +<!DOCTYPE html> +<html> +<head> +<title>mutool draw</title> +<link rel="stylesheet" href="style.css" type="text/css"> +<meta name="viewport" content="width=device-width, initial-scale=1"> +</head> + +<body> + +<header> +<h1>mutool draw</h1> +</header> + +<nav> +<a href="http://mupdf.com/index.html">ABOUT</a> +<a href="http://mupdf.com/news.html">NEWS</a> +<a href="index.html">DOCUMENTATION</a> +<a href="http://mupdf.com/downloads/">DOWNLOAD</a> +<a href="http://git.ghostscript.com/?p=mupdf.git;a=summary">SOURCE</a> +<a href="https://bugs.ghostscript.com/">BUGS</a> +</nav> + +<article> + +<p> +The draw command will render a document to image files, convert to +another vector format, or extract the text content. + +<pre> +mutool draw [options] file [pages] +</pre> + +<p> +The supported input document formats are: pdf, xps, cbz, and epub. + +<p> +The supported output image formats are: pbm, pgm, ppm, pam, png, tga, +pwg, pcl and ps. The supported output vector formats are: svg, pdf, +and debug trace (as xml). The supported output text formats are: plain +text, html, and structured text (as xml). + +<p> +Options: + +<dl> +<dt> -p password +<dd> Use the specified password if the file is encrypted. + +<dt> -o output +<dd> The output format is inferred from the output filename. Embed +%d in the name to indicate the page number (for example: +"page%d.png"). Printf modifiers are supported, for example "%03d". If no +output is specified, the output will go to stdout. + +<dt> -F format +<dd> Enforce a specific output format. Only necessary when outputting +to stdout since normally the output filename is used to infer +the output format. + +<dt> -R angle +<dd> Rotate clockwise by given number of degrees. + +<dt> -r resolution +<dd> Render the page at the specified resolution. The default +resolution is 72 dpi. + +<dt> -w width +<dd> Render the page at the specified width (or, if the -r flag is +used, render with a maximum width). + +<dt> -h height +<dd> Render the page at the specified height (or, if the -r flag is +used, render with a maximum height). + +<dt> -f +<dd> Fit exactly; ignore the aspect ratio when matching specified +width/heights. + +<dt> -B bandheight +<dd> Render in banded mode with each band no taller than the given +height. This uses less memory during rendering. Only compatible +with pam, pgm, ppm, pnm and png output formats. Banded rendering +and md5 checksumming may not be used at the same time. + +<dt> -W width +<dd> Page width in points for EPUB layout. + +<dt> -H height +<dd> Page height in points for EPUB layout. + +<dt> -S size +<dd> Font size in points for EPUB layout. + +<dt> -U filename +<dd> User CSS stylesheet for EPUB layout. + +<dt> -c colorspace +<dd> Render in the specified colorspace. Supported colorspaces are: +mono, gray, grayalpha, rgb, rgbalpha, cmyk, cmykalpha. Some +abbreviations are allowed: m, g, ga, rgba, cmyka. The default +is chosen based on the output format. + +<dt> -G gamma +<dd> Apply gamma correction. Some typical values are 0.7 or 1.4 to +thin or darken text rendering. + +<dt> -I +<dd> Invert colors. + +<dt> -s [mft5] +<dd> Show various bits of information: m for glyph cache and total +memory usage, f for page features such as whether the page is +grayscale or color, t for per page rendering times as well +statistics, and 5 for md5 checksums of rendered images that can +be used to check if rendering has changed. + +<dt> -A bits +<dd> Specify how many bits of anti-aliasing to use. The default is 8. + +<dt> -D +<dd> Disable use of display lists. May cause slowdowns, but should +reduce the amount of memory used. + +<dt> -i +<dd> Ignore errors. + +<dt> -L +<dd> Low memory mode (avoid caching objects by clearing cache after each page). + +<dt> -P +<dd> Run interpretation and rendering at the same time. + +<dt> pages +<dd> Comma separated list of page numbers and ranges (for example: +1,5,10-15). If no pages are specified, then all pages will be +rendered. + +</dl> + +</article> + +<footer> +<a href="http://artifex.com"><img src="artifex-logo.png" align="right"></a> +Copyright © 2006-2017 Artifex Software Inc. +</footer> + +</body> +</html> diff --git a/docs/manual-mutool-extract.html b/docs/manual-mutool-extract.html new file mode 100644 index 00000000..dff50e7e --- /dev/null +++ b/docs/manual-mutool-extract.html @@ -0,0 +1,55 @@ +<!DOCTYPE html> +<html> +<head> +<title>mutool extract</title> +<link rel="stylesheet" href="style.css" type="text/css"> +<meta name="viewport" content="width=device-width, initial-scale=1"> +</head> + +<body> + +<header> +<h1>mutool extract</h1> +</header> + +<nav> +<a href="http://mupdf.com/index.html">ABOUT</a> +<a href="http://mupdf.com/news.html">NEWS</a> +<a href="index.html">DOCUMENTATION</a> +<a href="http://mupdf.com/downloads/">DOWNLOAD</a> +<a href="http://git.ghostscript.com/?p=mupdf.git;a=summary">SOURCE</a> +<a href="https://bugs.ghostscript.com/">BUGS</a> +</nav> + +<article> + +<p> +The extract command can be used to extract images and font files from a PDF file. + +<pre> +mutool extract [options] file.pdf [object numbers] +</pre> + +<p> +Options: + +<dl> +<dt> -p password +<dd> Use the specified password if the file is encrypted. +<dt> -r +<dd> Convert images to RGB when extracting them. +</dl> + +<p> +If no object numbers are given on the command line, all images +and fonts will be extracted. + +</article> + +<footer> +<a href="http://artifex.com"><img src="artifex-logo.png" align="right"></a> +Copyright © 2006-2017 Artifex Software Inc. +</footer> + +</body> +</html> diff --git a/docs/manual-mutool-merge.html b/docs/manual-mutool-merge.html new file mode 100644 index 00000000..1c4f3edc --- /dev/null +++ b/docs/manual-mutool-merge.html @@ -0,0 +1,52 @@ +<!DOCTYPE html> +<html> +<head> +<title>mutool merge</title> +<link rel="stylesheet" href="style.css" type="text/css"> +<meta name="viewport" content="width=device-width, initial-scale=1"> +</head> + +<body> + +<header> +<h1>mutool merge</h1> +</header> + +<nav> +<a href="http://mupdf.com/index.html">ABOUT</a> +<a href="http://mupdf.com/news.html">NEWS</a> +<a href="index.html">DOCUMENTATION</a> +<a href="http://mupdf.com/downloads/">DOWNLOAD</a> +<a href="http://git.ghostscript.com/?p=mupdf.git;a=summary">SOURCE</a> +<a href="https://bugs.ghostscript.com/">BUGS</a> +</nav> + +<article> + +<p> +The merge command is used to pick out pages from two or more files and +merge them in order into a new output file. + +<pre> +mutool merge [options] file1 [pages] file2 [pages] ... +</pre> + +<p> +Options: + +<dl> +<dt> -o output +<dd> The output filename. +<dt> -O options +<dd> See <a href="manual-mutool-create.html">mutool create</a> for details on this option. +</dl> + +</article> + +<footer> +<a href="http://artifex.com"><img src="artifex-logo.png" align="right"></a> +Copyright © 2006-2017 Artifex Software Inc. +</footer> + +</body> +</html> diff --git a/docs/manual-mutool-portfolio.html b/docs/manual-mutool-portfolio.html new file mode 100644 index 00000000..d36dd898 --- /dev/null +++ b/docs/manual-mutool-portfolio.html @@ -0,0 +1,68 @@ +<!DOCTYPE html> +<html> +<head> +<title>mutool portfolio</title> +<link rel="stylesheet" href="style.css" type="text/css"> +<meta name="viewport" content="width=device-width, initial-scale=1"> +</head> + +<body> + +<header> +<h1>mutool portfolio</h1> +</header> + +<nav> +<a href="http://mupdf.com/index.html">ABOUT</a> +<a href="http://mupdf.com/news.html">NEWS</a> +<a href="index.html">DOCUMENTATION</a> +<a href="http://mupdf.com/downloads/">DOWNLOAD</a> +<a href="http://git.ghostscript.com/?p=mupdf.git;a=summary">SOURCE</a> +<a href="https://bugs.ghostscript.com/">BUGS</a> +</nav> + +<article> + +<p> +The portfolio tool can list files in, extract files from, and add files to PDF portfolios. + +<pre> +mutool portfolio [options] portfolio.pdf [actions] +</pre> + +<p> +Options are: + +<dl> +<dt> -p password +<dd> password +<dt> -o filename +<dd> output (defaults to input file) +<dt> -O options +<dd> PDF output options (see <a href="manual-mutool-create.html">mutool create</a>) +</dl> + +<p> +Actions are: + +<dl> +<dt> t +<dd> Display a table listing the contents of the portfolio. +<dt> x <i>N file</i> +<dd> Extract <i>Nth</i> entry to <i>file</i>. +<dt> a <i>file name</i> +<dd> Add contents of <i>file</i> as an entry named <i>name</i>. +</dl> + +<p> +For safety, only use ASCII characters in entry names for now. + +</article> + +<footer> +<a href="http://artifex.com"><img src="artifex-logo.png" align="right"></a> +Copyright © 2006-2017 Artifex Software Inc. +</footer> + +</body> +</html> diff --git a/docs/mutool/run.html b/docs/manual-mutool-run.html index 199e8224..596d11a2 100644 --- a/docs/mutool/run.html +++ b/docs/manual-mutool-run.html @@ -2,16 +2,26 @@ <html> <head> <title>mutool run: reference</title> -<style> -body{margin:2em;max-width:50em;line-height:1.4em} -dl,pre{margin-left:2em;} -</style> +<link rel="stylesheet" href="style.css" type="text/css"> +<meta name="viewport" content="width=device-width, initial-scale=1"> </head> + <body> -<h1> -MuPDF from JavaScript -</h1> +<header> +<h1>Calling MuPDF from JavaScript</h1> +</header> + +<nav> +<a href="http://mupdf.com/index.html">ABOUT</a> +<a href="http://mupdf.com/news.html">NEWS</a> +<a href="index.html">DOCUMENTATION</a> +<a href="http://mupdf.com/downloads/">DOWNLOAD</a> +<a href="http://git.ghostscript.com/?p=mupdf.git;a=summary">SOURCE</a> +<a href="https://bugs.ghostscript.com/">BUGS</a> +</nav> + +<article> <p> The 'mutool run' command executes a JavaScript program, which has access to most of the features of the MuPDF library. @@ -97,8 +107,6 @@ only store bytes. <dd>Create a new empty buffer. <dt>readFile(fileName) <dd>Create a new buffer with the contents of a file. -<dt>setUserCSS(userStylesheet, usePublisherStyles) -<dd>Set user styles and whether to use publisher styles when laying out reflowable documents. <dt>Buffer#length <dd>The number of bytes in the buffer. <dt>Buffer#[n] @@ -144,7 +152,7 @@ This matrix is represented in JavaScript as <code>[a,b,c,d,e,f]</code>. <dt>Translate(tx, ty) <dd>Return a translation matrix, short hand for <code>[1,0,0,1,tx,ty]</code>. <dt>Concat(a, b) -<dd>Concatenate matrixes a and b. Bear in mind that matrix multiplication is not commutative. +<dd>Concatenate matrices a and b. Bear in mind that matrix multiplication is not commutative. </dl> <p> @@ -187,6 +195,11 @@ If the object has a 'down' property, it contains an array with all the sub-headi </dl> <dl> +<dt>setUserCSS(userStylesheet, usePublisherStyles) +<dd>Set user styles and whether to use publisher styles when laying out reflowable documents. +</dl> + +<dl> <dt>Page#bound() <dd>Returns a rectangle containing the page dimensions. <dt>Page#run(device, transform, skipAnnotations) @@ -274,7 +287,7 @@ tiles of a page. <dt>new Pixmap(colorspace, bounds, alpha) <dd>Create a new pixmap. The pixel data is <b>not</b> initialized; and will contain garbage. <dt>Pixmap#clear(value) -<dd>Clear the pixels to the specifed value. Pass 255 for white, or undefined for transparent. +<dd>Clear the pixels to the specified value. Pass 255 for white, or undefined for transparent. <dt>Pixmap#bound() <dd>Return the pixmap bounds. <dt>Pixmap#getWidth() @@ -646,6 +659,10 @@ Do NOT mix and match objects from one document with another document! <dd>Add 'obj' to the PDF as a numbered object, and return an indirect reference to it. <dt>PDFDocument#addStream(buffer, object) <dd>Create a stream object with the contents of 'buffer', add it to the PDF, and return an indirect reference to it. If object is defined, it will be used as the stream object dictionary. +<dt>PDFDocument#addRawStream(buffer, object) +<dd>Create a stream object with the contents of 'buffer', add it to the PDF, and return an indirect reference to it. +If object is defined, it will be used as the stream object dictionary. +The buffer must contain already compressed data that matches the Filter and DecodeParms. <dt>PDFDocument#newNull() <dt>PDFDocument#newBoolean(boolean) <dt>PDFDocument#newInteger(number) @@ -720,7 +737,8 @@ are numbered objects. <dd>Update the contents of the stream the indirect reference points to. This will update the Length, Filter and DecodeParms automatically. <dt>PDFObject#writeRawStream(buffer) -<dd>Update the raw, uncompressed, contents of the stream the indirect reference points to. +<dd>Update the contents of the stream the indirect reference points to. +The buffer must contain already compressed data that matches the Filter and DecodeParms. This will update the Length automatically, but leave the Filter and DecodeParms untouched. </dl> @@ -824,7 +842,12 @@ There are several areas in MuPDF that still need bindings to access from JavaScr <li>DocumentWriter </ul> -<p> -Copyright © 2017 Artifex Software +</article> + +<footer> +<a href="http://artifex.com"><img src="artifex-logo.png" align="right"></a> +Copyright © 2006-2017 Artifex Software Inc. +</footer> </body> +</html> diff --git a/docs/manual-mutool-show.html b/docs/manual-mutool-show.html new file mode 100644 index 00000000..2b5b1ddf --- /dev/null +++ b/docs/manual-mutool-show.html @@ -0,0 +1,76 @@ +<!DOCTYPE html> +<html> +<head> +<title>mutool show</title> +<link rel="stylesheet" href="style.css" type="text/css"> +<meta name="viewport" content="width=device-width, initial-scale=1"> +</head> + +<body> + +<header> +<h1>mutool show</h1> +</header> + +<nav> +<a href="http://mupdf.com/index.html">ABOUT</a> +<a href="http://mupdf.com/news.html">NEWS</a> +<a href="index.html">DOCUMENTATION</a> +<a href="http://mupdf.com/downloads/">DOWNLOAD</a> +<a href="http://git.ghostscript.com/?p=mupdf.git;a=summary">SOURCE</a> +<a href="https://bugs.ghostscript.com/">BUGS</a> +</nav> + +<article> + +<p> +The show command will print the specified objects and streams to +stdout. Streams are decoded and non-printable characters are +represented with a period by default. + +<pre> +mutool show [options] file.pdf [object numbers ...] +</pre> + +<p> +Options: + +<dl> +<dt> -p password +<dd> Use the specified password if the file is encrypted. +<dt> -o file +<dd> Write output to file instead of stdout. +<dt> -b +<dd> Print streams as binary data and omit the object header. +<dt> -e +<dd> Print streams in their original encoded (or compressed) form. +</dl> + +<p> +Specify objects by number, or use one of the following special names: + +<dl> +<dt> 'xref' or 'x' +<dd> Print the cross reference table. +<dt> 'trailer' or 't' +<dd> Print the trailer dictionary. +<dt> 'encrypt' or 'e' +<dd> Print the encryption dictionary. +<dt> 'pagetree' or 'p' +<dd> List the object numbers for every page. +<dt> 'grep' or 'g' +<dd> Print all the objects in the file in a compact one-line format +suitable for piping to grep. +<dt> 'outline' or 'o' +<dd> Print the outline (table of contents). +</dl> + +</article> + +<footer> +<a href="http://artifex.com"><img src="artifex-logo.png" align="right"></a> +Copyright © 2006-2017 Artifex Software Inc. +</footer> + +</body> +</html> diff --git a/docs/naming.txt b/docs/naming.txt deleted file mode 100644 index 03ab3e4c..00000000 --- a/docs/naming.txt +++ /dev/null @@ -1,32 +0,0 @@ -Functions should be named according to one of the following schemes: - - verb_noun - verb_noun_with_noun - - noun_attribute - get_noun_attribute -- when the 'noun_attribute' name conflicts with a type - set_noun_attribute - - noun_from_noun -- convert from one type to another (avoid noun_to_noun) - -Prefixes are mandatory for exported functions, macros, enums, globals and types. - - fz for common code - pdf, xps, etc., for interpreter specific code - -Prefixes are optional (but encouraged) for private functions and types. - -Avoid using 'get' as this is a meaningless and redundant filler word. - -These words are reserved for reference counting schemes: - - new, find, load, open, keep -- return objects that you are responsible for freeing. - - drop -- relinquish ownership of the object passed in. - -When searching for an object or value, the name used depends on whether -returning the value is passing ownership: - - lookup -- return a value or borrowed pointer - - find -- return an object that the caller is responsible for freeing diff --git a/docs/progressive.txt b/docs/progressive.txt deleted file mode 100644 index da33f961..00000000 --- a/docs/progressive.txt +++ /dev/null @@ -1,281 +0,0 @@ -How to do progressive loading with MuPDF. -========================================= - -What is progressive loading? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The idea of progressive loading is that as you download a PDF file -into a browser, you can display the pages as they appear. - -MuPDF can make use of 2 different mechanisms to achieve this. The -first relies on the file being "linearized", the second relies on -the caller of MuPDF having fine control over the http fetch and on -the server supporting byte-range fetches. - -For optimum performance a file should be both linearized and be -available over a byte-range supporting link, but benefits can still -be had with either one of these alone. - -Progressive download using "linearized" files -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Adobe defines "linearized" PDFs as being ones that have both a -specific layout of objects and a small amount of extra -information to help avoid seeking within a file. The stated aim -is to deliver the first page of a document in advance of the whole -document downloading, whereupon subsequent pages will become -available. Adobe also refers to these as "Optimized for fast web -view" or "Web Optimized". - -In fact, the standard outlines (poorly) a mechanism by which 'hints' -can be included that enable the subsequent pages to be found within -the file too. Unfortunately this is very poorly supported with -many tools, and so the hints have to be treated with suspicion. - -MuPDF will attempt to use hints if they are available, but will also -use a linear search of the file to discover pages if not. This means -that the first page will be displayed quickly, and then subsequent -ones will appear with 'incomplete' renderings that improve over time -as more and more resources are gradually delivered. - -Essentially the file starts with a slightly modified header, and the -first object in the file is a special one (the linearization object) -that a) indicates that the file is linearized, and b) gives some -useful information (like the number of pages in the file etc). - -This object is then followed by all the objects required for the -first page, then the "hint stream", then sets of object for each -subsequent page in turn, then shared objects required for those -pages, then various other random things. - -[Yes, really. While page 1 is sent with all the objects that it -uses, shared or otherwise, subsequent pages do not get shared -resources until after all the unshared page objects have been -sent.] - -The Hint Stream -~~~~~~~~~~~~~~~ - -Adobe intended Hint Stream to be useful to facilitate the display -of subsequent pages, but it has never used it. Consequently you -can't trust people to write it properly - indeed Adobe outputs -something that doesn't quite conform to the spec. - -Consequently very few people actually use it. MuPDF will use it -after sanity checking the values, and should cope with illegal/ -incorrect values. - -So how does MuPDF handle progressive loading? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -MuPDF has made various extensions to its mechanisms for handling -progressive loading. - - + Progressive streams - - At its lowest level MuPDF reads file data from a fz_stream, - using the fz_open_document_with_stream call. (fz_open_document - is implemented by calling this). We have extended the fz_stream - slightly, giving the system a way to ask for meta information - (or perform meta operations) on a stream. - - Using this mechanism MuPDF can query: - - + whether a stream is progressive or not (i.e. whether the - entire stream is accessible immediately) - + what the length of a stream should ultimately be (which an - http fetcher should know from the Content-Length header), - - With this information MuPDF can decide whether to use its normal - object reading code, or whether to make use of a linearized - object. Knowing the length enables us to check with the length - value given in the linearized object - if these differ, the - assumption is that an incremental save has taken place, thus the - file is no longer linearized. - - When data is pulled from a progressive stream, if we attempt to - read data that is not currently available, the stream should - throw a FZ_ERROR_TRYLATER error. This particular error code - will be interpreted by the caller as an indication that it - should retry the parsing of the current objects at a later time. - - When a MuPDF call is made on a progressive stream, such as - fz_open_document_with_stream, or fz_load_page, the caller should - be prepared to handle a FZ_ERROR_TRYLATER error as meaning that - more data is required before it can continue. No indication is - directly given as to exactly how much more data is required, but - as the caller will be implementing the progressive fz_stream - that it has passed into MuPDF to start with, it can reasonably - be expected to figure out an estimate for itself. - - + Cookie - - Once a page has been loaded, if its contents are to be 'run' - as normal (using e.g. fz_run_page) any error (such as failing - to read a font, or an image, or even a content stream belonging - to the page) will result in a rendering that aborts with an - FZ_ERROR_TRYLATER error. The caller can catch this and display - a placeholder instead. - - If each pages data was entirely self-contained and sent in - sequence this would perhaps be acceptable, with each page - appearing one after the other. Unfortunately, the linearization - procedure as laid down by Adobe does NOT do this: objects shared - between multiple pages (other than the first) are not sent with - the pages themselves, but rather AFTER all the pages have been - sent. - - This means that a document that has a title page, then contents - that share a font used on pages 2 onwards, will not be able to - correctly display page 2 until after the font has arrived in - the file, which will not be until all the page data has been - sent. - - To mitigate against this, MuPDF provides a way whereby callers - can indicate that they are prepared to accept an 'incomplete' - rendering of the file (perhaps with missing images, or with - substitute fonts). - - Callers prepared to tolerate such renderings should set the - 'incomplete_ok' flag in the cookie, then call fz_run_page etc - as normal. If a FZ_ERROR_TRYLATER error is thrown at any point - during the page rendering, the error will be swallowed, the - 'incomplete' field in the cookie will become non-zero and - rendering will continue. When control returns to the caller - the caller can check the value of the 'incomplete' field and - know that the rendering it received is not authoritative. - -Progressive loading using byte range requests -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If the caller has control over the http fetch, then it is possible -to use byte range requests to fetch the document 'out of order'. -This enables non-linearized files to be progressively displayed as -they download, and fetches complete renderings of pages earlier than -would otherwise be the case. This process requires no changes within -MuPDF itself, but rather in the way the progressive stream learns -from the attempts MuPDF makes to fetch data. - -Consider for example, an attempt to fetch a hypothetical file from -a server. - - + The initial http request for the document is sent with a "Range:" - header to pull down the first (say) 4k of the file. - - + As soon as we get the header in from this initial request, we can - respond to meta stream operations to give the length, and whether - byte requests are accepted. - - - If the header indicates that byte ranges are acceptable the - stream proceeds to go into a loop fetching chunks of the file - at a time (not necessarily in-order). Otherwise the server - will ignore the Range: header, and just serve the whole file. - - - If the header indicates a content-length, the stream returns - that. - - + MuPDF can then decide how to proceed based upon these flags and - whether the file is linearized or not. (If the file contains a - linearized object, and the content length matches, then the file - is considered to be linear, otherwise it is not). - - If the file is linear: - - - we proceed to read objects out of the file as it downloads. - This will provide us the first page and all its resources. It - will also enable us to read the hint streams (if present). - - - Once we have read the hint streams, we unpack (and sanity - check) them to give us a map of where in the file each object - is predicted to live, and which objects are required for each - page. If any of these values are out of range, we treat the - file as if there were no hint streams. - - - If we have hints, any attempt to load a subsequent page will - cause MuPDF to attempt to read exactly the objects required. - This will cause a sequence of seeks in the fz_stream followed - by reads. If the stream does not have the data to satisfy that - request yet, the stream code should remember the location that - was fetched (and fetch that block in the background so that - future retries will succeed) and should raise an - FZ_ERROR_TRYLATER error. - - [Typically therefore when we jump to a page in a linear file - on a byte request capable link, we will quickly see a rough - rendering, which will improve fairly fast as images and fonts - arrive.] - - - Regardless of whether we have hints or byte requests, on every - fz_load_page call MuPDF will attempt to process more of the - stream (that is assumed to be being downloaded in the - background). As linearized files are guaranteed to have pages - in order, pages will gradually become available. In the absence - of byte requests and hints however, we have no way of getting - resources early, so the renderings for these pages will remain - incomplete until much more of the file has arrived. - - [Typically therefore when we jump to a page in a linear file - on a non byte request capable link, we will see a rough - rendering for that page as soon as data arrives for it (which - will typically take much longer than would be the case with - byte range capable downloads), and that will improve much more - slowly as images and fonts may not appear until almost the - whole file has arrived.] - - - When the whole file has arrived, then we will attempt to read - the outlines for the file. - - For a non-linearized PDF on a byte request capable stream: - - - MuPDF will immediately seek to the end of the file to attempt - to read the trailer. This will fail with a FZ_ERROR_TRYLATER - due to the data not being here yet, but the stream code should - remember that this data is required and it should be prioritized - in the background fetch process. - - - Repeated attempts to open the stream should eventually succeed - therefore. As MuPDF jumps through the file trying to read first - the xrefs, then the page tree objects, then the page contents - themselves etc, the background fetching process will be driven - by the attempts to read the file in the foreground. - - [Typically therefore the opening of a non-linearized file will - be slower than a linearized one, as the xrefs/page trees for a - non-linear file can be 20%+ of the file data. Once past this - initial point however, pages and data can be pulled from the - file almost as fast as with a linearized file.] - - For a non-linearized PDF on a non-byte request capable stream: - - - MuPDF will immediately seek to the end of the file to attempt - to read the trailer. This will fail with a FZ_ERROR_TRYLATER - due to the data not being here yet. Subsequent retries will - continue to fail until the whole file has arrived, whereupon - the whole file will be instantly available. - - [This is the worst case situation - nothing at all can be - displayed until the entire file has downloaded.] - - A typical structure for a fetcher process (see curl-stream.c in - mupdf-curl as an example) might therefore look like this: - - + We consider the file as an (initially empty) buffer which we are - filling by making requests. In order to ensure that we make - maximum use of our download link, we ensure that whenever - one request finishes, we immediately launch another. Further, to - avoid the overheads for the request/response headers being too - large, we may want to divide the file into 'chunks', perhaps 4 or 32k - in size. - - + We can then have a receiver process that sits there in a loop - requesting chunks to fill this buffer. In the absence of - any other impetus the receiver should request the next 'chunk' - of data from the file that it does not yet have, following the last - fill point. Initially we start the fill point at the beginning of - the file, but this will move around based on the requests made of - the progressive stream. - - + Whenever MuPDF attempts to read from the stream, we check to see if - we have data for this area of the file already. If we do, we can - return it. If not, we remember this as the next "fill point" for our - receiver process and throw a FZ_ERROR_TRYLATER error. diff --git a/docs/refcount.txt b/docs/refcount.txt deleted file mode 100644 index e575142a..00000000 --- a/docs/refcount.txt +++ /dev/null @@ -1,17 +0,0 @@ -Reference counting uses special words in functions to make it easy to remember -and follow the rules. - -Words that take ownership: new, find, load, open, keep. - -Words that release ownership: drop, free, close. - -If an object is returned by a function with one of the special words that take -ownership, you are responsible for freeing it by calling "drop" or "free", or -"close" before you return. You may pass ownership of an owned object by return -it only if you name the function using one of the special words. - -Any objects returned by functions that do not have any of these special words, -are borrowed and have a limited life time. Do not hold on to them past the -duration of the current function, or stow them away inside structs. If you need -to keep the object for longer than that, you have to either "keep" it or make -your own copy. diff --git a/docs/style.css b/docs/style.css new file mode 100644 index 00000000..a11c4915 --- /dev/null +++ b/docs/style.css @@ -0,0 +1,33 @@ +h1, nav, footer { font-family: sans-serif; } + +a { text-decoration: none; } +a:hover { text-decoration: underline; } +h2 { font-size: 1.25rem; } +h3 { font-size: 1.25rem; } +ul li { list-style-type: circle; } +pre, table, ol, dl { margin-left: 2rem; } +li { margin: 0; } +th, td { text-align: left; vertical-align: top; } + +body { margin: 0; } +h1 { + font-weight: normal; + margin: 0; + padding: 1rem 2rem; + background-color: black; + color: white; +} +nav { + padding: 1rem 2rem; + background-color: #ddd; +} +nav a { color: #303030; padding-right: 2rem; } +article { + max-width: 50rem; + margin: 2rem; +} +footer { + background-color: #ddd; + color: #303030; + padding: 1rem 2rem; +} diff --git a/docs/template.html b/docs/template.html new file mode 100644 index 00000000..57891821 --- /dev/null +++ b/docs/template.html @@ -0,0 +1,37 @@ +<!DOCTYPE html> +<html> +<head> +<title>TITLE</title> +<link rel="stylesheet" href="style.css" type="text/css"> +<meta name="viewport" content="width=device-width, initial-scale=1"> +</head> + +<body> + +<header> +<h1>TITLE</h1> +</header> + +<nav> +<a href="http://mupdf.com/index.html">ABOUT</a> +<a href="http://mupdf.com/news.html">NEWS</a> +<a href="index.html">DOCUMENTATION</a> +<a href="http://mupdf.com/downloads/">DOWNLOAD</a> +<a href="http://git.ghostscript.com/?p=mupdf.git;a=summary">SOURCE</a> +<a href="https://bugs.ghostscript.com/">BUGS</a> +</nav> + +<article> + +<p> +CONTENT + +</article> + +<footer> +<a href="http://artifex.com"><img src="artifex-logo.png" align="right"></a> +Copyright © 2006-2017 Artifex Software Inc. +</footer> + +</body> +</html> diff --git a/docs/thirdparty.html b/docs/thirdparty.html new file mode 100644 index 00000000..fa6644a3 --- /dev/null +++ b/docs/thirdparty.html @@ -0,0 +1,61 @@ +<!DOCTYPE html> +<html> +<head> +<title>Third party libraries used by MuPDF</title> +<link rel="stylesheet" href="style.css" type="text/css"> +<meta name="viewport" content="width=device-width, initial-scale=1"> +</head> + +<body> + +<header> +<h1>Third party libraries used by MuPDF</h1> +</header> + +<nav> +<a href="http://mupdf.com/index.html">ABOUT</a> +<a href="http://mupdf.com/news.html">NEWS</a> +<a href="index.html">DOCUMENTATION</a> +<a href="http://mupdf.com/downloads/">DOWNLOAD</a> +<a href="http://git.ghostscript.com/?p=mupdf.git;a=summary">SOURCE</a> +<a href="https://bugs.ghostscript.com/">BUGS</a> +</nav> + +<article> + +<p> +These are the third party libraries used by MuPDF. + +<table width="100%"> +<tr><th>Library <th>Version <th>Function <th>License + +<tr><td><i>Required:</i> +<tr><td><a href="http://www.freetype.org/">freetype</a><td>2.6.3<td>Font scaling and rendering <td>BSD-style +<tr><td><a href="http://www.harfbuzz.org/">harfbuzz</a><td>1.3.2 with patches <td>Text shaping <td>MIT-style +<tr><td><a href="http://www.ijg.org/">libjpeg</a><td>9.0 with patches <td>JPEG decoding <td>BSD-style +<tr><td><a href="http://www.openjpeg.org/">openjpeg</a><td>2.1.0 with patches <td>JPEG 2000 decoding <td>BSD-style +<tr><td><a href="http://www.zlib.net/">zlib</a><td>1.2.7<td>Deflate compression <td>zlib License + +<tr><td><i>Optional:</i> +<tr><td><a href="http://www.glfw.org/">glfw</a><td>3.2.1 with patches <td>OpenGL API for UI<td>BSD-style +<tr><td><a href="http://curl.haxx.se/">curl</a><td>7.51.0 with patches <td>HTTP data transfer <td>MIT-style +<tr><td><a href="http://www.luratech.com/">Luratech JP2</a><td>N/A<td>JPEG 2000 decoding <td>commercial +<tr><td><a href="http://www.luratech.com/">Luratech JBIG2</a><td>N/A<td>JBIG2 decoding <td>commercial +<tr><td><a href="https://www.itu.int/rec/T-REC-T.835/">JPEG-XR reference</a><td>1.8 with patches <td>JPEG-XR decoding <td>special +</table> + +<p> +NOTE: +<a href="http://jbig2dec.com/">jbig2dec</a> and +<a href="http://mujs.com/">MuJS</a> +are included in "thirdparty" but are copyright Artifex Software Inc. + +</article> + +<footer> +<a href="http://artifex.com"><img src="artifex-logo.png" align="right"></a> +Copyright © 2006-2017 Artifex Software Inc. +</footer> + +</body> +</html> diff --git a/docs/thirdparty.txt b/docs/thirdparty.txt deleted file mode 100644 index a8e9ba5e..00000000 --- a/docs/thirdparty.txt +++ /dev/null @@ -1,38 +0,0 @@ - Third Party Libraries Used by MuPDF - =================================== - -Library Version Function License URL - -freetype 2.5.5 Font scaling Freetype http://www.freetype.org/ - and rendering License - -glfw 3.1.1 Open GL API BSD-style http://www.glfw.org/ - (with patches) for UI - -harfbuzz 1.2.7 Text shaping MIT-style http://www.harfbuzz.org/ - (with patches) - -jpeg 9.0 JPEG decoding "Free", with - acknowledgement http://www.ijg.org/ - -openjpeg 2.0.0 JPEG 2000 BSD-style http://www.openjpeg.org/ - (with patches) decoding - -zlib 1.2.7 (De)Flate zlib License http://www.zlib.net/ - compression - -(Optional) - -curl 7.31.0 HTTP data MIT-style http://curl.haxx.se/ - transfer - -Luratech JP2 JPEG 2000 commercial http://www.luratech.com/ - decoding - -Luratech JBIG2 JBIG2 commercial http://www.luratech.com/ - decoding - -JPEG-XR 1.8 JPEG-XR special https://www.itu.int/rec/T-REC-T.835/ -reference (with patches) decoding - -NOTE: jbig2dec and mujs are included in "thirdparty" but are copyright Artifex Software Inc. diff --git a/docs/types.txt b/docs/types.txt deleted file mode 100644 index 1301b19c..00000000 --- a/docs/types.txt +++ /dev/null @@ -1,22 +0,0 @@ -Various different integer types are used throughout MuPDF. - -In general: - - * int is assumed to be 32bit at least. - - * short is assumed to be exactly 16 bits. - - * char is assumed to be exactly 8 bits. - - * array sizes, string lengths, and allocations - are measured using size_t. size_t is 32bit in 32bit builds, - and 64bit on all 64bit builds. - - * buffers of data use unsigned chars (or uint8_t's). - - * Offsets within files/streams are represented using fz_off_t's. - fz_off_t's are 64bits in 64bit builds, or in 32bit builds with - FZ_LARGEFILE defined. Otherwise they are a native int (so 32bit - in 32bit builds). - -In addition, we use floats and doubles, assumed to be IEEE compliant. |
