ipdf(1)

NAME
ipdf - Creates indexed pdf documents from text files

SYNOPSIS
ipdf [-hDIiSobdTLlcfFmatsKk] [file]

DESCRIPTION
Creates pdf documents from text files. When called without arguments, the contents of STDIN are converted to PDF and printed on STDOUT. ipdf was created to help facilitate creating a paperless office while still supporting a legacy machine that might generate plain-text reports by allowing an easy and flexible way to convert the text document in to a document that preserves formatting and is indexed/searchable easily. There are many options, and most can be set to defaults in either /etc/ipdf.conf or ~/.ipdf.conf:
 -h

Print help and exit
 -D LEVEL Enable debugging. Only effective if --enable-debug was used during compilation.
 -i LINE[:START:STOP:SUPPRESS:REPARENT] Creates an index using LINE from characters START to STOP. If SUPPRESS is 0, then suppressing multiple spaces in the index will be disabled. If REPARENT is set to a value greater than zero, the bookmark will be moved N indexes up the tree. For example, a reparent value of one will make the index a peer with the previous index, instead of a child. A value of 2 would make it a peer with its parent's parent (? :-/) if there were enough levels. If the value is larger than the number of index levels, then it will be a top-level index. So for indexes that should always be top-level, specify a large reparent value, like 100. To set a default at compile time, use --enable-default-reparent=N flag to configure. Creating an index adds named bookmarks to the PDF document as a collapsable tree. Some readers, such as Adobe Acrobat, will display those bookmarks so the user can jump to parts of the document. Multiple indexes may be specified with multiple -i options. A full -i argument might look like: -i 1:1:80:1:0 See INDEXING for examples of how this works.
 -I PAGE:LINE[:START:STOP:SUPPRESS:REPARENT] Creates an absolute index on page PAGE on line LINE from characters START to STOP. SUPPRESS and REPARENT work the same as for -i. If PAGE is 0, then LINE means the total line count for the entire document instead of the page. If PAGE is -1, then index LINE on every page, even repeat values. The -1 is mostly useful with the -S switch. A full -I argument might look like: -I 1:1:1:80:1:0 See INDEXING for more information.
 -x REGEX Instead of relying on line and page counts, use a regex for the index. The line that matches will be used as the index point, currently according the the START to STOP chars. The only way to change START and STOP is to use the -C flag.
 -S FORMAT Specify a format string for the previous index definition. It is passed through sprintf using the index value as the argument, so including a %s will result in the index value being expanded. e.g. -I 1:1 -S 'Line 1: %s'
 -C START[:STOP] Start/stop chars for last index defined. This can be used instead of the :: way during the index spec.
 -Q [1|0] Set the suppress_duplicates flag for last index. 1 is suppress duplicates, 0 is do not suppress duplicates. Currently, indexes will suppress duplicates by default.
 -q [1|0] Set the suppress_space flag for last index. If set to 1, then the index will be run through a filter that will make multiple runs of spaces in to 1 space. This just makes the index look tidier, it does not effect the content at all.
 -r NUMBER Set the reparent number for the previous index definition. Sometimes easier then using :1:80:1:100, etc.
 -R NUMBER Set the default reparent number for all following index definitions. Could be used, e.g., if you wanted all indexes to be top level by using a large reparent number like -R100
 -o FILENAME Output filename, instead of STDOUT
 -b FILENAME File to use as background image, i.e. for putting text over a pre-printed from. Currently only TIFF images are supported.
 -d DPI The DPI of the background image. The default is 72DPI.
 -T NUM Set top margin
 -L NUM Set left margin
 -l LINES Maximum number of lines per page, if no form feed (\f) character is seen before the line count reaches this, then a form feed is forced. Some older systems would simply generate reports based on a pre-defined form length instead of using form feed characters. Use this option to handle those kinds of systems.
 -n Do not treat form feed as a line terminator. Some badly written reports may include a newline after a form feed, causing formatting and indexing to get off by 1 line.
 -c CHARS Number of characters per line. Depending on landscape/portrait/ green bar/laser/daisywheel etc types of paper and printers, there may be different numbers of characters per line for those kinds of documents.
 -m PAGETYPE Page mode. The format is pagetype, a '-', followed by p or l. The p/l is portrait or landscape for that paper size. e.g. " -m 'letter-p'" means set page mode to letter in portrait. Valid page modes are: A0 A1 A2 A3 A4 A5 A6 B5 letter legal ledger 11x17
 -f SIZE Font size. May be a decimal, i.e 7.5.
 -F FACE Font face name, valid values are: Courier Courier-Bold Courier-Oblique Courier-BoldOblique Helvetica Helvetica-Bold Helvetica-Oblique Helvetica-BoldOblique Times-Roman Times-Bold Times-Italic Times-BoldItalic Symbol ZapfDingbats For reports Courier or Courier-Bold are best because they are fixed- width fonts and will preserve the formatting on old reports.
 -a AUTHOR Set the author portion of the PDF metainfo. Defaults to 'Unknown'.
 -t TITLE Set the title of the PDF metainfo. Defaults to the filename.
 -s SUBJECT Set the subject of the PDF metainfo. Defaults to 'PDF Document'.
 -K KEY Set the extra key to KEY. The default KEY is "Keywords" since Adobe Acrobat recognizes that extra key and will display it in the document properties.
 -k DATA Data to attach to KEY. If KEY is "Keywords" or left as the default, this data will appear in the Keywords box in Adobe Acrobat.

