xpdfrc(5)                                             xpdfrc(5)





NAME
       xpdfrc  -  configuration  file  for  Xpdf tools (version
       2.03)

DESCRIPTION
       All of the Xpdf tools read a single configuration  file.
       If  you  have  a .xpdfrc file in your home directory, it
       will be read.  Otherwise,  a  system-wide  configuration
       file  will  be  read  from  /usr/local/etc/xpdfrc, if it
       exists.  (This is its  default  location;  depending  on
       build  options,  it  may be placed elsewhere.)  On Win32
       systems, the xpdfrc file should be placed  in  the  same
       directory as the executables.

       The  xpdfrc  file  consists of a series of configuration
       options, one per line.  Blank lines and  lines  starting
       with a '#' (comments) are ignored.

       The  following  sections  list  all of the configuration
       options, sorted into functional  groups.   There  is  an
       examples section at the end.

INCLUDE FILES
       include config-file
              Includes  the  specified config file.  The effect
              of this is equivalent to inserting  the  contents
              of  config-file  directly  into the parent config
              file in place of  the  include  command.   Config
              files can be nested arbitrarily deep.

CHARACTER MAPPING
       nameToUnicode map-file
              Specifies  a file with the mapping from character
              names to Unicode.  This is  used  to  handle  PDF
              fonts  that have valid encodings but no ToUnicode
              entry.  Each line of a nameToUnicode  file  looks
              like this:

                   hex-string name

              The  hex-string  is the Unicode (UCS-2) character
              index, and name is  the  corresponding  character
              name.   Multiple nameToUnicode files can be used;
              if a character name is given more than once,  the
              code  in  the last specified file is used.  There
              is a built-in default  nameToUnicode  table  with
              all of Adobe's standard character names.

       cidToUnicode registry-ordering map-file
              Specifies  the file with the mapping from charac-
              ter collection to Unicode.  Each line of  a  cid-
              ToUnicode file represents one character:

                   hex-string

              The  hex-string  is the Unicode (UCS-2) index for
              that character.  The first line maps CID  0,  the
              second  line CID 1, etc.  File size is determined
              by size of the character  collection.   Only  one
              file  is  allowed  per  character collection; the
              last specified file is used.  There are no built-
              in cidToUnicode mappings.

       unicodeToUnicode font-name-substring map-file
              This  is used to work around PDF fonts which have
              incorrect Unicode information.   It  specifies  a
              file  which  maps from the given (incorrect) Uni-
              code indexes to the correct  ones.   The  mapping
              will  be  used  for  any font whose name contains
              font-name-substring.   Each  line   of   a   uni-
              codeToUnicode file represents one Unicode charac-
              ter:

                  in-hex out-hex1 out-hex2 ...

              The in-hex field is an input (incorrect)  Unicode
              index, and the rest of the fields are one or more
              output (correct) Unicode  indexes.   Each  occur-
              rence  of  in-hex will be converted to the speci-
              fied output sequence.

       unicodeMap encoding-name map-file
              Specifies the file with mapping from  Unicode  to
              encoding-name.   These  encodings  are used for X
              display fonts and text output (see below).   Each
              line  of  a unicodeMap file represents a range of
              one or more Unicode characters  which  maps  lin-
              early to a range in the output encoding:

                   in-start-hex in-end-hex out-start-hex

              Entries  for single characters can be abbreviated
              to:

                   in-hex out-hex

              The in-start-hex and in-end-hex  fields  (or  the
              single  in-hex  field) specify the Unicode range.
              The out-start-hex field (or  the  out-hex  field)
              specifies the start of the output encoding range.
              The length  of  the  out-start-hex  (or  out-hex)
              string  determines the length of the output char-
              acters (e.g., UTF-8  uses  different  numbers  of
              bytes   to   represent  characters  in  different
              ranges).  Entries must  be  given  in  increasing
              Unicode  order.   Only  one  file  is allowed per
              encoding; the last specified file is  used.   The
              Latin1,  ASCII7, Symbol, ZapfDingbats, UTF-8, and
              UCS-2 encodings are predefined.

       cMapDir registry-ordering dir
              Specifies a search directory, dir, for CMaps  for
              the   registry-ordering   character   collection.
              There can be multiple directories for a  particu-
              lar collection.  There are no default CMap direc-
              tories.

       toUnicodeDir dir
              Specifies a search directory, dir, for  ToUnicode
              CMaps.   There can be multiple ToUnicode directo-
              ries.  There are no  default  ToUnicode  directo-
              ries.

