home *** CD-ROM | disk | FTP | other *** search
/ GEMini Atari / GEMini_Atari_CD-ROM_Walnut_Creek_December_1993.iso / files / gnu / gemgs13 / gemgs.doc < prev    next >
Text File  |  1993-07-30  |  17KB  |  424 lines
  1.  
  2. Documentation for gemGS 1.3.             11/27/92
  3.  
  4. GemGS may be freely copied and distributed, although the source is
  5. copyrighted.  Portions of the source were taken from the Unix
  6. Ghostview distribution, and Tim Theisen holds the copyright to those
  7. parts.  If you modify the source, please change the name of the
  8. program so that there is no confusion.
  9.  
  10.  
  11. INTRODUCTION:
  12.  
  13. GemGS is a GEM shell for Ghostscript on Atari ST/TT computers.  The
  14. code is not the world's best, since I used it as an exercise to learn
  15. some aspects of GEM programming, but it is fun to play with, and may
  16. be useful to those who hate command line interpreters.  The only real
  17. advantage that the shell offers over the command line interface is the
  18. ability to choose specific pages from large documents for GS to
  19. display.  Unfortunately the speed (slow) of the page selection code
  20. nearly negates any benefit (hey, I didn't write that part of the
  21. code).
  22.  
  23. GemGS 1.3 contains some changes which allow it to interface properly
  24. to GS 2.52.  This includes a menu to select the pagesize, and a change
  25. in the GS command line option to specify the band-printing buffer
  26. size.  GemGS 1.3 should be used with GS 2.52, while gemGS 1.2 is
  27. intended for GS 2.41.
  28.  
  29. In essence, gemGS simply sets up a GS environment, allows the user to
  30. pick Ghostscript options with the mouse, and then executes GS.
  31.  
  32. Some frills are:
  33.  
  34. 1) Setup file that allows the user to define menu items, select
  35.    default options, and define environment variables.
  36.  
  37. 2) A user definable "tool" menu, which can be loaded with all kinds
  38.    of gem, tos, and ttp utility programs, which can then be run from
  39.    the shell in a semi-integrated fashion.
  40.  
  41. 3) GemGS can be installed so that it automatically displays PostScript
  42.    files which have been double-clicked.
  43.  
  44. Disadvantages are:
  45.  
  46. 1) It is tedious to use if you like CLIs.
  47.  
  48. 2) Postscript document scanning for page selection is sloooow.  I
  49.    stole most of the code for this from the Ghostview (X Windows shell
  50.    for GS) distribution, so I will pass the blame until I get time
  51.    to look into speeding it up.
  52.  
  53. 3) The menu bar and the command line dialog are too large for low
  54.    resolution on the ST. You can sort of use gemGS, but not too well.
  55.    I may fix up a low res version sometime in the future.
  56.  
  57. BASIC USAGE:
  58.  
  59. From a command line: gemgs [infile1 infile2 ...]
  60.  
  61. GemGS initializes the background and mouse itself, so it should work
  62. properly when run from a shell.  GemGS does not restore the cursor
  63. when it exits (that would mess up desktop users), so if you run from a
  64. shell, you may end up without a visible cursor in the end unless you
  65. execute gem programs from within some kind of wrapper.
  66.  
  67. Once inside the gemGS shell, you:
  68.  
  69. 1) pick the input and output files from the File menu,
  70. 2) choose the device from the Device menu,
  71. 3) pick the resolution from the Resolution menu,
  72. 4) pick the page size from the PageSize menu,
  73. 5) pick any options from the options menu,
  74. 6) click Run under the File menu.
  75.  
  76. Everything in items 1-6, except for choosing the input file, can be
  77. done from the startup file.  The input file can be entered on the
  78. command line.
  79.  
  80. Depending on how the options are set, selecting the Run menu item will
  81. either start GS running, or you will get an editable dialog showing the
  82. command line that will be passed to GS and asking for confirmation.
  83. After this, you interact with GS as usual; see the GS documentation.
  84. When GS exits, you will return to the shell.
  85.  
  86. GemGS can also be installed on the desktop to automatically display
  87. PostScript files which have been double-clicked. To do this, use
  88. whatever procedure is necessary on your machine to install gemGS
  89. as the default application for files with extension .ps. Then make
  90. sure the line "autorun 1" is in the the gemgs.rc startup file. When
  91. gemGS has been given command line parameters, autorun tells it
  92. to execute GS immediately on the input files, disregarding the
  93. state of the "confirm" option. If there are no input files, gemGS
  94. enters interactive mode as usual.
  95.  
  96. NOTE: GemGS looks searches the PATH environment variable for the
  97. file 'gs.ttp'. If PATH is not set, or you changed the name of
  98. the ghostscript executable, you will get a dialog stating that
  99. GS could not be run.
  100.  
  101. The screen driver for GS has been modified to include support for
  102. windows.  This modification was intended for use with gemGS, but can
  103. be used with GS alone.  GS figures out how to handle the windows by
  104. looking at the environment variable GS_WIN.  If GS_WIN is not set, the
  105. GS screen driver uses no windows.  If GS_WIN=interact (lower case),
  106. then images are displayed in a window, but text mode is entered after
  107. every page.  This allows interactive entry of commands at the GS
  108. command line.  "Interact" mode is intended to be used when GS is run
  109. from a shell.  If GS_WIN=batch, the screen driver assumes that you are
  110. running GS in such a fashion that no real interaction with GS takes
  111. place, i.e., GS prints no messages to you, and you type no commands to
  112. it.  This is the mode that gemGS uses when the "windows" option is
  113. selected.  This hides the fact that GS is really a command-line driven
  114. program, but it is not flawless.  For example, if an error occurs in
  115. GS when GS_WIN=batch, the error message will be written all over the
  116. screen background, menus, etc.  As long as nothing abnormal happens,
  117. it works OK.  See the Atari-specific GS documentation for instructions
  118. on screen driver use. Of course, if you have an old version of GS,
  119. the GS_WIN variable will be ignored.
  120.  
  121. MENUS:
  122.  
  123. Some menu items have alternate key bindings. Those that do, have the
  124. binding shown beside the menu entry.
  125.  
  126. #--------------------------------------------------------------------
  127.  
  128. Desk:
  129.  
  130. About gemGS - Displays a dialog about gemGS. For those serious-minded
  131.     folks who are uncertain, this dialog is a simultaneous
  132.     commentary on the current job situation for theoretical
  133.     physicists and the complaints of shareware authors who
  134.     feel that users never pay the requested fee. In short
  135.     it is a joke. Do you think anyone will pay up?
  136.  
  137. #--------------------------------------------------------------------
  138.  
  139. File:
  140.  
  141. Run   - Run Ghostscript with the current command parameters. If the
  142. ALT-r    "confirm" option is chosen, a dialog will display with the
  143.     GS command line.
  144.  
  145. Input - Presents a file selector so that the input file can be chosen.
  146. ALT-i    Note that only one file can be entered in this fashion.
  147.     Multiple input files have to be entered from a command line
  148.     or typed in the editable field which is displayed when the
  149.     "confirm" option is set.
  150.  
  151. Output- Presents a dialog for selecting output to PRN: (the centronics)
  152. ALT-o    port), CEN: (like PRN: only faster--apparently doesn't work on
  153.     some STEs or TTs), or to a file. If a file is desired, a
  154.     file selector is presented.
  155.  
  156. Quit  - Self explanatory, I hope.
  157. ALT-q
  158.  
  159. #--------------------------------------------------------------------
  160.  
  161. Device:
  162.  
  163. This menu item contains 2 standard entries and up to 8 more user-defined
  164. entries. The 2 standard entries are described here.
  165.  
  166. stvdi - Selects the screen device as the GS output device.
  167.     GemGS assumes that the screen device is the default device.
  168.     Other devices can be loaded into this menu, and the default
  169.     device can be selected in the startup file. More on this later.
  170.  
  171. Other - Presents a dialog for you to type in a device which has not
  172.     been loaded into the menu.
  173.  
  174. #--------------------------------------------------------------------
  175.  
  176. Resolution:
  177.  
  178. This menu item contains 2 standard entries and up to 8 more user-defined
  179. entries. The 2 standard entries are described here.
  180.  
  181. Default - Use the default resolution of the selected device.
  182.  
  183. Other   - Presents a dialog for you to type in a resolution which has
  184.       not been loaded into the menu. It is up to the user to use
  185.       resolutions that the chosen device can handle.
  186.  
  187. #--------------------------------------------------------------------
  188.  
  189. PaperSize:
  190.  
  191. Some of these entries are self-explanatory, and some are a complete
  192. mystery to me. I suppose if you don't understand it, you don't
  193. need it. The default papersize can be set from the startup file
  194. with something like "papersize letter".
  195.  
  196. #--------------------------------------------------------------------
  197.  
  198. Options:
  199.  
  200. All of the following options can be set from the gemGS startup file.
  201.  
  202. Confirm - Display a dialog containing the GS command line and ask
  203.     for confirmation before running GS. The command line can
  204.     be edited at this time.
  205.  
  206. Quiet - Run GS in quiet mode, no startup/informative messages.
  207.  
  208. NoPause - Tells GS not to pause and the end of every page in a
  209.     multi-page document. If NoPause is turned off, you have
  210.     to hit RETURN at the end of every page.
  211.  
  212. AutoQuit - GS will quit when it runs out of input. By default, GS
  213.     enters interactive mode when it reaches the end of its
  214.     input files.
  215.  
  216. Windows - This tells GS to display the image in a window. It is
  217.     only enabled when the screen device is selected. It is
  218.     ignored for printer devices. When this option is selected,
  219.     the environment variable GS_WIN is defined with the value
  220.     "batch". Selecting "windows" will automatically select
  221.     the "quiet", "nopause", and "autoquit" options. This is
  222.     so that output from GS does not get written all over the
  223.     GEM screen. Unfortunately, however, any GS error messages
  224.     will be ugly. Note that old versions of GS (generally < 2.5,
  225.     although some versions of 2.41 are OK) cannot display in
  226.     windows, and will ignore the GS_WIN envorinment variable.
  227.  
  228. Geometry - Display a dialog that allows a geometry to be chosen.
  229.     The Geometry is just the size of the image in pixels,
  230.     like 640x400. Every device has a default geometry, but
  231.     you can change it if you like.
  232.  
  233. Clist - Print images in bands for machines with limited memory.
  234.     GS can print imaging commands to a "Command list" and
  235.     then read these commands back repeatedly to construct large
  236.     images in bands. This is MANDATORY on 1M machines. When "Clist"
  237.     is selected, a dialog is presented to allow the user to
  238.     enter the size of the buffer (in bytes) that will be used
  239.     to hold the bands. Entering 100000 means that the image will
  240.     be printed in chunks of 100K bytes each. You will need to
  241.     have 100K of free memory AFTER GS is loaded and has allocated
  242.     memory for needs other than the print buffer.
  243.  
  244. Pages - If no input file is selected, a file selector is presented.
  245.     The input file is then scanned to determine the number of
  246.     pages and their order, etc. This can take a very long time
  247.     for long documents (about 5 minutes for 30 pages). A dialog
  248.     is then presented so that the desired pages can be selected.
  249.     Pages are selected by EITHER clicking on the appropriate
  250.     boxes OR typing a string in the editable text field provided.
  251.     The contents of the editable field override the buttons. The
  252.     buttons are used only if the field is empty. The Clear button
  253.     in this dialog clears all button selections AND the editable
  254.     field. Use the arrows to scroll up and down if there are
  255.     more than 10 pages. The selected pages are written to a
  256.     file called "pspage.ps", and that file is automatically
  257.     passed to GS instead of the original input file. "Pspage.ps"
  258.     is deleted when gemgs exits, but is available for viewing
  259.     and editing from within gemGS (by using programs in the tool
  260.     menu).
  261.  
  262. #--------------------------------------------------------------------
  263.  
  264. Tools:
  265.  
  266. This menu contains no default entries.  Everything in this menu is
  267. loaded from the gemGS startup file.  This menu is very flexible, and
  268. is intended to provide a convenient interface to programs which are
  269. often used on conjunction with GS.  For example, one menu entry in the
  270. example startup file runs the micro-emacs editor on the input file.
  271. Another entry runs dvips, a program that converts TeX dvi files to
  272. postscript format.  A help entry runs micro-emacs on this
  273. documentation file.  The programs can be of GEM, TOS, or TTP type.
  274.  
  275. In the definition of a tool menu entry, there are a few keywords that
  276. allow a limited use of dialogs and file selectors with programs in the
  277. tools menu.  See the documentation on the startup file for more
  278. details.
  279.  
  280.  
  281. STARTUP FILE:
  282.  
  283. On startup, gemGS looks for a file named "gemgs.rc".  If this file
  284. cannot be found in the current directory, then the directory contained
  285. in the environment variable HOME is searched.  An alert warns if no
  286. startup file can be found.  The syntax of the allowed commands is
  287. documented in the example startup file which should be included in
  288. this distribution.  A copy is included here for convenience.
  289.  
  290. #--------------------------------------------------------------------
  291. #    Begin example gemgs.rc
  292. #--------------------------------------------------------------------
  293. #
  294. # Example setup file for gemGS.
  295. #
  296. # The format for the setup commands is currently very strict, so
  297. # pay close attention to the precise form. Never use more than
  298. # a single space, and don't use any tabs.
  299. #
  300. # Any line which cannot be recognized is ignored, but I have
  301. # conventionally used a '#' to denote a comment.
  302. #
  303.  
  304. # Set default device. This overrides the GS_DEVICE environment
  305. # variable. If this is missing, the default is the stvdi device.
  306. # The device name must match name that GS knows for the device.
  307. # To see what devices are installed, type gs -h.
  308. # Format is "device gs_device_name".
  309.  
  310. device stvdi
  311.  
  312. # Set gemGS to autorun. When autorun is set to 1, gemGS will immediately
  313. # run GS on the input file, ignoring the 'confirm' option if it is set.
  314. # If there is no input file, the autorun variable is ignored and gemGS
  315. # runs interactively. This allows PostScript files to be immediately
  316. # displayed with gemGS by simply double-clicking on the file. Of course,
  317. # you must install gemGS as an desktop application first.
  318.  
  319. autorun 1
  320.  
  321. # Set the default options.
  322. # Format for on/off options is "option_name 1/0".
  323.  
  324. #confirm 1
  325. #quiet 0
  326. nopause 0
  327. #autoquit 1
  328. windows 1
  329.  
  330. # Format for other options is "option_name option_string".
  331.  
  332. #resolution 60
  333. #geometry 400x400
  334. #clist 150000
  335. #papersize a4
  336.  
  337. # Set environment variables. PATH is used in searching for GS
  338. # and for tools. GS_DEVICE is the default device if the "device"
  339. # command appears nowhere in this file. GS_LIB is the path that
  340. # GS searches for ps files, fonts, etc.
  341.  
  342. #setenv PATH=c:\bin,f:\gs
  343. #setenv GS_DEVICE=deskjet
  344. #setenv GS_LIB=f:\gs,f:\gs\ps,f:\gs\fonts
  345.  
  346. # Add devices to the device menu. The device name must match the
  347. # Ghostscript name for the device. Type 'gs -h' to see which
  348. # devices are available in the GS executable that you have.
  349. # Format is "devmenu gs_device_name".
  350.  
  351. devmenu djet500
  352. devmenu epson
  353. devmenu dfaxhigh
  354.  
  355. # Add resolutions to the resolution menu. The default screen
  356. # resolution is 80dpi. All resolution entries are in dots-per-inch.
  357. # The resolution string should be whatever comes after the GS
  358. # -r command line switch. It is up to you to specify a resolution
  359. # that the given device can handle.
  360. # Format is "resmenu resolution_string".
  361.  
  362. resmenu 60
  363. resmenu 100
  364. resmenu 120x60
  365.  
  366. # Add tools to the tool menu. These can be GEM, TOS, or TTP programs.
  367. # PATH will be searched for any program specified. If the program
  368. # is not in the specified PATH environment variable, the full program
  369. # name must be given. The following special keywords are recognized
  370. # by gemGS as command line options for tool menu entries:
  371. #
  372. # infile:    substitute the input file in the position of this keyword,
  373. # outfile:    substitute the output file in the position of this keyword,
  374. # fsel:        present a file selector, put the selection in this position,
  375. # dialog:    present a dialog with an editable text string, input here,
  376. # pause:    pause after tool terminates before redrawing screen,
  377. # gem:        specifies that program is a GEM program so that screen
  378. #            and mouse are handled properly.
  379. #
  380. # Format is "toolmenu menu_string program_name [command line options]"
  381.  
  382. toolmenu gemGS-Help ue gemgs.doc
  383. toolmenu GS-Help ue f:\gs\doc\use.doc
  384. toolmenu Edit-File ue dialog
  385. toolmenu Edit-Input ue infile
  386. toolmenu Print-Output bpr outfile
  387. toolmenu TeXdvi-to-PS dvips fsel
  388. toolmenu Dega-to-PS psst gem
  389. toolmenu Shell gulam
  390. toolmenu Directory ls -l pause
  391. toolmenu DiskSpace df c: d: e: f: g: h: pause
  392.  
  393. #--------------------------------------------------------------------
  394. #    End example gemgs.rc
  395. #--------------------------------------------------------------------
  396.  
  397.  
  398. ACKNOWLEDGEMENTS:
  399.  
  400. The code for scanning PostScript documents and printing selected
  401. pages to a file was taken from the source for Ghostview, by
  402. Tim Theisen.
  403.  
  404.  
  405. SUGGESTIONS, QUESTIONS, and BUG REPORTS:
  406.  
  407. Any suggestions for improving gemGS are welcome.  One user has
  408. reported that loadable menu items appear in the menu terminated by a
  409. \cr, which shows up as a bell I think.  I have been unable to
  410. reproduce this behavior on my system.  If anyone else is having this
  411. problem, I would like to hear about it.
  412.  
  413. Questions and bug reports can be sent to:
  414.  
  415. Tim Gallivan
  416. Center for Relativity
  417. Department of Physics
  418. University of Texas at Austin
  419. Austin, TX 78712
  420.  
  421. timg@landau.ph.utexas.edu
  422.  
  423. /* EOF */
  424.