QsREADME: instructions on the 8 July'98 version of Quikscript ======== The changes to this version of Quikscript are listed at the bottom of this document. Qs (Quikscript) is a PostScript text formatting and typesetting program. It enables documents to be prepared on any type of hardware, using visible layout marks to control the appearance of the output, and produce output on a PostScript printer by despatching Qs and the document file to the device. No processing is performed by the host hardware; all processing is done within the printer. The advantage that Quikscript provides, other than portability, is precision of control over output. Because it is written in PostScript, it is interpreted at run-time within the printer. It is possible to create documents that modify the Quikscript program during execution. It is very easy to include other PostScript programs or fragments with Quikscript. It is possible to use special PostScript fonts, such as hand-generated ones. Graphics generated from a variety of sources can be easily included, as can text output from computer programs. It is possible to embed Quikscript within a document, such as an advertisement or a telephone bill. To use Quikscript, create a file containing text and visible layout marks as described in the user manual. Create a temporary file containing Qs and your text, and send this to a PostScript printer. If you do not have a PostScript printer, you can process the temporary file using a PostScript previewer such as ghostscript, which can convert it to be printed by almost any other type of printer. To print the user manual, concatenate a copy of Qs and userdoc.qs into a single file and send this to a PostScript printer. [If your printer will only take US Letter and not A4 that is assumed in Quikscript, uncomment the two lines near the top of userdoc.qs that mention this paper size, and uncomment two similarly-commented lines near the top of Qs.] If you would like to be notified of future changes to Quikscript, send an email to g-freeman@adfa.edu.au containing the subject description "Quikscript user". Files included in this distribution: Qs Quikscript program (PostScript) userdoc.qs A user manual. To print this document, you should send Qs and this document to a PostScript printer. rotate.qs The PostScript program to modify Quikscript to rotate every page so that output is in landscape format rather than portrait format. draft.qs The PostScript program to modify Quikscript so that each page will be drawn with the word "DRAFT" added in large shadow letters across the page. border.qs Example PostScript routine to modify Quikscript adding a border to each page. pdffnt.qs The PostScript program to modify the character encodings so that European characters are available using the correct ISO character codes. Typesetting characters not included in the ISO set are also available. europfnt.qs The PostScript program to modify the character encodings so that most European characters are available. It approximates the ISO character set. (pdffnt.qs is recommended for European characters; this is retained only for existing documents that use this set.) outlinft.qs The PostScript program to set up a Helvetica font which draws characters in an outline form. smallcap.qs The PostScript program to set up a version of the current font with lower case letters drawn as small capitals. dijkstra.qs A cute font imitating a person's handwriting, good for hand-written correspondence that you can type at the keyboard! altpagnm.qs The PostScript routine to change the Quikscript behaviour to alternate page numbering from left to right side of page. cntpagnm.qs The PostScript routine to change the position of page numbers so that they will be centred at the top of the page. pagrange.qs Restrict the pages output to those between certain limits specified in the file. The file must be editted each time it is used to set the desired limits. 2col.qs Print the document on a landscape page in two 3col.qs or three columns, suitable for producing a simple leaflet. 2colleaf.qs Print the document in two columns suitable for folding as a simple leaflet. The paper will need to be trimmed at the trim marks. 3narrowcols.qs Print the document on a portrait page in three narrow columns, using Courier font and No-Fill mode, printing the text exactly as it is in the file. 2p.qs Print the document two pages per sheet, side-by-side. 2pend File "2pend" should be concatenated to the end of the document to ensure that nothing is missing from the last page. catex.c A version of the UNIX "cat" command that concatenates several files into one and writes it to standard output. This version examines the content of every file, looking for the string "%include file-name%". The file ("file-name" in this example) will be included at the point it is referred to. This file may itself have references to other files which must be included. The file-name is interpreted as a path relative to the path of the file which referred to it, so will be in the same directory unless it is given as an absolute path (beginning with '/') or begins with '../', which will be interpreted in the UNIX fashion. This is an extremely useful tool with Quikscript since it removes the necessity for including the above PostScript pieces explicitly in every document that uses them. It also enables PostScript drawing instructions for externally prepared diagrams to be held as separate files, rather than being embedded within the document where they will ultimately appear. If the included file is modified, the whole document will automatically reflect the change when next printed. catm.c An embellishment of "catex.c", incorporating the same functionality, but intended to be used for file merging. The first file argument is a "macro" file, defining a series of values of field names to be used when "catm" repeatedly copies the remaining files to standard output. The main use of this program is in producing a series of letters or similar documents with individual names, addresses, and such fields. notab.c A simple filter program to replace tabs with a sensible amount of white space. macros.qs Example of how macros can be used with catex or catm. This example shows how to set up a structured document containing sections, dot-lists, and hanging first line lists which can be embedded. QstoHTML.java Quikscript documents can be converted to HTML format if they need to be displayed with a web browser. QstoHTML.class The three files comprise the binary version of EditBuffer.class QstoHTML.java. Execute the first with a Java OctalString.class virtual machine. epstopnm A Unix script for converting an EPS file into a PNM image. This is most useful as a step in handling illustrations when a Quikscript document is to be converted into HTML. It relies on ghostscript being available to do the work. epstogif A Unix script for converting an EPS file into a GIF image. It uses epstopnm, and relies on ghostscript and pbmplus or netpbm being installed. sortIndex.java If Quikscript documents output an index to the output avl.java screen when run in a PostScript interpreter, the index sortindex.c can be externally sorted with either the C or Java sort avlsort.c program. This is most useful if the document is organized into several separate chapters or sections, where the indexes from each section will need to be merged into a single index. sortIndex.class The five files comprise the binary version AVLnode.class of the Java program to sort an index. AVLsortable.class Execute sortIndex with a Java IndexItem.class virtual machine. AVLtree.class stdcodes A text file containing the numeric codes and names of all the special characters in standard PostScript fonts. QsREADME This file. qsmodify.qs A specification of how Quikscript works, for people wanting to make changes or add new features. ============================================================================= Changes in the 8 July'98 release of Quikscript: This release of Quikscript provides several new features, which have required a revision of the internal mechanism used by Quikscript to process its input. The opportunity has also been taken to reorganize the variable initialization at the head of the file to order them alphabetically. Although the changes have been major, it is hoped that existing documents will not need to be modified to print with the new version. Only in cases where you have embedded PostScript in your document may you be at slight risk, as outlined below. New features ============ %SI%...%EI% Text can be indicated for inclusion in an index. %SI% indicates that the following text is to be recorded, and %EI% marks the end of an index item. Between these tags can be placed any text, also including layout marks which are not acted upon at this stage but held over till when the index is to be output. Current page number and possibly chapter abbreviation is recorded with the text. %SC%...%EC% Text can be indicated for inclusion in a table of contents. %SC% indicates that the following text is to be recorded instead of being output immediately, and %EC% marks the end of recording of contents text. Between these tags can be placed any text, also including layout marks which are not acted upon at this stage but held over till when the index is to be output. Current page number and possibly chapter abbreviation is recorded with the text. %CA,text% The text will be used along with page number in any index or contents item. Eg. %CA,1-% would mean pages would be represented as 1-1, 1-2, etc. %PC% Print the table of contents on the current page. The pages will then need to be shuffled to put it in sensible sequence with the remainder of the document. %OC% Output the table of contents to the output stream rather than to the printed page. The output stream might be the window in which the PostScript interpreter is being run, or it might be the serial line connecting the PostScript printer to a computer. This would be used if a document was held in several files, and the contents of each section (file) would need to be separately generated and joined into a single table by hand. %PI% Print the index. %OI% Output the index to the output stream rather than the printed page. This would be done if the index were being generated in several parts from separate chapters, which would need to be merged before being printed. It might also be wanted if the simple sorting done by Quikscript was unsatisfactory. %SH%...%EH% The text between the marks is to be used as page header text, to be placed beside the page number (if pages are to be numbered). This text can include layout marks, which will only be acted upon when the text is printed at the page top. Changes ======= %SF% %EF% These layout marks are reserved for possible future use, implementing footnotes. qsmodify.qs In order to implement the new tags, the internal mechanism for processing text has had to be revised. This has meant changing the item in the Kwrd table which previously was a boolean, replacing it with a numeric item to indicate the status of each keyword. If you have added your own keywords to this table, you will need to read carefully the description of how Quikscript now works. The mechanism is formally documented in qsmodify.qs Embedded PostScript The Guide to Quikscript in the past has described how to add PostScript instructions to the text of a document, in particular for setting the page header text to appear beside the page number. With the new keywords (%SH% %EH%) the PostScript procedure (PrPagNum) for dealing with page numbering has had to be changed. This has been done in such a way that, if you have provided your own PrPagNum in some documents, you should not be disadvantaged. You should be aware of the new procedure, and in future use the new design. There is now a simpler mechanism for setting the page header text, and the font used for the header is selected differently. Font, FontNam These internal Quikscript tables now have extra entries for specifying your own fonts, with provision for three families instead of the previous two. Code reorganization The definitions of internal variables have been reordered to make them easier to find. Also, the table of keywords with associated procedures has been oved close to the top of the file. If you have made your own changes to Quikscript, you will need to search more widely to find the equivalent code if you wish to merge your changes into the new Quikscript. ============================================================================= Changes in the 10 Mar'98 release of Quikscript: Bug fix: affecting any word containing internal layout marks that is forced onto a new line through not fitting on the current line. ============================================================================= Changes in the 15 Jan'98 release of Quikscript: New features in Quikscript: %VL% to turn off all vertical lines within a table. %PF...% to modify paragraph format without forcing a new paragraph. New programs or files accompanying Quikscript: QstoHTML, a program to convert a Quikscript document into HTML for display with a web browser (written in Java). macros.qs, example of how to use catex macros to enable simple structuring in documents. 2p.qs and 2pend, print the document two pages per sheet. pdffnt.qs, a character encoding containing all the European characters as well as most of the typographical characters, superceding europfnt.qs stdcodes, listing the standard characters and their numeric codes. 2col.qs, for producing 2-column leaflets 3narrowcols.qs, for listing text unmodified in three narrow columns. epstopnm, a Unix script for converting EPS files to PNM images, which is useful if a Quikscript document is to be converted to HTML. Several bugs were fixed, including: When VM forced a new column in multi-column output, it placed the currentpoint in the wrong column, so following text would be incorrectly placed. europfnt.qs omitted "degree". NP in multi-column pages went to the wrong column. Error in drawing vertical lines in some tables. First line of each cell of a table is now set as the beginning of a paragraph using the current paragraph format. Implementation of full justification contained several errors that showed up if there was a change of font or size within a line. One of these errors caused occasional lines to continue beyond the right margin. Revisions to the user manual: Illustration showing how Quikscript can be embedded in an EPS file, in this example to produce an advertisement. Appendix describing ghostscript features useful with Quikscript, and also the "distillery" program for producing PostScript conforming with the Document Structuring Conventions. Description of the QstoHTML program. ============================================================================= Changes in the 4 Jan'96 release of Quikscript: Many minor bugs have been fixed, including: %P% at the top of a page should not cause unnecessary white space %FI% should be taken as breaking a word, to avoid layout problems if not preceded or followed by white space Placement of horizontal lines (in tables) has been fixed Leading blank characters are not significant unless in no-fill mode and text is not centred or justified; trailing blank characters should not be output Fully justified text is placed better, with space between all characters as well as between words when text on a line is sparse Spurious blank lines in output have been suppressed Bugs in "catex.c" and "catm.c" have been fixed. Added files for producing two-column and three-column leaflets that were previously omitted. Unix manual page for "catm" (thanks to Peter Samuel) ============================================================================= Changes with 31 Oct'94 release of Quikscript: New features: Tables can now be set more easily. The following layout commands are now recognized: ST start table, using the following arguments to indicate the margins of the columns ET end table TJ table justification, allowing the justification rule for each column to be set CO go to the next column of the table NR go to the next row of the table HL draw a horizontal line below the items of the current row of the table VL draw a vertical line at the chosen table margins Positioning of sub- and super-scripts has been improved to prevent subscripts on one line from interfering with superscripts on the next line. The underlying typesetting engine has been revised to prevent occasional unwanted blank lines. A second user-defined font family is provided for in the font table, named "U2". New features in catex and catm: Both these C programs will allow user-defined macros, which will be expanded while copying the files to standard output. A macro can be defined with %DM,name:subst:% and can be invoked with %M,name% For example, quotations that are to be set in italics in an indented paragraph might have two macros defined: %DM,Quote:%P,15%%IT%:% and %DM,EndQuote:%RO%%P,0%:% Each quotation would be preceded by %M,Quote% and followed by %M,EndQuote% The date can be generated with the special string %DATE% ============================================================================= Changes in the earlier release of Quikscript: Incompatibilities with previous versions: PW formerly to set page width, has been removed. Its function is adequately covered with use of PM, for setting the margins at the left, right, top and bottom of the page, and by CW for setting column width. RJ formerly to right justify text on the current line, has been replaced by RL, to be consistent with CL to centre text on the current line. The "RJ" command now has a new meaning (see new features). T without any parameters now means to move to the left margin of the current line, that is, the TB position plus body alignment, and not as previously, just the TB position _ This still causes a non-breaking blank to be placed. Previously, %___% would mean place three blanks. This must now be done with %_,3%, to be consistent with other commands. Auxiliary files have been renamed where the filename was long, to alleviate copying problems for people who have to tolerate 8-character limits on their machines. New features: FJ Full justification, that is, right and left (by popular demand - I had to rebuild the Quikscript engine to provide this feature; Quikscript does not run quite so fast as a result) All following text will be fitted into output lines, and will have white space added between words to cause the right end of lines to line up as well as the left. CT Centre. All following lines of output will be centred between the left and right margins as set by TB and CW. RJ Right Justify. All following lines of output will be right justified (ragged left) to the current right margin as set with CW. LJ Left Justify. Restore the default processing mode (ragged right). ============================================================================= Quikscript is free for personal use. A licence is available for commercial use from the author. The Quikscript distribution can be obtained from website http://www.cs.adfa.edu.au/~gfreeman/sware/Quikscript.tar.gz Graham Freeman g-freeman@adfa.edu.au 8 July 1998