DISPLAY FONTS
       displayFontX PDF-font-name XLFD encoding-name
              Maps  a  PDF  font,  PDF-font-name, to an X font,
              XLFD, for display.   The  XLFD  (X  Logical  Font
              Descriptor) should contain the string "%s", which
              will be replaced by xpdf with the font size.   If
              the  XLFD contains spaces it must be quoted.  The
              encoding-name must be defined with the unicodeMap
              command  (see  above).   By  default, the Base-14
              fonts are mapped to standard X fonts,  using  the
              Latin1, Symbol, and ZapfDingbats encodings.

       displayFontT1 PDF-font-name T1-file
              Maps  a PDF font, PDF-font-name, to a Type 1 font
              for display.  The  Type  1  font  file,  T1-file,
              should be a standard .pfa or .pfb file.

       displayFontTT PDF-font-name TT-file
              Maps  a  PDF  font,  PDF-font-name, to a TrueType
              font  for  display.   The  TrueType  font   file,
              TT-file, should be a standard .ttf file.

       displayNamedCIDFontX PDF-font-name XLFD encoding-name
              Maps   a   specific   PDF   CID   (16-bit)  font,
              PDF-font-name, to the X font, XLFD, for  display.
              The  encoding  given  by  encoding-name  must  be
              defined with the unicodeMap command.   There  are
              no default display CID font mappings.

       displayCIDFontX registry-ordering XLFD encoding-name
              Maps  the  registry-ordering character collection
              to the X font, XLFD, for display.   This  mapping
              is used if the font name doesn't match any of the
              fonts  declared  with  displayNamedCIDFont*  com-
              mands.   The encoding given by encoding-name must
              be defined with the  unicodeMap  command.   There
              are no default display CID font mappings.

       displayNamedCIDFontT1 PDF-font-name T1-file
              Maps   a   specific   PDF   CID   (16-bit)  font,
              PDF-font-name, to a CID font  (16-bit  PostScript
              font),  for  display.   There  are no default CID
              font mappings.

       displayCIDFontT1 registry-ordering T1-file
              Maps the registry-ordering  character  collection
              to  a CID font (16-bit PostScript font), for dis-
              play.  This mapping is  used  if  the  font  name
              doesn't match any of the fonts declared with dis-
              playNamedCIDFont* commands.  There are no default
              CID font mappings.

       displayNamedCIDFontTT PDF-font-name TT-file
              Maps   a   specific   PDF   CID   (16-bit)  font,
              PDF-font-name, to a (16-bit) TrueType  font,  for
              display.  There are no default CID font mappings.

       displayCIDFontTT registry-ordering TT-file
              Maps the registry-ordering  character  collection
              to  a  (16-bit) TrueType font, for display.  This
              mapping is used if the font  name  doesn't  match
              any  of  the fonts declared with displayNamedCID-
              Font* commands.  There are no  default  CID  font
              mappings.

       fontDir dir
              Specifies  a  search  directory for external font
              files.  There can be  multiple  fontDir  directo-
              ries.   If  a  PDF  file  uses a font but doesn't
              embed it, these directories will be searched  for
              a  matching  font  file.  These fonts are used by
              both xpdf (for display) and pdftops  (for  embed-
              ding  in the generated PostScript).  Type 1 fonts
              must have a suffix of ".pfa", ".pfb",  ".ps",  or
              no  suffix  at  all.   TrueType fonts must have a
              ".ttf" suffix.  Other files in these  directories
              will  be  ignored.   There are no default fontDir
              directories.