INDEXING
Currently 3 indexing methods are supported, absolute page/line indexing, relative line-based indexing, and regex indexing. You should only use 1 form of indexing at a time, mixing different indexing types though not fatal, is currently an undefined action.

RELATIVE INDEXING
Most text-based reporting systems use the running-header approach. For example, a system that prints a customer listing might create a header that contains the customer number, territory, and salesman name. For example sake, let's say it looks a little like this: Page 1 CUSTOMER LIST DATE Salesman: 004 Mr Salesman 00100 Mr Customer
 ... If this is a standard header, and it's on every page, you might want an index based on the saleman and customer number. But you don't want to see the same salesman name repeated over and over again in the index, you just need the first occurance. That's what the relative indexing does, it creates a bookmark in the file whenever the value according to the index spec changes, so you can, say, jump to the beginning of the section for Mr Salesman here. Now say each salesman has customers assigned to them, and this report is sorted by salesman then by customer. A convenient index would look like this: 004 Mr Salesman
  + 00100 Mr Customer
  + 00101 Another 005 Another Salesman
 ... So you could click Mr Salesman and go to the beginning of Mr Salesman's section in the report, and you also see all the customers under the salesman in a little tree. Clicking the customer name/number would then take you to the page for that actual customer. With ipdf, you want to be able to index the second and third lines of the report. You could do that with a command like:
 ipdf -o report.pdf -i 1:11:20 -i 3 report.txt And it would create report.pdf from report.txt. Notice that 1 of the -i args has more : options in it, any options you don't fill in will get the default. The only option required, is the line number, but in the first -i I chose to use only characters 11-20 because I wanted to get rid of the word "Salesman" at the beginning of the line.

ABSOLUTE INDEXING
Sometimes there are reports that are always N pages long, maybe a summary by division report. For example, if you had 3 sales divisions, say inside, outside, and industrial sales, and you have a report, "Sales by Division Summary" and it's always 3 pages long. Furthermore, the name of the division for the page is on line #2. To make an index for each of the divisions, on page 1, 2, and 3, you could use absolute indexing like this:
 ipdf -o report.pdf -I 1:2 -I 2:2 -I 3:2 report.txt And you would have indexes created for page 1 line 2, page 2 line 2, and page 3 line 2.

REGEX INDEXING
The regex is probably the easiest to understand. It just indexes lines based on if they match an EXTENDED regular expression. It supports whatever you're current regex library will allow. For example, you can create nice man pages by doing: man ls | ul -t dumb | expand | ipdf -mletter-p -f12 -T0 -L50 -l65 -x '^[A-Z ]+.$' > ls.pdf The ul and expand just help create normal text, and with ipdf the font is set to 12pt, the top aligned to the very top of the page (man pages have some top space) and adjusted a little to the right, in letter-portriat mode and 65 lines per page. The regex looks for lines containing all caps, which happen to be the style that most man page headers are, and then it's all redirected to a pdf file.

CONFIG FILES
Configuration files can reside in both /etc/ipdf.conf and ~/.ipdfrc. They can be used to set global defaults, since usally most reports from a system are formatted mostly the same. That means that most likely, 90% or more of the time you will want the same font/page/margins. The precedence of options goes: internal defaults -> /etc/ipdf.conf -> ~/.ipdf.conf -> command line options The format of the options file is: directive <space> value With the command line options overriding any defaults. The configuration files can contain the following directives:
 debug    Same as -D
 chars_per_line    Same as -c
 lines_per_page    Same as -l
 top_margin    Same as -T
 left_margin    Same as -L
 font_size    Same as -f
 font_face    Same as -F
 page_mode    Same as -m
 author    Same as -a
 subject    Same as -s
 title    Same as -t
 extra_key    Same as -K
 extra_data    Same as -k
For a sample, see the ipdf.conf.dist that comes with the distribution.

BUGS
A little sensitive to the order of options on the command line. Indexing can be confusing, especially the reparent option. Mixing different index types can have unpredictable results, and is not gauranteed to be the same in any future releases.

THANKS
James Tait <JTait@wyrddreams.demon.co.uk> Help with bugfixes, features, and building on Solaris Nievin <nievin@monumental.com> Found bug with form feed handling

AUTHOR
Steve Slaven <bpk@hoopajoo.net>

SEE ALSO