Using TEX with NSF FastLane

Gary E. Walker

1  PDF Specifications

1.1  PDF Version

The National Science Foundation requires that all PDF documents submitted electronically via the FastLane system be formatted compliant with PDF version 1.2 (Adobe Acrobat 3.0x). Documents in PDF version 1.3 (Adobe Acrobat 4.0x) are incompatible with NSF's software and may not be uploaded to FastLane.

1.2  Font Types and Embedding

Documents electronically submitted to FastLane should employ Type 1 (sometimes called PostScript) fonts, exclusively if possible. Fonts should be embedded. The requirement for font embedding is for your own protection as your PDF documents will be processed on NSF's servers, and may be viewed on any number of different computing platforms which may not have appropriate fonts to substitute for the fonts you have used. Type 3 fonts, which cannot be embedded in PDF documents, should not be used.

1.3  Recommended Fonts

NSF FastLane recommends the use of the Bluesky Computer Modern fonts package which includes Computer Modern, associated Symbol and Cyrillic fonts, and the AMS Mathematical Symbol fonts. The Bluesky font package is freely redistributable, and is included with most TEX packages.

2  Creating PostScript Files with TEX and dvips

2.1  What is dvips?

dvips1 is a program which converts the standard TEX "device independent'' file format to PostScript. It is included with most TEX distributions and is generally used to format DVI documents for printing by piping the output to the printer daemon2 thusly: 
        dvips foo.dvi | lpr
In creating PDF files, however, we are not concerned solely with sending information to a PostScript printer. The PostScript files we create must have certain qualities in order to be made into PDFs compatible with FastLane's software.

2.2  dvips Configuration

Like most Unix applications, dvips is configured by passing it arguments at runtime. This can be automated by using dvips config files (stored, as convention would have it, in $TEXMF3/dvips/config) named by the convention config.xx where xx is a file type such as .ps or .pdf. The config file options are passed to dvips with the -P flag thusly: 
        dvips -P xx foo.dvi
In the above example, xx is the extension of the config file we wish to use, config.xx

2.3  The config.pdf File

Most newer TEX distributions include a config.pdf file in the .../dvips/config directory. This file is configures dvips' PostScript output for making good PDF files.

2.3.1  Finding the config.pdf File

First, determine if your system already has this file installed4: 
        [melmoth@bettie melmoth]$ whereis texmf
        texmf: /usr/share/texmf
        [melmoth@cc456701-a melmoth]$ find /usr/share/texmf -name config.pdf
        /usr/share/texmf/dvips/config/config.pdf
        [melmoth@bettie melmoth]$
If you don't have the file, don't worry, you can construct one of your own fairly simply by consulting the section "Creating Your Own config.pdf File''.

2.3.2  Structure of the config.pdf File

This section will examine and comment on the information in the config.pdf file. In order to create good PDF files, your postscript must be generated using the Type 1 fonts. Fonts are selected by choosing which fontmap5 files dvips should refer to. The lines which handle this in the config.pdf file look like this: 
        p +bsr.map
        p +bsr-interpolated.map
        p +hoekwater.map
These are the fontmaps for the Bluesky and Hoekwater Type 1 fonts. You may add other fontmaps if you wish, but only Type 1 fonts should be used. If you're not sure of which fontmaps refer to Type 1 fonts, leave these lines alone6.

The character shifting option (G) is compatible with the Bluesky fonts. If no changes are made to the above fontmap lines, it should not cause problems. If you wish use the BaKoMa fonts, comment it out by changing 

