.\" EMACS: -*- nroff -*-
.\" First parameter, NAME, should be all caps
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
.\" other parameters are allowed: see man(7), man(1)
.\" TeX users may be more comfortable with the \fB<whatever>\fP and
.\" \fI<whatever>\fP escape sequences to invode bold face and italics, 
.\" respectively.
.TH PDFTOIPE 1 "January 3, 2017"
.\" Please adjust this date whenever revising the manpage.
.\"
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.SH NAME
pdftoipe \- Convert PDF files into editable Ipe format
.SH SYNOPSIS
.B pdftoipe
{ \fIoptions\fP } \fIPDF file\fP [ \fIXML file\fP ]

.SH DESCRIPTION

\fBpdftoipe\fP converts arbitrary PDF files to Ipe's XML format.

Note that \fBpdftoipe\fP is not related to Ipe's use of the PDF file
format.  PDF files generated by Ipe contain an extra stream with Ipe
markup information, which is necessary for Ipe to read the file again.
If you wish to convert an Ipe-generated PDF-file to XML format, you
should use \fIipetoipe -xml\fP!  \fBpdftoipe\fP is meant to allow you
to take arbitrary PDF files and make them editable in Ipe.

\fBpdftoipe\fP does a pretty good job on drawings, but doesn't handle
text very well.  Ipe's text model is based on LaTeX, which is just
too different from the text found in most PDF files.

.TP
\fB-notext\fR
Ignore all text in the PDF file, convert graphics only
.TP
\fB-literal\fR
Allow Latex markup in text objects.  The default is to escape all
characters special in Latex.
.TP
\fB-math\fR
Use LaTeX math mode for all text in the PDF file
.TP
\fB-merge\fR \fIint\fP
Set the text merge level, an integer between 0 (the default) and 2.
It determines how eagerly \fBpdftoipe\fP tries to combine consecutive
text in the PDF document into a single Ipe text object.  At level 0,
only characters consecutively rendered in PDF are combined. At level
1, more text is combined.  At level 2, all text is combined until a
path or image is drawn.
.TP
\fB-unicode\fR \fIint\fP 
Determine what should be done with non-ASCII
characters in text.  At level 0, all non-ASCII
characters are represented as \fB[U+XXX]\fR.  At level 1 (the
default), some often used characters (such as bullets) are replaced by
Latex equivalents, others are represented as \fB[U+XXX]\fR.
At level 2, characters that are not replaced by Latex equivalents
are included in UTF-8.  At level 3, all characters are included as
UTF-8.

At level 2 and 3, UTF-8 is set as the input encoding in the Latex
preamble of the generated Ipe document.

Note that this only concerns characters for which the PDF file
provides a mapping to Unicode.  Characters from embedded fonts without
Unicode mapping (such as symbol fonts) are always represented as
\fB[S+XX]\fR.
.TP
\fB-f\fR \fIint\fP
First page to convert
.TP
\fB-l\fR \fIint\fP
Last page to convert
.TP
\fB-opw\fR \fIstring\fP
Owner password for encrypted PDF files
.TP
\fB-upw\fP \fIstring\fP
User password for encrypted PDF files
.TP
\fB-q\fP
Quiet mode (don't print any messages or errors)

.SH AUTHOR
Otfried Cheong

.SH REPORTING BUGS
.ad l
Please report bugs at
.I "https://github.com/otfried/ipe-tools/issues"

.SH SEE ALSO
.ad l
More information about Ipe can be found in  
.IR "The Ipe Manual" , 
available online at 
.I "http://ipe.otfried.org/manual/manual.html"