home *** CD-ROM | disk | FTP | other *** search
/ Computer Club Elmshorn Atari PD / CCE_PD.iso / pc / 0400 / CCE_0417.ZIP / CCE_0417.PD / ASCREEN.ZOO / readme < prev   
Text File  |  1992-03-14  |  11KB  |  261 lines
  1.  
  2. README for ASCREEN 3.1 --- 14th March 1992
  3. ==========================================
  4.  
  5. Installation
  6. ------------
  7. Copy the files ASCREEN.PRG, ASCREEN.RSC and ASCREEN.SET to a suitable
  8. folder on the hard disk, for instance near your other previewer.
  9. Use a text editor to correct the path names in ASCREEN.SET. There are
  10. various templates given for font names; uncomment the one that fits your
  11. TeX and comment out the others. Same for the resolution.
  12. Or start ASCREEN without specifying a DVI file, change the setup in the
  13. option dialogs and save your settings under the name of ASCREEN.SET.
  14.  
  15. Environment
  16. -----------
  17. ASCREEN 3.1 honors two environment variables:
  18.  
  19. ASCREENSET    Full path name of the setup file (ASCREEN.SET)
  20. ASCREENRSC    Full path name of the resource file (ASCREEN.RSC)
  21.  
  22. ASCRNENG.RSC contains English resources. To use these, either rename the
  23. file to ASCREEN.RSC or set ASCREENRSC to point at this file.
  24.  
  25. Usage
  26. -----
  27. Invoke by
  28.  
  29.     ascreen [ &setup ] [ Options ] File
  30.  
  31. or from a TeX shell. There are the following options:
  32.  
  33.     -A            Toggle cache-ahead (default is ON)
  34.     -c <Color>        Set colors for display (see below)
  35.     -D <Directory>        Directory for DVI files
  36.     -d            Use desktop background
  37.     -e <extension>        Set extension for `%e' in PK names
  38.     -F <extension>        Font directory
  39.     -f <2 or 3>        Shrinking factor (default is 2)
  40.     -G <extension>        IMG file directory
  41.     -H <dimension>        Left margin (default is 0pt)
  42.     -I            Toggle display of IMG files (default is ON)
  43.      -J            no-op (for TeXshell compatibility)
  44.     -l            Log to file (default is OFF)
  45.     -M <Number>        Magnification (in 1/1000 or `magstep')
  46.     -m            magical ENTER (default is ON)
  47.     -p <Number>        Maximum number of pages cached
  48.     -V <dimension>        Top margin (default is 0pt)
  49.     -v            Toggle verbosity (default is OFF)
  50.     -w <geometry>        Size and position of message window
  51.     -x <dimension>        Page width (default from DVI file)
  52.     -y <dimension>        Page height (default from DVI file)
  53.     -Z <Number>        Maximum number of fonts (default is 32)
  54.     -z <String>        Template for PK file names
  55.  
  56. A <dimension> is a floating point number followed by one of the TeX
  57. units of measure mm, cm, in, pt, sp, cc, dd or bp. A <geometry> is a
  58. string of the form `wxh' or `wxh+x+y', where w and h are the width and
  59. height of the window. x and y give the distance from the left or upper
  60. edge of the work area, respectively (not counting the menu bar). You may
  61. use `-x' or `-y' instead of `+x' or `+y', in which case the offsets are
  62. between the right or lower edge of the window and the right or lower
  63. edge of the work area. For instance, `100x100-0-0' would be a 100 by 100
  64. window in the bottom right corner of the screen. (This is from X11.)
  65. The <color> controls the appearance of formatted pages on the screen.
  66. This is a 16-bit number whose upper and lower byte give the color of the
  67. background and the `ink', respectively, namely as an index into the
  68. current pallette. All numbers may be given in decimal (123), octal
  69. (0173) or hexadecimal (0x7b), which is probably most useful when
  70. specifying colors. The default is color 0 for the background and color
  71. 15 for the text.
  72.  
  73. Just like TeX ASCREEN lets you enter the name of the setup file as the
  74. first argument, preceded by an ampersand. This makes it convenient to
  75. use several setup files in parallel. Those folks who always want to know
  76. everything in the most minute detail can, for instance, make a setup
  77. file that specifies printer fonts instead of screen fonts. So one can
  78. say `ascreen &huge.set foo' instead of `ascreen foo' for a giant
  79. display. Alias definitions in shells like Mupfel come in quite useful
  80. here.
  81.  
  82. Key Assignments
  83. ---------------
  84. The accelerators for menu entries are given in the menu (and may be
  85. customized with a resource editor). Besides, there are the following
  86. assignments:
  87.  
  88.     Cursor keys        move the document inside the current window
  89.                 (large steps)
  90.     Keypad-1,2,3,5        ditto
  91.     Keypad-7,8,9,)        movement by small steps
  92.     Clr/Home        go to upper left corner of page
  93.     Keypad -        go to previous page
  94.     Keypad +        go to next page
  95.     Enter            either like `Keypad +' or magical
  96.     Keypad .        magical backwards
  97.  
  98. `Magical Enter' works like this: usually the magical Enter key functions
  99. the same as the down-arrow key (or Keypad-2). But when the current
  100. position is at the bottom of the page, the top of the next page will be
  101. displayed. Thus you can page through an entire document just by
  102. repeatedly hitting the Enter key. The decimal point key on the keypad
  103. works similarly but backwards.
  104.  
  105. Related to this is `smart paging': when turning over the page backwards
  106. while being positioned at the top of the page, you end up at the bottom
  107. of the previous page.
  108.  
  109. In a window (or a page on the desktop) the left mouse button will pop up
  110. a menu containing the options, `Next Page', `Previous Page', `Go to
  111. page', `Reduce' and `Lock' or `Unlock'. You can't reduce two adjacent
  112. pages yet.
  113.  
  114. FLIB files
  115. ----------
  116. ASCREEN supports FLIB files, i. e. packed `libraries' of PK fonts. The
  117. format is that of emTeX (thanks to Eberhard Mattes for the description).
  118. FLIB files are accessed by listing their names in `fontpath', for
  119. instance
  120.  
  121.     fontpath    d:\fonts\fdori101.fli,d:\fonts
  122.  
  123. (Everything that ends with `.fli' is considered a FLIB file.) As you
  124. see, FLIB files and paths may occur in whatever order and will be
  125. searched in sequence, allowing fine control over where particular fonts
  126. will be fetched from. Unfortunately there's no program yet that will let
  127. you manage FLIB files; however, the ASCREEN distribution contains a Perl
  128. script that lets you pack a number of PK files into a FLIB file. (I've
  129. only tried it on a UNIX workstation yet, and I don't know whether it
  130. actually works on the Atari.) Some FLIB files with the most important
  131. fonts are available by FTP.
  132.  
  133. GEM message pipe
  134. ----------------
  135. You can send messages to ASCREEN 3.1 via the AES function appl_write(),
  136. thus triggering various functions of the program. Messages have the
  137. general format
  138.  
  139.     word 0:    message type (for ASCREEN, always MSG_ASCREEN = 8196)
  140.     word 1: AES application ID of the sending process
  141.     word 2: Oversize of message (for ASCREEN, mostly 0)
  142.     word 3: message subtype
  143.     word 4: more parameters
  144.        :
  145.  
  146. ASCREEN ignores all messages but those of type MSG_ASCREEN. It
  147. recognizes three different subtypes, namely
  148.  
  149.     MSG_REREAD (1)  the current DVI file will be read again and
  150.         redisplayed. This message is of interest to users of
  151.         PAM's MultiGEM; they can write a program that sends this
  152.         message to ASCREEN after a TeX run so that ASCREEN will
  153.         automatically read the newest DVI file. (But see `Known
  154.         Bugs' below for a caveat.)
  155.     MSG_NEWPAGE (2) ASCREEN sends this message to itself to trigger
  156.         `cache-ahead' of the next page. Other programs may send
  157.         the message, too. Word 4 is the absolute page number of
  158.         the page to be formatted. (The page will not be displayed
  159.         on screen but deposited in cache memory.)
  160.     MSG_NEWWIN (3) This message causes ASCREEN to open a new window.
  161.         Word 4 is 1 for a normal-sized window, 2 for a window that's 
  162.         been reduced by a factor of 2, and 4 for a thrice-reduced
  163.         window; word 5 is the absolute page number of the page to
  164.         be displayed in the window. Words 6-9 (yes, the message is
  165.         oversized) contain the coordinates of the window, frame,
  166.         sliders etc. included.
  167.  
  168. HyperTeX
  169. --------
  170. HyperTeX is an experimental setup for `linked documents', e. g., online
  171. documentation, in LaTeX. Files HYPTEST.TEX, HYPTEST.DVI and HYPERTEX.STY
  172. sketch the LaTeX part of the business (German only, sorry). Essentially,
  173. words that are to be linked are marked up in the source document, and
  174. appropriate \special commands are written to the DVI file. There's also
  175. a HYP file for the document which may be processed by the Perl script,
  176. HYP.PL.
  177.  
  178.     +---------+
  179.     | foo.tex |
  180.     +---------+
  181.          |
  182.        LaTeX
  183.          |        +---------+        +---------+
  184.          +--------->| foo.hyp |-- hyp.pl -->| foo.hl  |
  185.          |        +---------+        +---------+
  186.          |                         |
  187.          |        +---------+             V
  188.          +--------->| foo.dvi |------------>  ASCREEN
  189.             +---------+
  190.  
  191. The HL file is sorted by `links' and allows efficient location of all
  192. references to a key. ASCREEN reads the DVI and HL files and draws a
  193. frame around any link it displays. If you click inside such a frame, a
  194. popup menu appears which will let you jump to the definition, the
  195. previous or the next reference of the link. `Back' lets you roll back
  196. the chain of links followed in the current window, eventually returning
  197. you to the original page. Standard printer drivers shouldn't be bothered
  198. by the \special commands, there might be warnings which can be safely
  199. ignored.
  200.  
  201. Various hints
  202. -------------
  203. 64000 Bytes for unpacked glyphs should be ample.
  204.  
  205. You can page `reduced' windows as well, lock them etc. You can't reduce
  206. them any further, though :-(
  207.  
  208. Known bugs
  209. ----------
  210. Double pages can't be reduced yet (not too bad, just put two windows
  211. next to each other).
  212. Continuously pressing one of a window's arrow icons may cause ASCREEN to
  213. hang if the TOS version used supports icon auto-repeat.
  214. ASCREEN 3.1 keeps the DVI file open during all of the run. This limits the
  215. possibilities of MultiGEM (since TeX can't write on the file while
  216. ASCREEN is using it). An elegant and efficient solution is still
  217. lacking; in the meantime one should enlarge the DVI buffer such that the
  218. file in question fits completely. In this case the DVI file will be read
  219. into memory and then closed immediately afterwards, and TeX can access it.
  220.  
  221. Sad Facts
  222. ---------
  223. ASCREEN contains various unresolved references into code-to-be, e. g.,
  224. menu items and setup parameters for virtual fonts, etc., etc. You may
  225. still hope for all these features, but don't hold your breath waiting
  226. for them; there are other important things for me to do (diploma thesis,
  227. ...)
  228.  
  229. Copying
  230. -------
  231. You may use and copy ASCREEN freely as long as you don't make any money
  232. off it or pretend that you wrote it. If you like the program I'd
  233. appreciate a picture postcard of where you live.
  234.  
  235. Up-to-date Versions
  236. -------------------
  237. ASCREEN's `home site' is ftp.math.uni-frankfurt.de [141.2.90.2]; the
  238. current version is available there as well as FLIB files and other
  239. stuff. Since ASCREEN is freely redistributable, it is likely that it
  240. will turn up at other sites, too.
  241.  
  242. There is a mailing list for ASCREEN announcements, discussions etc.;
  243. send mail to ascreen-request@math.uni-frankfurt.de to find out more.
  244.  
  245. I will snail-mail you the current version of the program if you send me
  246. a formatted 720KB disk together with a self-addressed envelope and
  247. appropriate return postage.
  248.  
  249. Comments, bug reports, proposals, criticism etc.
  250. ------------------------------------------------
  251. are, of course, always welcomed. Please send them to...
  252.  
  253.     Anselm Lingnau
  254.     Buchenweg 1
  255.     6239 Eppstein i. Ts.
  256.     Germany
  257.  
  258.     phone: ++49-6198-8555
  259.     E-Mail:  lingnau@math.uni-frankfurt.de
  260.  
  261.