   This is the documentation for GNU Trueprint

   Copyright (C) 1999 Free Software Foundation Inc.

Trueprint
*********

Trueprint is a program for printing source code and other text files.

1 Overview
**********

What is Trueprint?  Trueprint is an ugly flower that smells beautiful.

   Trueprint is intended to be the only printing program you will ever
need to print your program source code and other text files.  It tries
to achieve this by being simple to use, providing powerful features,
and being intelligent enough to provide those features when you need
them.

   Trueprint knows about common computer languages and will select
features appropriate to each language.  For example if the language
contains functions then Trueprint will generate a function index.  And
if the language contains the concept of braces then Trueprint will
include a braces depth count in the left-hand margin.

   If you need to customize the appearance of the printed output then
you can use options to turn any of Trueprint's features on or off.  For
example you can specify that the output be printed landscape, two-up,
using an eight-point font with line numbers.  By setting an environment
variable you can create personal defaults for Trueprint which will
override the language defaults and which will in turn be overridden by
the command line options.

   Trueprint knows about the printers available on your system via a
special `printers' file.  This file tells it how large a page is and
whether the printer is double or single sided.  Using this information,
Trueprint can format your output appropriately.

   If there's anything that Trueprint doesn't do, you are welcome to
change the tool itself - just remember that it's covered by the GPL and
be sure to send a copy of the changes to <enhance-trueprint@gnu.org>!

   The original author and current maintainer of trueprint is Lezz
Giles.  His email addresses at the time of writing are
<gilesfamily@mediaone.net>, <lgiles@avici.com>, and
<giles@world.std.com>.

2 Installing Trueprint
**********************

Installing Trueprint is almost as simple as installing any well-behaved
GNU program.  For details, read the README file that comes with the
package.  This section provides an overview of the process, plus
details of the `printers' file.

2.1 Installation Overview
=========================

In the simplest case, assuming you want to install trueprint into
/usr/local/bin, installing trueprint is just a matter of five short
steps:
   * `./configure'

   * `make'

   * `make test'

   * Update the printers file with your printer information.

   * `make install'

   If you want to change the installation root directory from
`/usr/local' to, for example, `/usr' (so that the executable would be
put into  `/usr/bin/trueprint') then just pass the new root directory
to `./configure' using `--prefix', e.g. `./configure --prefix=/usr'.

   If the tests fail then cd to the tests subdirectory and look at the
appropriate `.dif' file.  If you can't work out what's gone wrong then
report the problem to <bug-trueprint@gnu.org>.

2.2 The `printers' file
=======================

The printers file is the most complicated part of Trueprint.  Put
simply, it contains two lists: a list of printer types, and a list of
the printers at your site.  The list of printer types is long (well,
actually it's fairly short) and it should contain the most common
office printers.  The list of printers in the distribution printers
file is just a set of example entries - you should delete these
examples and replace them with your own printer information.

   An example type entry is:
     type:Apple Laswerwriter II:1: 15:597:784:8

   The first field just specifies this as a `type' entry.

   The second field contains the printer type name.  Whitespace is
significant, so there shouldn't be any spaces between the start and end
of the name, and the colons.  The third field is 1 for a single-sided
printer and 2 for a double-sided printer.  The final four fields give
the left, right, top and bottom margins respectively in points from the
bottom left corner of the paper; more specifically they are the
coordinates of the bounding box that the postscript engine on the
printer can print in.

   The first three fields are typically easy to fill in; however the
