Moonshiner Documentation

Before using Moonshiner

What is Moonshiner?

Moonshiner is a graphical frontend (GUI) for Ghostscript's PostScript-to-PDF converter. While Ghostscript (and its wrapper ps2pdf) is a very powerful instrument, it is quite challenging to use its parameters on the command line, especially if you (like me) often change the settings as to what kind of color conversion, image resampling etc. you want Ghostscript to perform.

While I have never used Adobe's Distiller, and thus cannot really compare the two, Moonshiner (as the name suggests) is supposed to be a work-alike for the Linux world – at least GUI-wise; the actual work is of course done by Ghostscript.

Moonshiner is released under the GNU GPL v3+, meaning it is free software that you can use, edit and distribute as you like (as long as you keep it under the same license).

Moonshiner 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.

Visit Moonshiner's homepage for updates and other information.

This Document

This document comes in two flavors: Either just as a How-to-Use description of Moonshiner, or with additional information on the Ghostscript parameters that are affected, and other implementation details.

Show technical details

Requirements

Moonshiner needs the following to work:

Chances are that all three are already installed with your Linux distribution.

Installation

If you downloaded the rpm package, just install it with your package manager, e.g yum --nogpgcheck install moonshiner-1.0-1.noarch (as root) on Fedora. Otherwise, Unpack the downloaded archive to a directory of your choice. In that directory, call python setup.py install (you will need root privileges for that). Afterwards, you can start Moonshiner by calling moonshiner. You can also remove the temporary directory again.

Using Moonshiner

The Moonshiner Window

The Moonshiner window is split vertically into three parts. The top part (besides the logo) shows the “Input and Output” field where you chose the PostScript source and the destination PDF file. See below for details.

The middle part is where you actually set the parameters for the conversion. The five tabs, called “Misc,” “Images,” “Color,” “Fonts,” and “Encryption” are described in more detail below.

The bottom row shows several buttons, each one basically doing what it says (no, really!). The “Help” button opens this very text in your browser. The “About” opens the usual About box with information on the program author, license etc.

There is a bug in Python's webbrowser.open that leads to Firefox 3 not working correctly. Since I suppose most people using Moonshiner have Firefox 3 as their default browser, instead of using webbrowser.open I worked around the issue by relying on gnome-open (inspired by Smolt) for opening the help page. This should work on most Linuxes.

The “Configure” button opens the configuration dialog. Two settings can be changed here: The Ghostscript command line (the pre-configured value gs should usually suffice, since the Ghostscript executable is usually in your $PATH), and the PDF creation preset that will be used by default when Moonshiner opens (see The “Misc” Tab for more). The “Quit” button closes Moonshiner without doing the conversion.

The “Go Moonshing!” button is what actually starts the conversion according to your settings by calling Ghostscript. Clicking this button will open a new tab showing the Ghostscript command line and Ghostscript's output (except for the PDF itself). If the box next to “Quit if successful” is checked, Moonshiner will exit after the conversion, provided Ghostscript exits with a return code of zero, indicating success. If the conversion fails, Moonshiner will not exit, so you can check Ghostscript's output for error messages.