POSTSCRIPT CONTROL
       psPaperSize width(pts) height(pts)
              Sets the paper size for PostScript  output.   The
              width  and  height parameters give the paper size
              in PostScript points.

       psPaperSize letter | legal | A4 | A3 | match
              Sets the paper size for PostScript  output  to  a
              standard  size.   The  default  paper size is set
              when xpdf and pdftops  are  built,  typically  to
              "letter"  or  "A4".   This  can  also  be  set to
              "match", which will set the paper size  to  match
              the size specified in the PDF file.

       psDuplex yes | no
              If  set  to  "yes", the generated PostScript will
              set the "Duplex" pagedevice  entry.   This  tells
              duplex-capable   printers  to  enable  duplexing.
              This defaults to "no".

       psLevel level1 | level1sep | level2 | level2sep | level3
       | level3Sep
              Sets the  PostScript  level  to  generate.   This
              defaults to "level2".

       psFont PDF-font-name PS-font-name
              When  the  PDF-font-name  font  is  used in a PDF
              file, it will be  translated  to  the  PostScript
              font  PS-font-name,  which is assumed to be resi-
              dent in the  printer.   Typically,  PDF-font-name
              and  PS-font-name are the same.  By default, only
              the Base-14 fonts are assumed to be resident.

       psNamedFont16 PDF-font-name wMode PS-font-name encoding
              When the 16-bit font PDF-font-name is used  in  a
              PDF  file  with the wMode writing mode and is not
              embedded, the PS-font-name  font  is  substituted
              for  it.  The writing mode must be either 'H' for
              horizontal or 'V' for vertical.  The PS-font-name
              font is assumed to be resident in the printer and
              to use the specified encoding  (which  must  have
              been defined with the unicodeMap command).

       psFont16 registry-ordering wMode PS-font-name encoding
              When  a  16-bit  font using the registry-ordering
              character collection and wMode  writing  mode  is
              not  embedded and does not match any of the fonts
              declared   in   psNamedFont16    commands,    the
              PS-font-name  font  is  substituted  for it.  The
              writing mode must be either 'H' for horizontal or
              'V'  for  vertical.   The  PS-font-name  font  is
              assumed to be resident in the printer and to  use
              the  specified  writing  mode and encoding (which
              must have been defined with the  unicodeMap  com-
              mand).

       psEmbedType1Fonts yes | no
              If  set  to  "no",  prevents  embedding of Type 1
              fonts in generated PostScript.  This defaults  to
              "yes".

       psEmbedTrueTypeFonts yes | no
              If  set  to  "no", prevents embedding of TrueType
              fonts in generated PostScript.  This defaults  to
              "yes".

       psEmbedCIDTrueTypeFonts yes | no
              If  set  to "no", prevents embedding of CID True-
              Type fonts in generated PostScript.  For Level  3
              PostScript,  this generates a CID font, for lower
              levels it generates a non-CID composite font.

       psEmbedCIDPostScriptFonts yes | no
              If set to "no", prevents embedding of  CID  Post-
              Script  fonts in generated PostScript.  For Level
              3 PostScript, this  generates  a  CID  font,  for
              lower  levels  it  generates  a non-CID composite
              font.

       psOPI yes | no
              If set to "yes", generates  PostScript  OPI  com-
              ments  for  all  images  and forms which have OPI
              information.  This option is  only  available  if
              the  Xpdf  tools  were compiled with OPI support.
              This defaults to "no".

       psASCIIHex yes | no
              If set to "yes", the ASCIIHexEncode  filter  will
              be used instead of ASCII85Encode for binary data.
              This defaults to "no".

       psFile file-or-command
              Sets the default PostScript file or print command
              for  xpdf.   Commands start with a '|' character;
              anything else is a file.  If  the  file  name  or
              command  contains spaces it must be quoted.  This
              defaults to unset, which tells xpdf to generate a
              name  of  the  form  <file>.ps  for  a  PDF  file
              <file>.pdf.

       fontDir dir
              See the description above, in the  DISPLAY  FONTS
              section.

TEXT CONTROL
       textEncoding encoding-name
              Sets  the encoding to use for text output.  (This
              can be overridden with the "-enc" switch  on  the
              command line.)  The encoding-name must be defined
              with the unicodeMap command  (see  above).   This
              defaults to "Latin1".

       textEOL unix | dos | mac
              Sets  the  end-of-line convention to use for text
              output.  The options are:

                  unix = LF
                  dos  = CR+LF
                  mac  = CR

              (This can be overridden with the "-eol" switch on
              the command line.)  The default value is based on
              the OS where xpdf and pdftotext were built.

       textPageBreaks yes | no
              If set to "yes", text extraction will insert page
              breaks  (form  feed  characters)  between  pages.
              This defaults to "yes".

       textKeepTinyChars yes | no
              If set to "yes", text extraction  will  keep  all
              characters.  If set to "no", text extraction will
              discard tiny (smaller than  3  point)  characters
              after   the   first   50000  per  page,  avoiding
              extremely slow run times for PDF files  that  use
              special  fonts  to  do shading or cross-hatching.
              This defaults to "no".

MISCELLANEOUS SETTINGS
       initialZoom percentage | page | width
              Sets the initial zoom factor.  A number specifies
              a  zoom  percentage, where 100 means 72 dpi.  You
              may also specify 'page', to fit the page  to  the
              window size, or 'width', to fit the page width to
              the window width.

       t1libControl none | plain | low | high
              Sets the type of font rendering  for  t1lib  (the
              Type  1  rasterizer)  to use.  Options are "none"
              (don't use t1lib at all), "plain" (use  non-anti-
              aliased fonts), "low" or "high" (use low-level or
              high-level anti-aliased fonts).  This defaults to
              "low".

       freetypeControl none | plain | low | high
              Sets the type of font rendering for FreeType (the
              TrueType rasterizer) to use.  Options are  "none"
              (don't  use  FreeType  at all), "plain" (use non-
              anti-aliased fonts), "low" or "high"  (use  anti-
              aliased  fonts;  these  two are identical).  This
              defaults to "low".

       urlCommand command
              Sets the command executed when you click on a URL
              link.   The string "%s" will be replaced with the
              URL.  (See  the  example  below.)   This  has  no
              default value.

       movieCommand command
              Sets  the  command  executed  when you click on a
              movie  annotation.   The  string  "%s"  will   be
              replaced  with  the movie file name.  This has no
              default value.

       mapNumericCharNames yes | no
              If set to "yes", the Xpdf tools will  attempt  to
              map  various  numeric  character  names sometimes
              used in font subsets.  In some cases  this  leads
              to  usable  text,  and in other cases it leads to
              gibberish -- there is no way for  Xpdf  to  tell.
              This defaults to "yes".

       printCommands yes | no
              If  set to "yes", drawing commands are printed as
              they're executed (useful  for  debugging).   This
              defaults to "no".

       errQuiet yes | no
              If  set  to  "yes", this suppresses all error and
              warning messages from  all  of  the  Xpdf  tools.
              This defaults to "no".