final four fields need to be calculated for each printer type.
Fortunately the postscript interpreter knows what the coordinates are -
it's just a matter of asking it nicely, and the file `testprint'
contains a little postscript program that will do just that.  If you
print `testprint' using either `lpr' or `lp' then it will print out the
four numbers needed in the `printers' file (on the other hand, if it
simply prints the contents of the file then either your printer is not
configured properly or it isn't a postscript printer - you'll need to
rectify the situation before you can use Trueprint on that printer).

   The second half of the file contains printer entries, for example:
     printer:pr2-simp:HP Laserjet 8000 simplex

   Once again, the first entry simply specifies that this is a
`printer' entry.  The second entry contains the printer queue name as
known to your operating system (i.e. the value you would pass to `lp'
or `lpr').  The third field contains the appropriate printer type name;
once again whitespace is important so make sure there are no trailing
space or tab characters at the end of the line.

   If you have two queues set up to one printer, one for single-sided
output and one for double-sided output, simply set up two printer
types.  Similarly if you have multiple queues for the same printer for
different paper sizes.

3 Languages
***********

Different programming languages have different features and look their
best with different formats.  Since Trueprint tries to be all things to
all people, it understands a number of different languages and tries to
accomodate all of them.  In version 5.0 Trueprint understands:
   * C

   * Verilog

   * C++

   * Shell

   * Pascal

   * Perl

   * Java

   It also understands some other formats:

   * Plain text

   * Pseudo C

   * Listing files

   * A special format called "report format"

   Not all of the languages are fully supported.  C is well supported,
but Java is only minimally supported.  The language support is
implemented in the `lang_*.c' files - if you're not happy with the
level of support for your favorite language just improve - or add - it!

   There are a couple of ways that Trueprint can find out what type of
language a file contains.  It can look at the filename suffix, or it
can be told using the `--language' option.  The details are:

_Language_     _suffix_       _-language option_
C              .c .h          -language=c
Verilog        .v             -language=v
C++            .cxx .cpp .cc  -language=cxx
               .C .hpp .H
Shell          .sh            -language=sh
Pascal         .pas           -language=pascal
Perl           .pl            -language=perl
Java           .java          -language=java
Plain text     default        -language=text
Pseudo C       .pc .ph        -language=pseudoc
Listing        .lst           -language=list
Report format  .rep           -language=report

   For most of the languages, Trueprint uses the language to work out
where comments are (so it can print them in italics) and where the
function names are (so it can print them in bold and include them in
the function index).  However there are some special features for some
of the languages:

   Pseudo C is like C, except it has a more forgiving syntax.  In
particular it ignores strings, so if you leave off a closing quote then
pseudo C will print out using a vaguely sensible format.  Pseudo C is
intended for printing code that doesn't yet compile.

   Listing format assumes very wide lines and a fixed page length of
sixty-six characters, so it turns off line-wrap and sets the page
length appropriately.

   Report format uses a few special characters: anything between ^A and
^E is printed in bold and included in the function index, and anything
between a pair of ^Cs is printed in italics.

4 Page Formatting
*****************

There are a few options that you can use to adjust the overall page
formatting.  Most of these options are pretty self-explanatory.

   For portrait printing use `--portrait', and for landscape printing
use `--landscape'.

   To force the printer to print single-sided use `--single-sided', and
to try to force double-sided printing use `--double-sided'.  These
options also affect headers and footers, so forcing `--double-sided' on
a single-sided printer will result in odd-looking headers and footers.
Also since Trueprint tries to start each file on a new sheet of paper,
specifying `--double-sided' forces occasional pages with no content.

   To print one page of output on one physical sheet, the default, use
`--one-up'.  To print two-up, i.e. two logical pages on one sheet
(side-by-side for portrait or one over the other for landscape) use
`--two-up'.  And to print four logical pages on each sheet (and to help
ruin your eyesight!) use `--four-up'.  There is another mode called
`two-tall-up' which prints two logical pages on each sheet at four-up
pointsize - for portrait format each logical page is very tall and
narrow, and for landscape format each logical page is very wide.

   To leave a gap down the left-hand-side of each physical page so that
you can punch holes in the page without punching out any information,
use `--holepunch', and to leave a gap at the top of the page (if you
want to punch holes at the top) use `--top-holepunch'.  Options
`--no-holepunch' and `no-top-holepunch' exist to override these if
they've been set up as defaults.

5 Page Furniture
****************

Page furniture refers to the bits and pieces scattered around the edge
of each page.  It includes things like headers and footers, line
numbers, and so on.

   The left-hand side of each page can include two columns of
information: line numbers and a count of the current braces depth.
Line numbers are normally included, but they can be forced on with
`--line-numbers' and forced off with `--no-line-numbers'.  The braces
depth count is normally only turned on for languages that have the
concept of braces (e.g. C or Java); it can be explicitly turned on with
`--braces-depth' or it can be turned off with `--no-braces-depth'.

   If you are nostalgic for the old line-printer paper with gray or