Please note that while you can uncheck “Quit if successful” to do several conversions without re-opening Moonshiner every time, at most one of these conversions should usually go to standard output (if you do not want to end up with one file containing several PDFs – which you don't, probably).

Input and Output

By default, Moonshiner works as a filter, meaning that the input PostScript file is taken from the standard input, and the output PDF file is written to the standard output. This enables you to call something like 

moonshiner < input_file.ps > output_file.pdf
from the command line. When you start Moonshiner, you can see that the Input File and Output File values in the top left corner are set to the standard channels.

While Moonshiner's standard input is forwarded directly to Ghostscript (by means of a shared file descriptor), Ghostscript's standard output is filtered by Moonshiner to exclude everything before the %PDF-1.x comment starting the actual PDF file. This is done because Ghostscript sends PostScript errors (including stack traces) to standard output, not standard error.

If you instead want to use direct file operations, you can drag your source PostScript file from your file manager and drop it on the Moonshiner window. If Output File was set to standard output, dropping the source file will also automatically choose the same directory and file name (except for the extension) for the output. If you want the output to go to a different directory, just drag and drop this directory onto Moonshiner. You can also edit the output file name right in place.

You can always set Input File and Output File back to using the standard channels by clicking the corresponding buttons.

The “Misc” Tab

This tab controls settings that do not belong to any of the other categories. Probably most important is the preset that all other settings are based on. This should always be the first thing to choose (based on what purpose your PDF is going to serve) when you change settings. Any changes to those other settings that you have made before will be overwritten when you choose a new preset (you will be asked for confirmation). You can change the preset that is chosen by default in the configuration dialog.

These are actually Ghostscript's /dPDFSETTINGS presets (except for the /Blend difference mentioned below), meaning that they also control some settings that cannot be changed with Moonshiner.

In the “Misc” tab you can also choose which PDF version (1.3 or 1.4) the created file will be compatible with. Note that this will have consequences concerning how fine-grained the restrictions for encrypted PDFs can be; see the “Encryption” tab for details.

The settings for compression of contents and ASCII encoding of binary should usually not need to be changed other than for debugging purposes or if you need your PDF to be ASCII only.

If the source PostScript file contains no page orientation information (e.g. landscape or portrait), Ghostscript can analyze how the majority of text is oriented in the document, thereby often being able to decide on the correct orientation. You can choose whether to do this at all, and if so, whether this decision should be made on a page-by-page basis or document-wide.

PostScript files can contain code that overrides some of the settings that you make in Moonshiner. If you want to ignore this code to make sure that your settings are applied exactly as you made then, check “Enforce all settings”.

The “Images” Tab

With this tab, you control how images are stored in the PDF file. You can control the settings for color images, grayscale images, and monochrome (i.e. black and white) images seperately. Note that these categories do not refer to the actual content of the images, but to how they were stored in the source PostScript file: A color image can very well contain only black and white – while still being a color image.

For color and grayscale images, you can choose to put them into the PDF file without compression (this should hardly ever be necessary; it only bloats file size), with (lossless) ZIP compression, or with (lossy) JPEG compression. You can also tell Ghostscript to choose between ZIP and JPEG compression for each individual image, based on which method seems more appropriate for the image contents.

For images that will be JPEG compressed, you can set the quality in seven steps from Maximum (good quality, large file size) to Minimum (bad quality, small file size).

The actual values for the /xxxImageDictionary (you can find them in the source file moonshiner_params.py) are based on the Distiller's and Ghostscript's default settings, with one exception: The /Blend value for maximum quality is 1 in Ghostscript, but 0 in Moonshiner.

For monochrome images, you can choose between no compression, ZIP compression, CCITT fax encoding (the default) and runlength encoding. All these methods are lossless.

For each of the three image types, you can choose to resize an image to a maximum print resoultion. If, for example, you choose “Downsample grayscale images to 300 dpi if the image has at least 150 percent of this,” all grayscale images that have at least 450 dots per inch (which is 150% of 300 dpi) will be resized to 300 dpi.

You cannot currently choose the /xxxDownsampleType in Moonshiner. This is mainly because according to its documentation, Ghostscript currently does not implement bicubic resizing anyway.

The “Color” Tab

This tab controls settings related to color information in the PostScript and PDF file. With the top frame labeled “Color conversion” you can choose to convert your file's colors to a different color space. If you do so, you can also choose which rendering intent to apply when doing the conversion.

Ghostscript's documentation is quite non-verbose about its handling of color spaces and color management; in some parts, it is even self-contradicting. Therefore, I may be making some false assumptions here; if you know better, please contact me. Choosing a color conversion in Moonshiner does two things to the Ghostscript parameters: The /ColorConversionStrategy parameter is chosen accordingly, and so is the -sProcessColorModel (or the -dUseCIEColor in case of conversion to device independent color space).

The frame labeled “Passing settings from PS to PDF” controls whether certain color-related settings found in the PostScript file are to be passed into the PDF file. If you do not know what they mean, you should leave them set the way as supposed by your chosen preset.

The “Fonts” Tab

This Tab controls embedding of fonts into the PDF file. If you choose to embed your fonts, you can also choose whether you want subsetting of fonts to be enabled. If you have a font of which only a small subset of glyphs (i.e. characters) are actually used in the file, it usually suffices to only embed those few glyphs. You can set a threshold percentage for subsetting: If the font contains 220 glyphs, and you set the percentage to 50%, this means that the whole font (including the unused glyphs) will be embedded if more than 110 glyphs (50% of 220) are actually used; otherwise, only the necessary glyphs will be embedded. Setting the percentage to 100% will result in fonts always being subsetted.

Moonshiner does not yet include the possibility to toggle embedding on a per-font basis. Ghostscript does support this, however, so this feature might be included in a future version of Moonshiner. Also note that, according to its documentation, Ghostscript will not embed the 14 standard PDF fonts into the PDF if the default, screen or ebook preset is chosen in the “Misc” tab.

You can also choose whether to compress the fonts when embedding them or not. It should hardly ever been neccessary to turn this option off.

Ghostscript documentation expressedly notes that the possibility to turn off Font compressing “is intended only for debugging.”

The “Encryption” Tab

The PDF file format allows content encryption and basic access control. This tab controls the appropriate settings. If you choose to encrypt the document, you have to choose the owner password that will give full and unrestricted access to the encrypted PDF. You can also choose a user password for restricted access. If the PDF file is opened using this password, access to the file is restricted according to the restriction settings.

These settings include restrictions on the amount of modification, printing, and data extraction allowed to be performed on the PDF file. They should be quite self-explaining. Please note that your choice of PDF Version has an influence on the restriction settings. The PDF 1.4 format allows a more fine-grained control on access permissions and restrictions than version 1.3.

It might be worth mentioning that modification restrictions that allow form fields to be filled out but not to be added are not useful if creating a PDF from a PostScript file, since the PostScript language does not include forms. However, as Ghostscript also accepts PDF files as input, Moonshiner will happily pass a PDF file that might already contain a form to Ghostscript.

When using encryption, be advised to keep the following note from the PDF Reference Manual in mind (page 75 in the PDF 1.4 Reference):

“Once the document has been opened and decrypted successfully, the viewer application has access to the entire contents of the document. There is nothing inherent in PDF encryption that enforces the document permissions specified in the encryption dictionary. It is up to the implementors of PDF viewer applications to respect the intent of the document creator by restricting user access to an encrypted PDF file according to the permissions contained in the file.”
In other words: As soon as somebody has the user password for your PDF, he has access to the same data as he would have with the owner password. The Adobe Reader – which most people will use to read your document – will of course honor the restrictions; however, other PDF viewing or editing applications may or may not do so.