PSIO -- The Postscript I/O package. The PSIO interface is used to format a block of text as Postscript output on a page of a given size (Letter, Legal, A4 or B5). Once initialized by a ps_open() call, programs can set various options related to the page size or properties, preferred fonts, etc. Output is begun with a call to the ps_write_prolog() routine to initialize the PS prolog. Afterwards, text may be fed to a buffer using ps_deposit() to fill the output page to a right justified margin, inserting linebreaks where needed. Other routines permit specific linebreaks or text positioning as required. 1) PSIO Interface Summary ------------------------- include ps = ps_open (fd, default_footer) ps_setfont (ps, font) ps_page_size (ps, page) ps_font_size (ps, font_size) ps_header (ps, ledge, center, redge) ps_footer (ps, ledge, center, redge) ps_setmargins (ps, left, right, top, bottom) ps_write_prolog (ps) ps_close (ps) ps_xpos (ps, xpos) ps_ypos (ps, ypos) ps_indent (ps, nchars) ps_testpage (ps, nlines) ps_deposit (ps, line) ps_linebreak (ps, fill_flag) ps_pagebreak (ps, fill_flag) ps_newline (ps) ps_output (ps, line) ps_center (ps, line) ps_rightjustify (ps, text) width = ps_textwidth (ps, string) pos = ps_centerpos (ps, text) pos = ps_rjpos (ps, text) 2) PSIO Interface Description ----------------------------- ps = ps_open (fd, default_footer) Initialize the PS structure with default page size and margins, set output file descriptor. Returns the PS struct pointer initialized with defaults. If the 'default_footer' int flag is enabled a default footer containing the string "NOAO/IRAF" in the bottom left corner, the IRAF version string in the center, and the page number in the bottom right will be created for each page. Otherwise only a page number will appear unless a different footer is defined with the ps_footer() command. ps_setfont (ps, font) Set the current font to be used. Allowable values for 'font' are set in the include file as define F_ROMAN 1 # times-roman font define F_ITALIC 2 # times-roman italic font define F_BOLD 3 # times-roman bold font define F_TELETYPE 4 # fixed-width font define F_PREVIOUS 5 # previous font The default font will be a 10-point Times-Roman. ps_font_size (ps, font_size) Set the font size in points to be used. Font sizes are not changeable once the interface has been opened so this routine must be called before the Postscript prolog is written. ps_page_size (ps, page) Set the default page size to be used. Allowable values for 'page' are set in the include file as define PAGE_LETTER 1 # US Letter (612x792 @ 300 dpi) define PAGE_LEGAL 2 # US Legal (612x1008 @ 300 dpi) define PAGE_A4 3 # A4 size (595x850 @ 300 dpi) define PAGE_B5 4 # B5 size (524x765 @ 300 dpi) The default page size will be US Letter but can be overridden in the environment by defining a 'pspage' variable as e.g. cl> reset pspage = "legal" ps_header (ps, ledge, center, redge) Set header text tags. The header will appear on each page, empty strings are allowed to indicate no text is to be written in that part of the header. ps_footer (ps, ledge, center, redge) Set footer text tags. The footer will appear on each page, empty strings are allowed to indicate no text is to be written in that part of the header. A running page number will always be written to the 'redge' field unless a non-empty value is defined, a white- space character can be used to indicate no text should be written to that part of the footer. ps_setmargins (ps, left, right, top, bottom) Set/Change page margins from defaults set by ps_open(). Values are defined in units of inches given as a floating point number. ps_write_prolog (ps) Write the PS prolog given the current postscript struct. This initializes a flag preventing subsequent changes from taking effect once called. ps_close (ps) Close the struct, flush the page, and free memory ps_xpos (ps, xpos) ps_ypos (ps, ypos) Set current X or Y position on page ps_indent (ps, nchars) Set a temporary indenture of the page from the permanent left margin. Value is given as a number of fixed-width characters, negative values are not permitted, a value of zero may be used to reset to the left margin. ps_testpage (ps, nlines) Test whether the output is within the specified number of line of the end of the page, if so do a page break. This routine can be used to force a page break when a certain number of lines is to be reserved to e.g. keep a group of text together on a page. ps_deposit (ps, line) Deposit a line of text to the output buffer. When the output width exceeds the permanent right margin the line is flushed to the output file and the x-position reset to the current left margin, the y-pos is moved to the next line determined by the font size. Remaining words in the line buffer to added to the next line buffer. Width of the line is computed from the width of each word plus a space char, including font changes. The line buffer outputs each word plus spacing individually, font changes are handled in the output routine. ps_linebreak (ps, fill_flag) Break the current line regardless of whether it has been filled. The int 'fill_flag' says whether to fill the current line to be right justified. May be called to simply flush the current line buffer. ps_output (ps, line, fill_flag) Output the given line and break, fill to be right justified if the int 'fill_flag' is set. ps_center (ps, line) Center the line on the page and break. ps_rightjustify (ps, text) Right justfify text on the current line. width = ps_textwidth (ps, string) Get the width of the given string. Width is returned in terms of Postscript pixels assuming a 72 point, 300 dpi page. pos = ps_centerpos (ps, text) pos = ps_rjpos (ps, text) Get the X position of the centered and right-justified strings. 3) Postscript Prolog -------------------- Example prolog for the postscript output. The actual prolog is created based on parameters specified such as the page size, header/footer text, etc. Lines with '***' indicate those which are set dependent upon PS structure values. %!PS-Adobe-1.0 %%Creator: IRAF postscript translator %%CreationDate: Wed May 19 14:34:47 1999 %%Pages: (atend) %%DocumentFonts: (atend) %%EndComments %%BeginProlog /inch { 72 mul } def % 72 points per inch /PL { 792 } def % set page height *** /FtrY { 20 } def % footer Y position /HdrY { PL 40 sub } def % header Y position /xOrg 72 def % 1 inch left margin *** /yOrg 720 def % 1 inch top margin *** /yDelta 12 def % line spacing *** /Line 1 def % line number /Page 0 def % page number /pnum 4 string def % sizeof page number cvs buffer /res 10.00 def % pixel resolution factor *** /TA { newpath % Draw a box around our text xOrg yOrg moveto % area as a debugging procedure. 0 -664 rlineto % *** 467 0 rlineto % *** 0 664 rlineto % *** closepath stroke } bind def /FS { findfont exch scalefont } bind def % find and scale a font /Fonts [ % create an array of fonts 10 /Times-Roman FS % *** 10 /Times-Bold FS % *** 10 /Times-Italic FS % *** 10 /Courier FS % *** 12 /Times-Bold FS % *** ] def /R { Fonts 0 get setfont } bind def % set roman font /B { Fonts 1 get setfont } bind def % set bold font /I { Fonts 2 get setfont } bind def % set italic font /T { Fonts 3 get setfont } bind def % set teletype font /H { Fonts 4 get setfont } bind def % set header font /NL { Line 1 add SL } bind def % newline /H { res div currentpoint exch pop moveto } def % horizontal position /S { exch H show } bind def % show /SL { /Line exch def % set line position xOrg yOrg Line yDelta mul sub moveto } bind def /BP { % Begin page (header). xOrg HdrY moveto R (TEE \(Nov97\)) show % write the header *** 280 HdrY moveto R (system) show % *** 485 HdrY moveto R (TEE \(Nov97\)) show % *** 1 SL R } bind def /EP { % End page (footer). /Page Page 1 add def % increment page number xOrg FtrY moveto R (NOAO/IRAF) show % write the footer *** 250 FtrY moveto R (IRAF V2.11 May 1997) show *** 530 FtrY moveto R Page pnum cvs show *** showpage % show the page } bind def %%EndProlog %%Page: 1 1 %----------------------------------------------------------------------------- initgraphics TA BP ...... EP ...... % end of listing %%Trailer %%DocumentFonts: Times-Roman Times-Bold Times-Italic Courier %%Pages: *** 4) Example Program ------------------ include include task pstest = t_pstest # PSTEST -- Test the PSIO package. This test program pretty-prints a file # with a header message and page number suitable for output to a printer. procedure t_pstest() pointer ps int fd, ip, op char fname[SZ_FNAME], date[SZ_TIME], line[SZ_LINE], outline[SZ_LINE] pointer ps_open() int open(), getline() long clktime() begin # Get the file to format and date string. call clgstr ("filename", fname, SZ_FNAME) call cnvtime (clktime(0), date, SZ_TIME) # Open the file. fd = open (fname, READ_ONLY, TEXT_FILE) # Initialize the PSIO interface. ps = ps_open (STDOUT, NO) call ps_header (ps, fname, "NOAO/IRAF", date) call ps_footer (ps, "PSIO Test Page", "", "") call ps_write_prolog (ps) # Output the text in a fixed-width font. call ps_setfont (ps, F_TELETYPE) call ps_linebreak (ps, NO) while (getline (fd, line) != EOF) { if (line[1] == EOS) { # Simple break on a newline. call ps_linebreak (ps, NO) } else { # Detab the line. ip = 1 op = 1 while (line[ip] != EOS && op <= SZ_LINE) { if (line[ip] == '\t') { repeat { outline[op] = ' ' op = op + 1 } until (mod(op,8) == 1) ip = ip + 1 } else { outline[op] = line [ip] ip = ip + 1 op = op + 1 } } outline[op] = EOS # Output the line and a newline. call ps_output (ps, outline, NO) call ps_newline (ps) } } # Close the file and PSIO interface. call close (fd) call ps_close (ps) end