Author: Jaroslav Gresula
Contact: jarda@jagpdf.org
Version: 0.2.0-beta
Date: Mon, 12 Oct 2009 21:29:08 +0200
License:MIT License



jag-tipdf is a command line utility that combines plain text and images into a single PDF. It is written in Python and it uses the JagPDF library, which is a Python extension running on x86/Linux, amd64/Linux and x86/Windows.



This software is beta. The latest version can be downloaded from http://jagpdf.org/downloads/jag-tipdf.

The development branch is available at GitHub. To clone the branch, do:

$ git clone git://github.com/jgresula/jag-tipdf.git


jag-tipdf depends on the JagPDF library. If the library is not installed on your system, follow the instructions on the JagPDF download page.

To install jag-tipdf, run

$ python setup.py install

Optionally, you can run tests:

$ python setup.py test



This is the the html version of the man page.


jag-tipdf [global-options] [[input-options] INPUT] ...


jag-tipdf sequentially appends INPUTs (or standard input if the file name - is given) to a PDF file. By default, jag-tipdf sends the PDF file to standard output. The INPUT can be either a path to a local file or a URL.

The PDF file is initially configured according to global-options. Then for each INPUT its input-options are applied and the INPUT is appended to the PDF file.

The INPUT can be either plain text or an image. jag-tipdf natively supports JPEG and PNG image formats. Where available, other formats are supported through conversion to PNG using PIL (Python Imaging Library) or imagemagick.


Once an input-option is specified, its value remains valid across the following INPUTs. All global-options must precede the first INPUT, otherwise they will have no effect.

There are several option argument types:

comma separated list of items
hexadecimal rrggbb value
string that can contain the following variables: %basename, %path, %page, and %filestem
expressed in 1/72 inch

General Options

-h, --help show a help message and exit
--version show program's version number and exit

Common Input Options

 Set the type of the INPUT. If TYPE set to auto and the file has a known image extension then jag-tipdf treats the INPUT as an image, otherwise as plain text. The option arguments text and image explicitly set the type of the input. You might need to use this option if an image comes from stdin, or if the file has a non-standard extension. Default value: auto.
--page=FORMAT Set the page size. FORMAT can be either A4, Letter, or width,height in units. Default value: A4
 Set the page background color.
 Set page margins. MARGINS is a top,right,bottom,left list.
 Add a node labeled with STRING to the bookmark tree and associate it with the INPUT.
 Separate the INPUT from the previous one by adding vertical SPACE. SPACE can be either a distance (even negative) expressed in units or break which inserts a page break. Default value: break.
--filter=CMD Execute CMD through the shell and use its stdout instead of the original INPUT.

Text Input Options

--font=FONT Show text using FONT. FONT can be either a path to a font program or a core font name. Core names for monospaced fonts are: Courier, Courier-Bold, Courier-Oblique, and Courier-BoldOblique. Using core fonts usually leads to smaller PDFs. Default value: Courier.
 Set font size.
 Set text color.
--encoding=ENC Specify text encoding. If a file variable -*- coding: -*- is found in the first two lines of the input, then it overrides this option and its value is used instead. Default value: iso-8859-1.
--zebra=COLORS Paint a zebra with COLORS. COLORS is a list of colors.
 Scale character spacing with FACTOR. Positive FACTOR values increase character spacing whereas negative values have the opposite effect. Default value is 0.
 Scale character spacing with FACTOR. Positive FACTOR values increase the distance between individual lines of text whereas negative values have the opposite effect. Default value is 0.
--highlight, --no-highlight
 Turn syntax highlighting on/off. This feature requires Pygments (http://pygments.org). Default: turned off

Image Input Options

 Set the image alignment mode. MODE can be left, center, or right. Default value: left.
--image-fit-wide, --no-image-fit-wide
 Resize the image if it is wider than the page. Default: turned on
 Use DPI instead of the dpi specified in the image.

Global Options

-o, --output-file=FILE
 Send output to FILE instead of stdout.
 Set the initial destination. This option determines how the resulting PDF is initially displayed. Possible values are fitv - fit page height to window, fith - fit page width to window, fit - fit page to window, or a number specifying the zoom factor - factor 1.0 corresponds to 100%.
--full-screen The resulting PDF will be initially displayed in full-screen mode.
 Specify the initial page layout. LAYOUT can be single, cont, or cont-facing.
 Set the owner password.
--user-pwd=PWD Set the user password.
 Set access permissions. PERM can be a combination of no_print, no_modify, and no_copy.
--n-up=N Perform imposition of 2^N pages on a sheet. Default value: 0
 Set the document name. The name is displayed in the document's window title bar. If not specified, then the name of the PDF file is displayed.


All .txt files in the current directory tree.
$ find . -name '.txt' -print0 | xargs -0 jag-tipdf --bookmark=%basename
1MB of random characters.
$ < /dev/urandom tr -dc '!-~' | head -c1048576 | fold | jag-tipdf -
Manual pages from the section 1.
$ find /usr/share/man/man1 -name '*.gz' | \
>     sort | \
>     xargs jag-tipdf \
>     --filter="man \`basename %filestem | cut -d. -f1\` | col -b" \
>     --bookmark=%filestem


The most up-to-date information can be found on the project homepage at <http://jagpdf.org/jag-tipdf>.


Report bugs to <jagpdf@googlegroups.com>.


Written by Jaroslav Gresula <jarda@jagpdf.org>.