EXAMPLES
       The following is a sample xpdfrc file.

       # from the Thai support package
       nameToUnicode /usr/local/share/xpdf/Thai.nameToUnicode

       # from the Japanese support package
       cidToUnicode Adobe-Japan1 /usr/local/share/xpdf/Adobe-Japan1.cidToUnicode
       unicodeMap   JISX0208     /usr/local/share/xpdf/JISX0208.unicodeMap
       cMapDir      Adobe-Japan1 /usr/local/share/xpdf/cmap/Adobe-Japan1

       # use an X server font for Times-Roman
       # (this is the built-in default)
       displayFontX Times-Roman "-*-times-medium-r-normal-*-%s-*-*-*-*-*-iso8859-1" Latin1

       # use the Base-14 Type 1 fonts from ghostscript
       # (note that this overrides the displayFontX command above)
       displayFontT1 Times-Roman           /usr/local/share/ghostscript/fonts/n021003l.pfb
       displayFontT1 Times-Italic          /usr/local/share/ghostscript/fonts/n021023l.pfb
       displayFontT1 Times-Bold            /usr/local/share/ghostscript/fonts/n021004l.pfb
       displayFontT1 Times-BoldItalic      /usr/local/share/ghostscript/fonts/n021024l.pfb
       displayFontT1 Helvetica             /usr/local/share/ghostscript/fonts/n019003l.pfb
       displayFontT1 Helvetica-Oblique     /usr/local/share/ghostscript/fonts/n019023l.pfb
       displayFontT1 Helvetica-Bold        /usr/local/share/ghostscript/fonts/n019004l.pfb
       displayFontT1 Helvetica-BoldOblique /usr/local/share/ghostscript/fonts/n019024l.pfb
       displayFontT1 Courier               /usr/local/share/ghostscript/fonts/n022003l.pfb
       displayFontT1 Courier-Oblique       /usr/local/share/ghostscript/fonts/n022023l.pfb
       displayFontT1 Courier-Bold          /usr/local/share/ghostscript/fonts/n022004l.pfb
       displayFontT1 Courier-BoldOblique   /usr/local/share/ghostscript/fonts/n022024l.pfb
       displayFontT1 Symbol                /usr/local/share/ghostscript/fonts/s050000l.pfb
       displayFontT1 ZapfDingbats          /usr/local/share/ghostscript/fonts/d050000l.pfb

       # from the Japanese support package
       displayCIDFontX Adobe-Japan1 "-*-fixed-medium-r-normal-*-%s-*-*-*-*-*-jisx0208.1983-0" JISX0208

       # use the Bakoma Type 1 fonts
       # (this assumes they happen to be installed in /usr/local/fonts/bakoma)
       fontDir /usr/local/fonts/bakoma

       # set some PostScript options
       psPaperSize          letter
       psDuplex             no
       psLevel              level2
       psEmbedType1Fonts    yes
       psEmbedTrueTypeFonts yes
       psFile               "| lpr -Pprinter5"

       # assume that the PostScript printer has the Univers and
       # Univers-Bold fonts
       psFont Univers      Univers
       psFont Univers-Bold Univers-Bold

       # set the text output options
       textEncoding UTF-8
       textEOL      unix

       # misc options
       t1libControl    low
       freetypeControl low
       urlCommand      "netscape -remote 'openURL(%s)'"


FILES
       /usr/local/etc/xpdfrc
              This  is the default location for the system-wide
              configuration file.  Depending on build  options,
              it may be placed elsewhere.

       $HOME/.xpdfrc
              This  is  the  user's  configuration file.  If it
              exists, it will be read in place of  the  system-
              wide file.

AUTHOR
       The   Xpdf  software  and  documentation  are  copyright
       1996-2003 Glyph & Cog, LLC.

SEE ALSO
       xpdf(1),    pdftops(1),    pdftotext(1),     pdfinfo(1),
       pdftopbm(1), pdfimages(1)
       http://www.foolabs.com/xpdf/



                        10 October 2003               xpdfrc(5)
