A2X(1)

NAME
a2x - convert and format ascii for printing to various devices

SYNOPSIS
a2x [options] [files]

DESCRIPTION
A2x.ps is a PostScript program to format ascii data in various ways. There is also a UNIX shell script called a2x, which arranges a2x.ps and a specified input to produce a PostScript program as output. It also supports use of Ghostscript's interpreter gs. This way, you can use a2x.ps with a real PostScript printer or produce output for any device supported by Ghostscript.

A2x.ps is intended to be used with a2x, so this man page decribes just that.

With a2x you may switch between portrait and landscape mode, suppress even or odd pages, choose any number of columns per page, clip output to columns (truncate long lines), use german umlauts, choose fonts and their sizes (or lines per page), preview in an X window, handle tabs and backspaces, print nroff-formatted man pages and more.

A2x always writes to stdout. If no files are given, a2x reads its input data from stdin, so you may use it as a filter.

OPTIONS

[-dev DEV]
With this option you can specify a target device other than the default
    target device. DEV may be any Ghostscript device name or ps. You should specify your individual default device in a2x as described in the INSTALLATION section below.

-a4, -letter, -legal
    choose upon paper sizes. The default is -a4. Again, change this to your needs in a2x as described in the INSTALLATION section below.

-o  print odd pages only.

-e  print even pages only.

-p  print in portrait mode. This is the default.

-l  print in landscape mode (2 up).

    [-c n]
Specify the number
    n of columns per page. The default is 1-column in portrait mode, 2-column in landscape mode.

    [-title, -title= name]
The -title option  makes the filename being printed on (top left)
    of each page. By default, this is not done. Using [-head= name] causes name to be used instead of the file's name. (This is useful when reading from standard in.)

-date
    makes the current date being printed on (top right) of each page. The default is not to do this.

-num
    This one makes the pagenumber being printed on (center bottom of) each page. The default is not to print pagenumbers.

    [-s n]
Yes, this sets the fontsize to
    n pt. The default is 10pt for portrait, 8pt for landscape.

-bs Turn on backspace handling.

    [-t n]
Set tab width to
    n. The default is 8.

    [-n n]
Choose
    n lines per page. A corresponding fontsize is computed by a2x.ps.

    [-f font]
Using the
    -f option you may choose the Postscript font font to be used by a2x.ps. The default is Courier.

-ger, -us
    With the -ger option, a2x.ps reencodes characters to allow german umlauts. Anyway, this is done by default. Suppress it with -us, which actually causes no reencoding, or change the default in a2x.ps.

-man
    Print nroff formatted man page. This selects a fixed font, 66 lines per page and turns backspace handling on.

-pagecount
    Finally, this option suppresses any output. It just prints the number of pages it would have had to standard out.

INSTALLATION
Installing a2x is easy.

First, assume, that you have Ghostscript or you don't have a PostSript printer. Now, if you don't have Ghostscript, get it. It is available via anonymous ftp at many sites. Once, you have installed it successfully, go on like this:

(1) Type gs -h on your command line. Ghostscript should give you a list of available devices. If your printer is in that list, you are lucky. If not, get a new one (one in the list, of course).

(2) Copy a2x.ps to a directory, where you like it to live (if you are superuser, Ghostscript's home would be a nice place, usually something like /usr/local/lib/ghostscript, or similar).

(3) Copy the file a2xshell.ps to the same directory.

(4) Now, go into a2x and change the definition of the variables Device and Paper. Simply assign to Device the Ghostscript device name of your printer and one of the papersizes a4, letter and legal to variable Paper. Also, look for the variable A2X_PATH in a2x. Assign to it the directory path, where you just copied a2x.ps in step (2).

(5) You may also want to specify some interactive devices. They are given by the InteractiveDevices variable. For these, gs waits for you to press return after each page. They should be screen devices like the x11 device.

(6) Finally, copy a2x to a directory, where your shell can find it (eg any directory mentioned in your PATH variable).

Next, assume you do have a PostScript printer. If you installed a2x for use with Ghostscript, you are done. Use the -dps option to generate PostScript output or make ps your default device as described above. If you don't have Ghostscript and don't want to install it, then simply follow steps (2), (4) and (6) above.

CUSTOMIZATION
To change default settings other than the ones described above, go into a2x.ps and check the definitions in the procedure /A2xdefaults. If you would like some characters to be reencoded, go to the definition of /fontvec in a2x.ps. The comments there should explain how to achieve your desired encoding. The encoding choice is controlled by the variable /country, which is simply the index of the encoding in /fontvec. It is set in /A2xdefaults (and via the -ger and -us options). If you do your own country specific reencoding, please email it to me. I would then include it into the next version of a2x.

EXAMPLES
Assume, you have a working lpr command and want to print file abc.xyz. To simply print this file "as is", use
  a2x abc.xyz | lpr However, you can do more. To preview the output in an X window, in landscape mode, using the default 2-column style, type
  a2x -dx11 -l abc.xyz I know, you'd like the filename and todays date being printed on top of each page. Also, pagenumbers would be nice. BTW, 9pt, instead of the default 8, would be possible. Say
  a2x -dx11 -l -title -date -num -s9 abc.xyz Yes, viewing the first few pages, this seems to be ok. Now, abc.xyz is quite large. You would like to know, how many sheets of paper it would take to print it this way. Get it with
  a2x -l -title -date -num -s9 -pagecount abc.xyz Oooh, thats a lot... Better, to print it double sided. First, all the odd pages with
  a2x -o -l -title=abc -date -num -s9 abc.xyz | lpr, and the rest by replacing the -o option by -e. Addititionally, the string abc comes out on top of each page, instead of abc.xyz. Now, you'd like to list all the TeX-files in the current directory. Use UNIX's find and a2x. To get it formatted into Times-Roman font, 3-columns, do a
  find . -name "*.tex" -print| a2x -c3 -fTimes-Roman | lpr Finally, to get this man page on one sheet of paper, do
  nroff -man a2x.1 | a2x -man -l -o | lpr
  nroff -man a2x.1 | a2x -man -l -e | lpr

BUGS
I have tested a2x with Ghostscript 2.6.1 and a DECLaser 1152, only. Send bug reports via email to the authors address, please. With the -dps option, a2x produces PostScript output in which the character ^A (ascii 1) is used as a special symbol. For this reason, a2x filters all ^A's from your input. As a consequence, reencoding this character (see the CUSTOMIZATION section) will have no effect.

AUTHOR
Christoph Beck <beck@jack.rhein-main.de>