green bands running across each page you can turn this on with
`--gray-bands NUMBER' where NUMBER is the width of the bands.  For
example `--gray-bands 3' would print light gray bands three lines deep
all the way down the page.  Naturally you can force this off with
`--no-gray-bands'.

5.1 Headers and Footers
=======================

Headers and footers are printed in boxes at the top and bottom of each
page.  There are three header strings and three footer strings, and
each can be a mixture of constant strings or % escapes.  The strings
are set with `--left-header=STRING', `--center-header=STRING',
`--right-header=STRING', `--left-footer=STRING',
`--center-footer=STRING', and `--right-footer=STRING'.  If you want to
turn off either headers or footers you can use `--no-headers' or
`--no-footers', and of course you can force them on with `--headers' and
`--footers'.

   If you're printing double-sided then the left and right headers and
footers are swapped on every second page.

   Normally headers and footers have a line drawn around them and a
line is also drawn down the left side of each page.  By specifying
`--no-page-furniture-lines' these lines are not drawn.  In fact if you
turn off headers, footers, line count and braces depth then no page
furniture will be drawn at all, i.e.  `--no-page-furniture-lines
--no-headers --no-footers --no-braces-depth --no-line-numbers'.

   There is also an optional message string that is printed across the
middle of each page in a very large, light gray font.  You can use this
message to say things like `draft' or `top secret'.  Use
`--message=STRING' to set the message.

   There are quite a few % escapes that you can use inside the header,
footer and message strings:

`%%'
     Print a simple %.

`%m'
     Print the current month of the year as a number, e.g. 05.

`%d'
     Print the current day of the month, e.g. 01.

`%y'
     Print the current year, e.g. 1999

`%D'
     Print the date in the format mm/dd/yy.

`%L'
     Print the date and time in long format, e.g. Fri Oct 8 11:49:51
     1999

`%c'
     Print the last modified date of the current file in the format
     mm/dd/yy.

`%C'
     Print the last modified date and time of the current file in long
     format, e.g. Fri Oct 8 11:49:51 1999

`%H'
     Print the current hour.

`%M'
     Print the current minute.

`%S'
     Print the current second.

`%T'
     Print the time in the format HH:MM:SS.

`%j'
     Print the day of the year, e.g. 095.

`%w'
     Print the day of the week, e.g. Sunday.

`%a'
     Print the abbreviated day of the week, e.g. Sun.

`%h'
     Print the abbreviated month name, e.g. Mar.

`%r'
     Print the time in am/pm notation, e.g. 10:45pm.

`%p'
     Print the page number in the current file.

`%P'
     Print the overall page number.

`%f'
     Print the total number of pages of the current file.

`%F'
     Print the total number of pages.

`%n'
     Print the current filename.

`%N'
     Print the current function name.

`%l'
     Print the username of the current user.

   The default strings are:

`left-header'     `%L'
`center-header'   `%N'
`right-header'    `Page %P of %F'
`left-footer'     `%L'
`center-footer'   `%n %p'
`right-footer'    `Page %P of %F'

6 Text Formatting
*****************

6.1 Page breaks
===============

There are three places that Trueprint can include page breaks: at the
end of a function (assuming the current language has functions), when
it finds a form-feed character (control-L), and at the end of each file.

   To force on page breaks at the end of functions use
`--page-break-after-function'.  The default behaviour, to not break the
page at the end of a function, can be forced with
`--no-page-break-after-function'.

   You can force Trueprint to expand form-feeds to a new page with
`--form-feeds' and, of course, you can turn it off with
`--ignore-form-feeds'.

6.2 Line wrap
=============

By default Trueprint will wrap lines that are too long for the page.
It will try to break the lines at intelligent locations, for example at
a space character, and it will print the remainder of the line
right-justified.  If you don't like this then you can turn off
line-wrap with `--no-line-wrap', or you can set the line-wrap column
explicitly with `--line-wrap=COLUMN'.  You can also tell Trueprint to
wrap lines at exactly a specific column, i.e. to stop trying to be
clever, with `--no-intelligent-line-wrap'.  Of course you can force the
feature on with `--intelligent-line-wrap'.  And if you want to use
intelligent line-wrap but you want to ensure that you don't end up with
incredibly short lines then you can set the minimum line length with
`--minimum-line-length=NUMBER'.

6.3 Page length and pointsize
=============================

The default pointsize used by Trueprint is 10.  Of course, this is
reduced appropriately if you're printing two-up or four-up.  You can
set the pointsize explicitly with `--pointsize=NUMBER', although bear
in mind that the pointsize will still be scaled down for two-up or
four-up.

   In the old days of printing, strips of lead were used to seperate