G
to 
%G
There are two sections of the config.pdf file which deal with the resolution of the PostScript file as a whole and of embedded bitmaps. The first section looks like this: 
% Default resolution. Attempt to make `resolution independent'.
% Resolution set to 8000dpi (could be as high as 10000).

D 8000
You should not need to make adjustments to this entry as 8000dpi is approximately 111 times finer than screen resolution, and about 13 times greater than the highest resolution at which the document is likely to be printed.

The other section dealing with resolution, looks like this: 

% Last resort sizes.
% If you accidentally include a bitmapped pk font, it will probably go
% at 600dpi.

R 300 600
This section controls the resolution with which fonts (such as the occasional type 3 font which finds its way into your document as part of an EPS image) will be rendered. You should not need to change this either, as your documents are unlikely to be printed at a resolution higher than 600dpi. If you have legibility problems with your EPS graphics, try raising this to: 
R 600 1200

2.3.3  Creating Your Own config.pdf File

dvips searches for configuration files in paths selected by an environment variable which, by default, includes the current user's home directory. By creating a configuration file of your own and placing it in your home directory, you can get around the fact (assumed by this section) that you do not have a config.pdf file.

Start by opening a document called config.pdf in your favorite text editor7. To that file, add the following lines8: 

m 6000000 o
D 8000
p +bsr.map
p +bsr-interpolated.map
p +hoekwater.map
R 300 600
G
h tex.pro
h alt-rule.pro
Now save the file in your home directory. Provided that your system has the appropriate fonts9 installed, this configuration file should work fine.

2.4  Installing Font Packages For Use With dvips

The installation of font packages and creation of new font maps is an involved process. It will be addressed in this document at a later time.

3  Converting PostScript to PDF

Important Notice: The current versions of both Ghostscript10 and Adobe Acrobat Distiller (6.01 and 4.05 respectively) have been known to produce PDF files which, while individually compatible with FastLane, cannot be properly compiled by FastLane's server processes. At this time, only pdftex and Adobe Acrobat Distiller 3.0x are recommended for conversion of TEX documents to PDF.

Converting your PostScript document to PDF with Distiller is relatively simple. If your postscript file was called foo.ps you would use the following command line: 

distill --embedallfonts on --maxsubsetpct<99>[foo.ps]
This should produce a PDF file compatible with FastLane.

4  Creating PDF files with pdftex

Newer distributions of LATEX and teTEX include a utility called pdfTEX which converts your TEX and LATEX source files directly into PDF. Use of this utility is encouraged, but older versions of this software may not produce PDF files compatible with FastLane.

4.1  Determining the pdftex Version

To check the version of pdftex you have, do the following: 
[melmoth@bettie melmoth]$ pdftex --version
pdfTeX (Web2C 7.3.1) 3.14159-0.13d
kpathsea version 3.3.1
Copyright (C) 1999 Han The Thanh, Petr Sojka, and Jiri Zlatuska.
Kpathsea is copyright (C) 1999 Free Software Foundation, Inc.
There is NO warranty.  Redistribution of this software is
covered by the terms of both the pdfTeX copyright and
the GNU General Public License.
For more information about these matters, see the files
named COPYING and the pdfTeX source.
Primary author of pdfTeX: Han The Thanh, Petr Sojka, and Jiri Zlatuska.
Kpathsea written by Karl Berry and others.

[melmoth@bettie melmoth]$
If the Web2C11 and kpathsea12 versions you see are lower than the ones in the above example, you should either upgrade your version of TEX13, or use pdftex at your own risk14.

4.2  Using pdfTEX

Use of pdfTEX is fairly straightforward15. The main thing you have to consider is whether you wish to call the pdftex or pdflatex program. If you have used LATEX macros, use pdflatex. If you have confined yourself to plainTEX macros, use pdftex. Both programs need the filename of the TEX source document you wish to convert as an argument. For instance, if you named your LATEX source foo.tex you would use: 
[melmoth@bettie melmoth]$ pdflatex foo.tex
If you get errors, try switching to scroll mode. If that works, be sure to check your PDF carefully to make sure it looks ok. If you get fatal errors, check your TEX source. pdfTEX is rather precise about what errors in your source it is willing to accept. The PDF you get from this process should be compatible with FastLane (the fonts are embedded and subsetted by default, and type 1 fonts are used exclusively if possible).

5  Frequently Asked Questions

5.1  I am using a WYSIWYG TEX editor such as TEX tures. What should I do?

Consult your software's documentation and technical support. They should be able to help you comply with NSF's restrictions.

5.2  Why do I have to use type 1 fonts? My document looks fine on my computer.

Your document looks fine on your computer because it was created there. When it is rendered for people at NSF or for reviewers who are responsible for making the recommendation that your proposal be funded or not, it will not be on your computer. It will not have direct access to whatever fonts were used in its creation. As a result, it will be rendered using bitmaps rather than mathematically correct instructions. For example, the figures below were captured from Adobe Acrobat Reader at equal magnifications. The first figure shows a document with type 3 fonts rendered by Reader. The second shows a document using type 1 fonts. Because the type 1 fonts are stored as mathematical outlines rather than bitmaps, there is no pixelation, and anti-aliasing (the use of semi-opaque pixels in between opaque ones to try and simulate a diagonal line of greater resolution than is afforded by the available pixels) is much more effective.

Figure
An example of a document with type 3 fonts.

Figure
An example of a document with type 1 fonts.

It is left to the user to decide which of these documents he or she would rather a reviewer saw16.

5.3  Where can I download the Bluesky fonts?

The Bluesky Computer Modern and AMS Math Symbol fonts can be downloaded from ftp://tug.ctan.org/tex-archive/fonts/cm/ps-type1/bluesky/17.

Footnotes:

1 dvips, oddly enough, does not follow the usual UNIX naming convention for such conversion utilities of extension2extension.

2 Similar to the function of the groff/troff utility.

3 TEXMF is an environment variable which contains the path of the "texmf'' directory.

4 Examples in this document are from a Red Hat Linux 6.1 system. Your own system may vary considerably, particularly if you use a non-TDS (TEX Directory Structure. See http://www.tug.org/tds/) compliant distribution.

5 The fontmap (*.map) files for dvips are also stored in .../dvips/config.

6 It is worth noting here that wise old hackers make backups of system files before they start fooling around with them.

7 I used pico for the examples, but that doesn't mean you have to.

8 Yes, some of these weren't discussed above. The reason that they were not discussed above is that you shouldn't mess with them unless you know exactly what you're doing. If you know exactly what you're doing, this document is basically useless to you after the first section anyway.

9 If you have the Bluesky fonts, but not the Hoekwater ones, just comment out the appropriate line.

10 This is expected to be fixed in the next Aladdin Ghostscript release.

11 Web2C is the GNU/FSF TEX implementation. See http://www.tug.org/web2c/

12 kpathsea is an extremely useful library for path searching by K. Berry.

13 Web2C distributions of TEX are available at http://www.tug.org/web2c

14 Yes, 3.14159 is an approximation of pi. See http://www.tex.ac.uk/

15 If you are reading the PDF version of this document, it was generated with pdfLATEX

16 The difference is not so dramatic in these images (because they have lost a fair amount of definition thanks to JPEG compression), but is quite noticeable in a PDF.

17 http://www.ctan.org is the Comprehensive TEX Archive Network and is mirrored all over the place. It is one of the best resources for TEX related files, fonts, document classes, etc.