TSetterDoc.Tioga
Copyright c 1985 by Xerox Corporation. All rights reserved.
Last Edited by: Michael Plass on February 21, 1984 10:26 am
Last Edited by: Tim Diebert on May 23, 1984 4:56:06 pm
Last Edited by: Subhana, May 31, 1984 3:27:52 pm PDT
Last Edited by: Rick Beach on January 26, 1985 3:26:11 pm PST
TIOGA TSETTER
CEDAR 5.2 — FOR INTERNAL XEROX USE ONLY
Tioga TSetter
Typesetting Tioga Documents
Michael Plass and Richard J. Beach
© Copyright 1984 Xerox Corporation. All rights reserved.
Abstract: The TSetter formats Tioga documents for printing. The Tioga typesetter knows how to format several different kinds of document content, including text, typographic rules, Press files, and AIS sampled image files. There is an interactive tool for driving the Tioga typesetter and for sending formatted files to print servers. There is another tool, PressScreen, for formatting the contents of the screen. The program interface to the TSetter permits clients to format parts or the whole Tioga document for formatting.
Keywords: typesetting, Tioga documents, Press files, AIS files, sampled images, typographic rules, TSetter, PressScreen, print servers
XEROX  Xerox Corporation
   Palo Alto Research Center
    3333 Coyote Hill Road
   Palo Alto, California 94304