the lines of text.  If you wanted more seperation you included more
strips of lead.  Trueprint is nothing if not traditional.  The default
leading (pronounced `ledding') is one point, but you can increase (or
decrease) it with `--leading=NUMBER'.  Not suprisingly you can't
specify a negative number.

   You can set the overall page length with `--page-length=LENGTH'.
Trueprint will set the point size appropriately.  Unfortunately, since
there are a limited number of pointsizes that Trueprint can chose from
(e.g. it can't select 8.35), using this option may result in a blank
space at the bottom of each page.  This option is best used if your
file naturally breaks into pages of a specific length.  You may also
want to turn off line-wrap so that long lines don't mess up your
carefully formatted output.

6.4 Tab size
============

The default tab size is eight characters.  If this eats up too many
columns for you, then you can set it with `--tabsize=NUMBER'.

7 Output Options
****************

By default Trueprint will simply send the postscript output to `lp' or
`lpr' (depending on the ancestry of your version of Unix), and it will
explicitly set the destination to the value of the environment variable
`$PRINTER'.  You can use `--printer=PRINTER' to send the print job to
another printer.  If you like `lp' options then you can also say `-P
PRINTER', or if you are a fan of System V then you can say `-d PRINTER'
(almost every Trueprint option has a single-character equivalent - I
only mention these two explicitly because they are used exactly the
same way as the options to `lpr' and `lp').

   If you want to print multiple copies then just use `--copies=NUMBER'.

   If you want to save the postscript output then you can redirect it
to a file using `--output=FILENAME'.  If you use `-' for the filename
then the postscript will be sent to stdout.  If you use
`--redirect-output' then the output will be sent to a file named after
the first parameter with the suffix `.ps'.  The `--redirect-output'
option overrides the `--output=FILENAME' option, and of course there is
a `--no-redirect-output' option to turn it off.

8 Print Selection
*****************

A Trueprint print job can contain a reasonably long list of pages:
   * A cover sheet,

   * a file index,

   * a function index,

   * and the files.

   Each of these can be explicitly disabled or enabled:

`--no-cover-sheet'                   `--cover-sheet'
`--no-file-index'                    `--file-index'
`--no-function-index'                `--function-index'
`--no-print-body'                    `--print-body'

   In addition there is a mechanism for printing only a subset of the
pages, by using `--print-pages=SELECTION', where selection consists of
a comma-seperated list of page selections:

`NUMBER'
     Print the specific page.

`NUMBER-NUMBER'
     Print all pages between, and including, the specified pages.

`FUNCTION-NAME'
     Print all pages that include FUNCTION-NAME.

`d'
     Print all pages that have changed (this is only useful with the
     `--diff' (see Miscellaneous Features) option.

`D'
     Print all pages containing functions that have changed (this is
     only useful with the `--diff' (see Miscellaneous Features)
     option.

`f'
     Print the function index.

`F'
     Print the file index.

   For example, `--print-pages=1-5,main,f' will print the function
index, pages 1 to 5, and all the pages for the function `main'.

   If you specify `--prompt' then Trueprint will prompt you for each
page, whether or not it should print that page.  It will give you
information such as the current filename, current functionname, page
number, and so on.  The possible responses are:

`y'
     Print this page.

`yNUMBER'
     Print NUMBER pages.

`y*'
     Print all the remaining pages.

`n'
     Skip this page

`nNUMBER'
     Skip NUMBER pages.

`n*'
     Skip all the remaining pages.

`pSELECTION'
     Print all remaining pages that match SELECTION, where SELECTION is
     in the format defined above.

`?'
     Print a help message.

   Of course, you can force the prompting feature off with
`--no-prompt'.

9 Miscellaneous Features
************************

9.1 Diff-marking
================

One of the more obscure but more useful features of Trueprint is the
ability to highlight differences between two versions of sets of files.
Added lines are shown in bold, while deleted lines are shown
struck-out.

   You specify the old version of the file or files with
`--diff=PATHNAME'.  If PATHNAME suffixed with the current filename is a
valid file then the differences between PATHNAME/FILENAME are displayed.
Alternatively, if PATHNAME is a file and you're printing one file, then
the differences between PATHNAME and the current file are displayed.

   Some examples:

     trueprint --diff=../old- this.c that.c

   will print the differences between ../old-this.c and this.c, and
../old-that.c and that.c.

     trueprint --diff=../old/ this.c that.c

   will print the differences between ../old/this.c and this.c, and
../old/that.c and that.c.  Note that the trailing / is important.

     trueprint --diff=this.c that.c

   will print the differences between this.c and that.c.

9.2 Help and Version Information
================================

Use `--help' for general on-line help information.  If you give the
`--help' option a parameter it will give you more detailed information
about a specific area - use `--help' for a list of the areas.

   Use `--version' to see the current version of Trueprint.

9.3 Setting personal defaults
=============================

When Trueprint starts it uses four sets of options:

   * Hard-coded defaults.

   * Language-specific defaults.

   * Options taken from the environment variable `$TP_OPTS'.

   * Command-line options.

   Each set of options overrides the earlier sets, so command-line
options override all other sets.

   If you want to set some personal default options, then simply set
the environment variable `$TP_OPTS'.

9.4 Postscript level
====================

It is possible to request that trueprint generate level 1 or level 2
postscript. Level 2 is the default.  If level 2 is set then trueprint
will send the appropriate instructions to select the proper paper size.
You shouldn't normally need to use this option.  To select postscript
level 1 use `--ps-level-one' and to select postscript level 2 use
`--ps-level-two'.  In the future this option may be used to turn on
more features.

9.5 Environment Information
===========================

By default Trueprint uses environment variables and the current
username.  You can force it to ignore these by using
`--ignore-environment'.  In practice this is only used when running the
tests during installation.  For the sake of completeness there is an
option `--use-environment'.

9.6 Debugging
=============

Trueprint has built-in debugging messages that can be useful for
tracking down problems.  The debugging messages are turned on with
`--debug=STRING', where STRING is a series of letter/digit pairs.  Each
letter turns on a set of debugging messages, and the corresponding
digit indicates the level of messages, with 1 indicating the least
number of messags and 9 turning on all messages.  The letter `@' can be
used to turn on all areas, so `--debug=@9' will turn on all messages.
Use `--help=debug' for details of what letters turn on what areas.
Note that this feature is not uniformly implemented - messages were
only typically added where they were needed.  Also note that messages
will not be generated in code prior to the code that sets the debug
string!

10 Options and Environment Variables
************************************

10.1 Miscellaneous options
==========================

`-D'
`--debug=STRING'
     set debug options to STRING

`-O STRING'
`--diff=STRING'
     if STRING is a file then print diffs between STRING and input file
     otherwise use as a prefix and print diffs

`-t STRING'
`--language=STRING'
     treat input as language.  Use -help languages for list.

`-U STRING'
`--username=STRING'
     set username for coversheet

`-H'
`--help'
     Type help information

`--help=STRING'
     Type specific help information.  Use `--help' for a list of
     possible STRINGs.

`-V'
`--version'
     Type version information

`-N'
`--use-environment'
     use environment variables

`--N'
`--ignore-environment'
     don't use values from environment, such as time, `$USER', etc.
     This is for test purposes, to make test results more reproducible.

10.2 Page furniture options
===========================

`-X STRING'
`--left-header=STRING'
     Specify string for left side of header.

`-x STRING'
`--left-footer=STRING'
     Specify string for left side of footer.

`-Y STRING'
`--center-header=STRING'
     Specify string for center of header.

`-y STRING'
`--center-footer=STRING'
     Specify string for center of footer.

`-Z STRING'
`--right-header=STRING'
     Specify string for right side of header.

`-z STRING'
`--right-footer=STRING'
     Specify string for right side of footer.

`-m STRING'
`--message=STRING'
     Message to be printed over page.

`-G NUMBER'
`--gray-bands=NUMBER'
     Emulate the old lineprinter paper with gray bands across each
     page.  The value of NUMBER gives the width of the bands and the
     gaps between them.

`-K'
`--headers'
     Include the header on each page.

`--K'
`--no-headers'
     Suppress the header on each page.

`-k'
`--footers'
     Include the footer on each page.

`--k'
`--no-footers'
     Suppress the footer on each page.

`-i'
`--no-braces-depth'
     Exclude the braces depth count.

`--i'
`--braces-depth'
     Include the braces depth count.

`-n'
`--no-line-numbers'
     Exclude the line number count.

`--n'
`--line-numbers'
     Include the line number count.

10.3 Text formatting options
============================

`-b'
`--no-page-break-after-function'
     Don't print page breaks at the end of functions.

`--b'
`--page-break-after-function'
     Print page breaks at the end of functions.

`-W'
`--no-intelligent-line-wrap'
     Wrap lines at exactly the line-wrap column.

`--W'
`--intelligent-line-wrap'
     Wrap lines intelligently at significant characters, such as a space

`-T NUMBER'
`--tabsize=NUMBER'
     Set tabsize (default 8).

`-E'
`--ignore-form-feeds'
     Don't expand form feed characters to new page.

`--E'
`--form-feeds'
     Expand form feed characters to new page.

`-p NUMBER'
`--point-size=NUMBER'
     Specify point size (default 10).

`-g NUMBER'
`--leading=NUMBER'
     Specify interline gap in points (default 1).

`-w NUMBER'
`--line-wrap=NUMBER'
     Specify the line-wrap column.

`--no-line-wrap'
     Turn off line-wrap.

`-l NUMBER'
`--page-length=NUMBER'
     Specify number of lines on a page, point size is calculated
     appropriately.

10.4 Print selection options
============================

`-C'
`--no-cover-sheet'
     Don't print cover sheet.

`--C'
`--cover-sheet'
     Print cover sheet.

`-A STRING'
`--print-pages=STRING'
     Specify list of pages to be printed.

`-a'
`--no-prompt'
     Don't prompt for each page, whether it should be printed or not.

`--a'
`--prompt'
     Prompt for each page, whether it should be printed or not.

`-F'
`--no-file-index'
     Don't print file index.

`--F'
`--file-index'
     Print file index.

`-f'
`--no-function-index'
     Don't print function index.

`--f'
`--function-index'
     Print function index.

`-B'
`--no-print-body'
     Don't print body of text.

`--B'
`--print-body'
     Print body of text.

10.5 Page format options
========================

`-I'
`--no-holepunch'
     Don't leave space for holepunch at the side of each page.

`--I'
`--holepunch'
     Leave space for holepunch at the side of each page.

`-J'
`--no-top-holepunch'
     Don't leave space for holepunch at the top of each page.

`--J'
`--top-holepunch'
     Leave space for holepunch at the top of each page.

`-o p'
`--portrait'
     Print using portrait orientation.

`-o l'
`--landscape'
     Print using landscape orientation.

`-S 1'
`--single-sided'
     Print single-sided.

`-S 2'
`--double-sided'
     Print double-sided.

`-1'
`--one-up'
     Print 1-on-1 (default).

`-2'
`--two-up'
     Print 2-on-1.

`-3'
`--two-tall-up'
     Print 2-on-1 at 4-on-1 pointsize.

`-4'
`--four-up'
     Print 4-on-1.

10.6 Output options
===================

`-d STRING'
`--printer=STRING'
     Use printer STRING.

`-P STRING'
`--printer=STRING'
     Use printer STRING.

`-s STRING'
`--output=STRING'
     Send output to filename STRING; use - for stdout.

`-c NUMBER'
`--copies=NUMBER'
     Specify number of copies to be printed.

10.7 Environment Variables
==========================

10.7.1 TP_OPTS
--------------

Specify options.  These options override any default options including
language defaults, but are overridden by command line options.

10.7.2 TP_DIFF_CMD
------------------

Specify the diff command to be used.  The command must produce output
in the same format as the classic Unix diff.  This variable can be used
to add flags to the diff command used, for example to make diff ignore
whitespace.

10.7.3 TP_PRINT_CMD
-------------------

Specify the print command.  The default is lpr.  If this is set then it
should be set to a command that takes standard input.  If this is set
then the destination and number of copies have no effect, i.e. there is
no mechanism to pass these values to your print command.  If you set
this to /bin/cat then the postscript output will appear on stdout.

10.7.4 TP_PRINTERS_FILE
-----------------------

Specify the printers file.  The default is the printers file that was
initially configured when trueprint was installed.  This can be used to
test out a new printers file.