For Internal Xerox Use Only
The TypeSetter Tool
In the glorious future, Tioga will have an interactive typesetter that will let you make incremental revisions to a typeset document to adjust pagination, page layout, and other details before actually printing it. Work has started on this, but until it's available, the current typesetter will do a more than adequate job of letting you print your files.
The TSetter tool provides a convenient way of driving the Tioga typesetter. Start it up by typing "TSetter" to the command tool. The typesetter icon will come up showing the name of the print server it is "connected" to; this name can be specified in your profile under the heading Hardcopy.PressPrinter, or as the first argument on the TSetter command line. Using "*" instead of a server name will cause TSetter to display the press file on your screen using ShowPress instead of sending it off to be printed.
The remainder of the TSetter command line is taken as a list of file names to be printed. If this list is non-empty and the files are succesfully printed before you touch any of the tool's buttons, the tool will quietly go away.
When you open the typesetter icon, you will see the menu
Pause Stop StopSending Get Print All < Screen > New
plus a fill-in field labeled Documents:. The normal way to use the typesetter is to select the viewer or file name, and click Get to add the document name to the queue. Then click Print to start the typesetter up; if all goes well, the only other thing you have to do next is to walk over to the printer and pick up your output.
You can put several documents in the queue before starting up the typesetter, and go do something else while it is working away. The queue is shown after the Documents: button and is in fact editable; it is a good idea to click Pause before editing, though, to keep the typesetter from taking the queue out from under you. Clicking All instead of Print funnels the whole queue into one big press file, which avoids a lot of header pages if you want to print many small files.
To print the bitmap on the screen, use the Screen button. The "<" button will print just the left half of the screen, the ">" the right. The half-screen output may be printed on a Spruce printer (e.g., Clover or Menlo) if it is not too complicated; otherwise, use a full Press printer (such as Stinger, Quoth, or Lilac).
Hitting Stop will bring the typesetter to a halt.
Hitting StopSending will abort any transmission to a print server.
Destroying a tool will not stop it; it will just finish running and then go away.
If you try to typeset a press file, it will just get sent to the server without modification. After it is successfully transmitted, it will be deleted if its name ends in a "$".
To make a TSetter tool that sends its output to a different place, type the server name somewhere, select it, and click New. If the selection is less than two characters long, the resulting tool will be called TSetter, and will just create a press file without trying to send it anywhere (thus you cannot make a ShowPress TSetter with the New button; use the TSetter * command).
The name of the press file is generated by appending ".press" to the input file name, unless the input file had a name of the form xxx.tioga; in the latter case the press file will be named just xxx.press. If the source file is local, the press file will inherit the directory structure. The press file resulting from a remote file will not have any subdirectories.
It is OK to run multiple typesetter tools at the same time.
If you want to print multiple copies of you document, change the Copies field near the bottom of the TSetter viewer. This number is reset to 1 after each file is transmitted to a server, to keep you from wasting a lot of paper by forgetting to reset it.
The Temporary Press Files button is followed by a Boolean value. If this is TRUE, the typesetter will create press files with names that end in "$", so that they will be deleted after they are successfully transmitted. Clicking the button toggles the Boolean. The initial setting of this flag is controlled by the user profile entry Hardcopy.TemporaryPressFiles.
The feedback from the typesetter tool is logged. You can see the log by making the tool bigger and scrolling the appropriate subwindows. The top subwindow is for the formatting process and the bottom subwindow is for the spooling process.
Multiple column and landscape output of a document is possible. Look at [Indigo]<Cedar®>Styles>*Print.style (where ® is the current Cedar release number, e.g. 5.2) to see if there is a style there that will let you do what you want. If not, let TiogaImplementors^.PA know. (You are welcome to try writing your own print styles, but be warned that they may not work in the future, as incompatible changes in this mechanism are planned.) As an example, you can get two column landscape output by setting the style on your document to be "TwoColumnLandscapeCedar". (For now, you must make sure all the styles you need are stored locally on your disk.)
TSetter Command
To drive the typesetter from a command tool, type
TSetter Clover foo.mesa bar.tioga
to the command tool. This will create a new tool aimed at Clover (substitute your favorite printer here), and put the list of files in its queue. The file names are expanded to fullnames using the working directory and star expansion before being put in the queue. If all the files are succesfully printed before you touch any of the tool's buttons, the tool will quietly go away when it is done. There are no switches and the server name is positional; use Alias if this is too much typing for you.
TSViewer Interface
To drive the typesetter from a program (or the command tool), there is a client interface called TSViewer that lets you create a TSetter tool and simulate clicks on its buttons.
TSExtras Interface
For more exotic formatting requirements of clients of Tioga, try the TSExtras interface which provides interfaces for formatting a Tioga viewer or individual nodes of a Tioga document.
Including press files as illustrations
The TSetter has a somewhat primitive method for including press files as illustrations. Suppose you have a press file named foo.press that contains an illustration that you would like included in the printed version of a Tioga document. Here's what you do:
1. Make sure that foo.press consists of one page, and contains just the stuff you want to include, already the right size (i.e., TSIncludePress can't scale or clip).
2. Print foo.press so you can measure it.
3. Get out your ruler, and draw a box around the part of foo.press that you want to include.
4. Put a node in the tioga document something like the following:
foo.press leftMargin: 1 in, topMargin: 1 in, width: 2.125 in, height: .75 in
where the leftMargin, topMargin, width, and height are the numbers you measured off of the printed version of foo.press.
Caps vs. lower case are ignored; the keyword parameters may be in any order; use spaces, tabs, CRs, commas, and semicolons freely; units may be pt, in, bp, cm, or mm.
5. Get out the EditTool, and enter the following
Property name: ArtworkClass
Property Value: IncludePress
Better get the capitalization right here, I think.
6. Select the node you added in step 4, and click "Set" in the "Property name:" window of the EditTool.
7. Start the TSetter.
8. Typeset the document as usual, and if all goes well, you will get what you want.
What can go wrong:
Error reporting is somewhat primitive, but you will surely notice when somthing is amiss:
Uncaught signal:
From any of the following:
The press file name might be wrong.
Something may be wrong with the format of the node you created in step 4 above.
The press file might be garbage.
In any of these cases, click "Abort" in the action area, (after which you may destroy it), fix what is wrong, and try again.
The text of the node is printed instead of the illustration:
You may have goofed in steps 5 or 6.
The illustration is in the wrong place:
Check the postiioning information supplied in step 4.
The illustration is garbled:
May be a bug. Contact the implementor.
Including sampled images as illustrations
The typesetter provides a mechanism for including sampled images (AIS files) as illustrations. Suppose you have an AIS file named foo.ais that contains an illustration that you would like included in the printed version of a Tioga document. Here's what you do:
1. Put a node in the tioga document something like the following:
foo.ais width: 2.125 in, height: 3.75 in, indent: 1 in, screen: 85
where the dimensions specify the size and placement of the image. Indent may be left out; it defaults to zero. If either the width or the height is not specified, its value is calculated to make the aspect ratio come out right; this is usually what you want. Another way to specify the final size is to omit both width and height, and specify the dotSize instead; this is useful if you really want to force a particular resolution in the output. In particular, if the AIS file is a bitmap such as one created with the PressScreenTool, using a dotSize of 0.32 mm will allow the Press file to be printed on a Spruce printer. Screen may also be left out; it defaults to 85. Screen indicates the half-tone screen frequency to use in making the image.
Caps vs. lower case are ignored in parsing the parameters; the keyword parameters may be in any order; use spaces, tabs, CRs, commas, and semicolons freely; units may be pt, in, bp, cm, or mm.
2. Get out the EditTool, and enter the following
Property name: ArtworkClass
Property Value: IncludeAIS
Better get the capitalization right here, I think.
3. Select the node you added in step 4, and click "Set" in the "Property name:" window of the EditTool.
4. Start the TSetter.
5. Typeset the document as usual, and if all goes well, you will get what you want.
What can go wrong:
Error reporting is somewhat primitive, but you will surely notice when somthing is amiss:
Uncaught signal:
From any of the following:
The AIS file name might be wrong.
Something may be wrong with the format of the node you created in step 4 above.
The AIS file might be garbage.
In any of these cases, click "Abort" in the action area, (after which you may destroy it), fix what is wrong, and try again.
The text of the node is printed instead of the illustration:
You may have goofed in steps 2 or 3.
The illustration is in the wrong place:
Check the postiioning information supplied in step 4.
The illustration is garbled:
May be a bug. Contact the implementor.
Defining Typographic Rules
A third ArtworkClass implementation is provided for inserting typographic rules, rectangular black areas usually thin lines, into documents. There is a simple scheme for indicating the thickness and lengths of rules, along with some reasonable defaults.
1. To get a thin rule across the page, put a node in your document that looks like:
---------------
where there must be at least one minus sign.
2. Open the EditTool, and enter the following
Property name: ArtworkClass
Property Value: Rule
Get the capitalization right here.
3. Select the node you added in step 1, and click "Set" in the "Property name:" window of the EditTool.
To get other thicknesses of rules, there are some predefined weights:
- (minus sign) gives a 0.4 point rule (a thin line)
(em dash) also gives a 0.4 point rule
= (equals sign) gives a 1.0 point rule (a thicker line)
~ (tilde) gives a rule 80% of the font height (believe me, I had a use for this once to blot out a preprinted form)
# (number sign) gives a rule 80% of the font height
To specify the thickness of the rule as any other size, say 3.0 points, use
thickness: 3.0 pt
where units are mandantory and may be in for inches, pc for picas, pt for points, cm for centimeters, mm for millimeters, and bp for big points.
In the absence of a length parameter, the default length is the distance from the left indent to the right margin, essentially across the page or column. To completely control the length use this parameter:
length: 1.0 in
where units are the same as for thickness.
For example, to get a one inch square black area, specify the following in a node:
thickness: 1.0 in length: 1.0 in
What can go wrong:
Error reporting is somewhat primitive, but you will surely notice when somthing is amiss:
Uncaught Signal:
There is likely some syntactic problem with the specification of the rule. I tried to keep it simple enough not to need fancy diagnostics hoping that you would get it right the first time!
The text of the node is printed instead of the rule:
You may have goofed in setting the ArtworkClass property in steps 2 or 3.
Text following the rule disappears:
You may have nested the text under the rule. Try double-clicking the middle mouse button to select the rule as an entire subtree. If the text following is also selected, it is improperly nested.
Making Text Invisible
There are times when you wish some information in documents, such as annotations or comments to yourself, not be printed yet remain in the document. The TSetter has been designed to always print Comment nodes so they are not sufficient to make annotations invisible. An ArtworkClass implementation makes this possible. Apply an ArtworkClass property of Invisible to nodes that you wish the TSetter to ignore.
Be forewarned that using an ArtworkClass property of Invisible will undoubtedly confuse you in the future. There is nothing visible in the document to warn you that the invisible text will not be printed. I recommend that you also set a unique format with unique typeface parameters to help remind you that this is an annotation.
Mark Properties
To implement running headers and footers, the TSetter marks special Tioga nodes. These marked nodes are later used for page layout purposes. In fact, the entire branch descendant from a marked node is retained. Caution is advised that text nodes are not inadvertenly nested under a marked node.
Marked nodes have a Mark property value which is a rope name. The present set of known mark property values is established by the page layout styles, e.g. BasicPrint.Style. No checking is done on mark property values, so they may seem to disappear when the document is printed if the property value was incorrectly named.
Page layout routines access the marks for the current page. Two operations are provided for extracting the first and last marks of a given kind defined on a page. At the end of each page the list of marks is pruned of duplicates. This provides for normal running headers and footers as implemented by BasicPrint.Style, as well as for more exotic dictionary slug footers.
PressScreen Tool
The PressScreen tool augments the capablities of the TSetter tool for printing screen images. The screen image is packaged in a clever way so that it can be used for two purposes simultaneously. First is can be printed by a Press printer (unfortunately not always by a Spruce printer). Second it can be displayed as an AIS image by Cedar Graphics or the Imager.
The TSetter registers the additional command PressScreen. Executing the PressScreen command creates a PressScreen tool viewer. The tool viewer provides new ways for describing the format of the printed results, for specifying the screen image to be printed, and for controlling Viewers while capturing the screen image. An auxillary system-wide button for activating PressScreen is posted at the top of the Cedar desktop so that no other screen real estate need be dedicated to the tool viewer after the control parameters are set.
The PressScreen tool viewer has four menu items: DoIt, SetCorners, FlashImage, and GetSelectedViewer. DoIt (and the PS system-wide button at the top of the screen) cause PressScreen to do its work: prepare the identified screen image for printing. SetCorners uses the mouse to set the corners of a rectangular screen area. When this button is clicked, the cursor changes to a cross hair. A left-click-and-hold will set the first corner and dragging the mouse with the left button still held down will drag a border. Release the left mouse button to set the corners of the desired screen area. FlashImage highlights the desired area briefly in reverse video. GetSelectedViewer uses the current selection to determine the screen area of interst. If the selection is a string more than 1 character long then that string is taken to be the name of the desired viewer and its corners are used. Otherwise if the selection is only a point selection then the viewer containing the selection and its corners are used.
The screen area can be one of four choices: DesiredArea, WholeScreen, LeftColumn, and RightColumn. The latter two choices refer to the Viewers columns as currently defined by the boundary line and includes the screen areas above and below the columns. WholeScreen refers to the entire screen area. DesiredArea refers to the area corners defined below that are set by the SetCorners or GetSelectedViewer menu buttons.
The corners of the desired screen image area are specified in the four viewers labelled Area Corners. One can edit the values there, although the normal way to change them is to use the SetCorners or GetSelectedViewer menu buttons. The first (x, y) pair refer to the upper left corner, the second pair refr to the lower right corner.
The printed screen image can be formatted in several ways. Magnification can be adjusted automatically to fit either a FullPage or HalfPage, or it can be specified explicitly in the Magnification Factor viewer. The printed page can be oriented in either Landscape or Portrait orientation with the long paper dimension horizontal or vertical respectively. A black border two pixels wide is normally provided and this thickness can be adjusted in the BlackBorder viewer. When the screen image is printed, the left and right margins will be the length in the PageMargin viewer.
A countdown timer is provided should it be necessary to set up for a press screen. The CountDownTimer viewer sets the number of seconds after the DoIt or PS buttons are clicked that the screen image is actually captured. Note that this is only a minimum time estimate due to unpredictable system activity while timing. For your entertainment, there is a pie viewer that counts down the time remaining.
Three Viewer Controls buttons provide the means to achieve special effects. These control buttons are in effect only when they are black with white lettering, and are not active when they are white or grey with black lettering.
Pagination in the Cruel World
The present TSetter has several features that provide a sense of pagination control. Unfortunately these features do not have exceptionally good user interfaces. Therefore, only the hardy and the brave need read on. Fools can ignore that warning.
The TSetter builds pages by collecting boxes of typeset material (text, graphics, press files, etc.) until the vertical dimension of that collection of boxes exceeds the page depth minus the header/footer margins. At present the TSetter will add any extra white space at the bottom to build a page with exactly the right vertical dimension. There is a variable TSOpsImpl.pageBottomSkip that if set NIL will distribute the extra white space between the boxes of typeset material, but there is no user interface for changing it except by the Interpreter. The TSetter knows nothing about footnotes or floating figures. Therefore attempting to place these in a pleasing manner can only be done manually in an iterative manner: try it, look at it, change it and try again.
Page Breaks
You may force the TSetter to break a page where you want by using the pagebreak format in Cedar.Style. The node with this format will be typeset at the bottom of the current page, if it fits, and the following node on the following page. If the node contains text, such as the DRAFT notice on many Cedar documentation files, then it will appear as a poor-man's footnote. Generally the node is empty, which makes editing it awkward. If a document has pageBreak nodes in it and edits rearrange the amount of text on a page, then the TSetter will insist on breaking a page where that page break node is located whether it looks reasonable or not.
You can discover all the page break nodes with the EditTool using the Find Property button: 1. enter Format in the Property name field (capitalization is important); 2. enter pagebreak in the Value pattern field (capitalization is important); 3. make a selection in your document; 4. left-click Find to search forward or right-click Find to search backward. A node that has the format pagebreak will be selected if one is found.
Page Numbering
Page numbering can be controlled by altering some of the JaM variables that BasicPrint.Style defines. These JaM variables are not style attributes in the same sense as font family or size. You may alter them by either creating your own style (or StyleDef property) or by providing Tioga properties to change them.
Tioga provides node properties whose values are executed by the JaM interpreter either before or after the node style format is applied. The two properties are Prefix and Postfix. For altering the pagination control variables we shall use the Postfix property on the root node only. Placing the property on other nodes within the document may have an unsynchronized effect since the TSetter can box several nodes in advance of building a page. To set a Postfix property, use the EditTool: 1. enter Postfix in the Property name field (capitalization is important); 2. enter an appropriate value described below in the Property value field; 3. ensure that the toggle button reads For root node; 4. select somewhere in your document; 5. left-click the Set button. You can concatenate several changes by separating them with blanks.
You can eliminate page numbering totally by modifying the pageNumbering variable. Its default value is the JaM BOOLEAN value .true. To turn off page numbering, set the Postfix value of the root node to (pageNumbering) .false .cvx .def where the periods are part of the JaM names for a BOOLEAN FALSE value, convert to executable value, and define this variable.
You can establish the first page number of a document by modifying the firstPageNumber variable. Its default value is 1. To change it so that the first page is numbered 42, set the Postfix value of the root node to (firstPageNumber) 42 .cvx .def.
By default BasicPrint.Style does not print a page number or headings on the first page of your document. To control this you can modify the firstHeadersAfterPage variable. For instance, if the firstPageNumber variable is still 1 and you want page numbers and headers on page 1, set the Postfix value of the root node to (firstHeadersAfterPage) 0 .cvx .def.
Two Column Layout
An alternative layout to BasicPrint.Style is provided in TwoColumnCedar.Style. If you change the style of your document to TwoColumnCedar instead of Cedar, you will get two columns when the document is typeset.
Basic Headers and Footers
BasicPrint.Style provides for 6 pieces of headers and footers. These are referred to by their position when the pages are bound together. That is, the piece of the footer closest to the binding is the insideFooter, the piece in the middle is the centerFooter, and the piece nearest to the loose edge of the page is the outsideFooter. Headers contain the page number so the three pieces are the insideHeader, the centerHeader, and the page number. To change this arrangement requires that you modify the GetFooters JaM code, which is recommended for pioneers only.
To supply text for these pieces, you must create Tioga nodes with a Mark property whose property value is the name of one of those pieces.
The firstHeadersAfterPage variable described above controls when the headers and footers first appear on the typeset document. The default BasicPrint.Style does not put page numbers or headers until after page 1.
Two-sided Headers and Footers
When a document is to be printed on both sides of the paper, the headers and footers are designed for the inside and outside edges of the paper. Inside in this situation means nearest the binding, and outside means nearest the loose edge of the page. Furthermore, the headers and footers can be designed to take advantage of the two-page spread of facing pages. The printing industry names for those two pages are recto (right-hand side with an odd page number) and verso (left-hand side with an even page number). Thus BasicPrint.Style accommodates ten (out of a possible twelve) different pieces of headers and footers: insideRectoHeader, centerRectoHeader, centerVersoHeader, insideVersoHeader, insideRectoFooter, centerRectoFooter, outsideRectoFooter, outsideVersoFooter, centerVersoFooter, insideVersoFooter. The two missing pieces are reserved for page numbers in the outside headers on both the recto and verso pages.
To change from one-sided to two-sided layout, you must change the oneSidedFormat variable from .true to .false, either by specifying it in your own style or by providing a Postfix property of the root node whose value is (oneSidedFormat) .false .cvx .def.