home *** CD-ROM | disk | FTP | other *** search
/ Crawly Crypt Collection 1 / crawlyvol1.bin / utility / misc / gloss_it / read.me < prev   
Text File  |  1987-04-21  |  18KB  |  479 lines
  1.  
  2.  
  3.  
  4.     0. Manual for GLOSS_IT! β0.015
  5.     ==============================
  6.  
  7.          (Revised 01.03.90)
  8.  
  9.  
  10. A. Presentation
  11. B. Introduction
  12.   1. Why GLOSS_IT! ?
  13.   2. What GLOSS_IT! is
  14. C. Tutorial
  15.   1. Configuration
  16.   2. Basic use of GLOSS_IT!
  17.   3. JULIET
  18.   4. ADDRESS
  19.   5. HELLO
  20.   6. How Use GLOSS_IT! with your own files
  21. D. Keyboard shortcuts
  22. E. Limits
  23. F. Copyright
  24. E. Final remark
  25.  
  26.     A. Presentation
  27.     ===============
  28.  
  29.     Version DEMO ß0.015 , 1 march 1990.
  30.  
  31.     This version is Public Domain. Not to be sold.
  32.     Demo limitations : 6 files, 3 indexes, 8 keywords, no free of 
  33.     memory.
  34.  
  35.     Hypertext program on ATARI ST by :
  36.         Patrick INSTALLE
  37.         Av. Minerve, 8
  38.         B-1190 Bruxelles Belgium
  39.         Phone : 32.2.358 35 30
  40.         bitnet : R11102@BBRBFU01.bitnet
  41.         BBS : RATS database Antwerpen 32,3,2338928
  42.  
  43.     You should find in the GLOSS_IT.TOS (self extracting LZH-archives) 
  44. the files :
  45.  
  46.     GLOSS_IT.PRG The program.
  47.     READ.ME      This file.
  48.  
  49.     DEMO.CNF     Configuration for the DEMO (use directory A:\)
  50.     READ_ME.CNF  Configuration to look into the READ.ME file
  51.  
  52.     JULIET.ASC   Romeo and Juliet example file.
  53.     JULIET.ID0   Main index of JULIET.ASC.
  54.     JULIET.ID1   Slave index of JULIET.ASC.
  55.  
  56.     ADDRESS.ASC  Address coming from a database program
  57.     ADDRESS.ID0  Main index of ADDRESS.ASC
  58.     ADDRESS.ID1  Slave index of ADDRESS.ASC
  59.  
  60.     HELLO.ASC    C program
  61.     HELLO.ID0    Main index of HELLO.C
  62.     GEMLIB.ASC   Part of GEM library
  63.     GEMLIB.ID0   Main index of GEMLIB.ASC
  64.  
  65.     For the basic operation (menu, windows, mouse, ...) please refer 
  66. to the user manual of your ATARI ST.
  67.  
  68.  
  69.     B. Introduction
  70.     ===============
  71.  
  72.     GLOSS_IT! is a hypertext concept developed on and for the ATARI 
  73. ST.
  74.  
  75.     GLOSS_IT! develops the idea of lexicons or glossaries to access 
  76. and easily explore any kind of text file. This can be plain text, 
  77. program source code, a database containing any kind of information, 
  78. etc.
  79.  
  80.     GLOSS_IT! tremendously improves the accesses to keywords and 
  81. establishes dynamic links into the file, and between files.
  82.  
  83.     B.1. Why GLOSS_IT! ?
  84.     ____________________
  85.  
  86.     I was looking for an alternative solution to paper and pencil for 
  87. research and development in the field of biology. Therefore I needed 
  88. to edit and make quick references to methods, procedures, materials, 
  89. literature references,..and be able to come back exactly to my 
  90. starting point.
  91.  
  92.     Which tools exist on the market :
  93.  
  94.     a) The word processors
  95.  
  96.     Certainly the most common programs on computers, but the time to 
  97. find a definite information in one or several large files (and come 
  98. back to the original place after having read this information...) is 
  99. too long.
  100.  
  101.     b) The databases
  102.  
  103.     The structure of the databases (which made them so useful) doesn't 
  104. follow the dynamic evolution of a text. The databases don't support 
  105. the concept of recursively.
  106.  
  107.     c) The Hypertexts
  108.  
  109.     The hypertexts require the definitions of buttons and links to the 
  110. destination(s) and eventually from them, and this to multiple files. 
  111. In these conditions, the hypertext doesn't support the evolution of 
  112. your text.
  113.  
  114.     B.2. What GLOSS_IT! is
  115.     ______________________
  116.  
  117.     Like an editor, GLOSS_IT! lets you access text files (using the 
  118. usual ASCII conventions). But GLOSS_IT!, by itself, doesn't allow you 
  119. to edit the text.
  120.  
  121.     Like a database GLOSS_IT! uses indexes. You can use several 
  122. indexes for each file, use several files simultaneously, and freely 
  123. access each file. But GLOSS_IT! neither modifies, nor organises your 
  124. information in any way.
  125.  
  126.     Like an hypertext GLOSS_IT! gives you the possibility to make 
  127. successive  choices without any predetermined structure. But GLOSS_IT! 
  128. doesn't give you the possibility to set the link or to make any 
  129. treatment of the informations between the selection and the 
  130. destination.
  131.  
  132.     C. Tutorial
  133.     ===========
  134.  
  135.     C.1. Configuration
  136.     __________________
  137.  
  138.     The first contact with GLOSS_IT! is the choice of a configuration 
  139. file. If you work with drive A:\, use DEMO.CNF directly, otherwise 
  140. cancel. GLOSS_IT! verifies the date and time of your file. With the 
  141. unpacking of the file the date of the files has changed, and then 
  142. GLOSS_IT! will "refresh" your indexes.
  143.  
  144.     Open "Utilities","CONFIGURATION", "  Set-up ..." dialogue. This 
  145. dialogue shows you several parameters of your present configuration.
  146.  
  147.     Auto load : When this button is checked it means that the auto 
  148. loading of data is chosen. The usual (*,?) wild cards are accepted for 
  149. file names.
  150.  
  151.     Data : Always checked. This is the default directory for your 
  152. texts.
  153.  
  154.     Alternate : If you want to use a different directory for the 
  155. indexes, select the box "Alternate" and the corresponding path.
  156.  
  157.     Temporary : For large files, GLOSS_IT! could need to make Indexes 
  158. in a temporary directory. Select the box "Temporary" and the 
  159. corresponding path.
  160.  
  161.     Program : You specify here the editor program you want to call and 
  162. execute in order to be able to edit your file. You will be able to 
  163. call it very easily by keeping the right mouse button down while 
  164. clicking on the left one. The parameter send to the program is 
  165. actually the name of the top window file, the number of the line and 
  166. column selected.
  167.  
  168.     Set Autoload to the drive, directory and file you want. "A:\*.ASC" 
  169. for example. Do the same for the Data. Confirm your choice.
  170.  
  171.     In the box " Input " switch the control of date and time of the 
  172. index to " Update index ". When " Keep old index " is set then the 
  173. indexes are never updated (CDROM files !), with " Ask new index " a 
  174. dialogue box is presented when needed.
  175.         Back to the menu, save your new configuration file as 
  176. DEMO2.CNF.
  177.  
  178.     If you don't already have the demonstration file on the GLOSS_IT! 
  179. desktop, with the menu item "Utilities", "CONFIGURATION", "  Load ", 
  180. load the DEMO2.CNF.
  181.  
  182.    At this stage you should have the demonstrations series of files 
  183. JULIET, ADDRESS, HELLO, GEMLIB on the GLOSS_IT! desktop.
  184.  
  185.     C.2. Basic use of GLOSS_IT!
  186.     ___________________________
  187.  
  188.     When you double click on the desktop on one of the large text 
  189. icons (looking like closed books), the entire text is loaded and shown 
  190. in a window.
  191.  
  192.     When you double click on the desktop on one of the small icons 
  193. associated to a text, the corresponding index is shown.
  194.  
  195.     When you click in an index window, the corresponding subject is 
  196. loaded and shown.
  197.  
  198.     When you click in a subject window, the program searches a keyword 
  199. that fits the word(s) under the arrow.
  200.  
  201.     When you press the right button and click (with the left button) 
  202. GLOSS_IT! executes an external program with arguments corresponding to 
  203. the position you are looking at (clicking, actually!) in the upper 
  204. window. (the filename of the upper window, the line and the column of 
  205. the text are send as arguments). My favourite editor is Tempus, which 
  206. handles all this gracefully, but you can use any good (and clean!) 
  207. editor for this job.
  208.  
  209.     C.3. JULIET
  210.     ___________
  211.  
  212.     This file actually consists of the first few pages of the well-
  213. known Shakespeare play "Romeo and Juliet". this is the first example 
  214. file we will use.
  215.  
  216.     On the desktop of GLOSS_IT!, you should have :
  217.  
  218.         JULIET.ASC Romeo and Juliet sample file.
  219.         JULIET.ID0 Main index of JULIET.ASC.
  220.         JULIET.ID1 Slave index of JULIET.ASC.
  221.  
  222.     Select and open the file JULIET.ASC from the GLOSS_IT! desktop. 
  223. The text of JULIET.ASC is loaded, and a window with the text opened. 
  224. Discover it. Close the window.
  225.  
  226.     Select and open the two indexes JULIET.ID0 and JULIET.ID1. Look at 
  227. them. Close the windows.
  228.  
  229.     Open the JULIET.ID0. and select (click on...) any keyword. The 
  230. keyword and the corresponding subject is automatically called and 
  231. displayed. Come back to the main index by closing the window.
  232.  
  233.     In the main index ID0, choose the keyword "I.1" then select 
  234. "Sampson". Immediately at the top of the window the keyword "Sampson" 
  235. is displayed with the related text.
  236.  
  237.     Select "Capulet" in this new subject . Now you move in the same 
  238. main keyword "Character of the play" to another "slave" index 
  239. "Capulet".
  240.  
  241.     If you are not familiar with the text you could also ask, from the 
  242. "Utilities" menu for the "Subject's set" that gives you all 'callable' 
  243. words of a subject.
  244.  
  245.     C.4. ADDRESS
  246.     ____________
  247.  
  248.     ADDRESS.ASC is a part of a database in text ASCII file.
  249.  
  250.     On the desktop of GLOSS_IT! you should have :
  251.  
  252.         ADDRESS.ASC Address file coming from a database program
  253.         ADDRESS.ID0 Main index of ADDRESS.ASC.
  254.         ADDRESS.ID1 Slave index of ADDRESS.ASC.
  255.  
  256.     Select and open the file ADDRESS.ASC from the GLOSS_IT! desktop. 
  257. The text of ADDRESS.ASC is loaded, and a window with the text opened. 
  258. Discover it. Close the window.
  259.  
  260.     Select and open the two indexes ADDRESS.ID0 and ADDRESS.ID1. Look 
  261. at them. Close the windows.
  262.  
  263.     Open again the file ADDRESS.ASC. Select in the menu "Files" 
  264. "Index" "Make...". You get the dialogue "Make Index" on top of the 
  265. screen and behind the window with the display of ADDRESS.ASC.
  266.  
  267. - MAIN - SLAVE Index
  268.  
  269.     The definition of a subject is the text that is contained between 
  270. two main indexed keywords.
  271.     The Main(s) index(es) determines itself keywords but also the 
  272. limit of the keyword subjects.! The indexes *.ID0 are always main 
  273. indexes.     At the top right of the dialogue you find "Main Index". 
  274. Select this button to switch in "Slave Index".  The Slave indexes 
  275. don't modify the definition of the subjects.
  276.     Change the extension of the index to ID2.
  277.  
  278. - FLAG
  279.  
  280.     The flag is the way GLOSS_IT! is able to determine the position of 
  281. the
  282. keywords.
  283.     With the box " Flag " you determine the flag of your keywords.         
  284. Try "Start at column" "000" "PRENOM- ".
  285.  
  286. - KEY(word)
  287.  
  288.     The keywords themselves are related to the Flag.
  289.     With the box "KEY" you determine the keywords
  290.     Try "On line" "000"               (the line of the flag)
  291.         "Start at column" "009"       (start column is number 0).
  292.         "End at column"   "080"       (at maximum)
  293.  
  294.     Confirm and choose the ADDRESS.ASC file in the files selector. 
  295. After a few seconds, the index is made and ready to use.
  296.  
  297.     GLOSS_IT! doesn't automatically add the index to its desktop. You 
  298. have to close the file ADDRESS.ASC. After having selected the file to 
  299. close, select in the menu "Files" "TEXT" "Close". Then load the file 
  300. ADDRESS.ASC and look at the new index you have made.
  301.  
  302.  
  303.     C.5. HELLO
  304.     __________
  305.  
  306.     HELLO.ASC is a small program in C language.
  307.  
  308.     On the desktop of GLOSS_IT! you should have :
  309.  
  310.         HELLO.ASC   C program.
  311.         HELLO.ID0   Main index of hello.C.
  312.         GEMLIB.ASC  Part of GEM library.
  313.         GEMLIB.ID0  Main index of GEMLIB.ASC.
  314.  
  315.     Select and open the file HELLO.ASC from the GLOSS_IT! desktop. The 
  316. text of HELLO.ASC is loaded, and a window with the text opened. 
  317. Discover it. Close the window. Do the same with GEMLIB.ASC.
  318.  
  319.     Select and open the two indexes HELLO.ID0 and GEMLIB.ID1. Look at 
  320. them. Close the windows.
  321.  
  322.     Open again HELLO.ID0. Select the keyword "main". The subject 
  323. "main" is then displayed. In this subject select the GEM function 
  324. "appl_init" GLOSS_IT! then display the subject "appl_init" from the 
  325. GEMLIB.ASC file. Go back. Select "alert". GLOSS_IT! will show the 
  326. subject "alert" of HELLO.ASC. In the subject "alert" select 
  327. "form_alert". GLOSS_IT! will show you now the subject "form_alert". 
  328. Come back to the desktop.
  329.  
  330.     Open the main subject with the menu item "Utilities" "SEARCH" 
  331. "Find" then enter the word "main" in the edit box and execute the 
  332. search. In this way you go directly to the called subject. Close the 
  333. subject "main".
  334.  
  335.     Execute the Search for "a". GLOSS_IT! finds some occurrence of "a" 
  336. in the keywords available, then it automatically constructs a Set of 
  337. key-words with all the keywords with a "a".
  338.  
  339.  
  340.     C.6. How to use GLOSS_IT! with your own files
  341.     _____________________________________________
  342.  
  343.     In order to be accessible to GLOSS_IT!, your file should contain 
  344. some structure.
  345.  
  346.     This structure can be of many different natures:
  347.  
  348.     Each logical element of your file that you intend to use as a 
  349. keyword should start on a definite column, with a definite type of 
  350. pattern, with a definite word or letter, etc.
  351.  
  352.     Look at the present file "READ.ME" : every head of a paragraph is 
  353. either underlined with "=" or with "_" signs. These are the flags used 
  354. by GLOSS_IT! to make the main and  the secondary indexes, and find 
  355. back these particular places in the file.
  356.  
  357.     Look also for instance at the Juliet file:
  358.  
  359.     In the part containing the characters of the play, each name is on 
  360. a line beginning with the sequence "-  ". This is the motif you use to 
  361. define the keywords in the file, where one of the characters makes a 
  362. statement. Note that the name of a character is the only word on this 
  363. line.
  364.  
  365.     Similarly, if you want to exploit GLOSS_IT! on some C source code, 
  366. you can choose to start each function with a specific pattern. Look at 
  367. "HELLO.ASC" and "GEMLIB.ASC" files. Each function starts with its name 
  368. commented out using usual C-like syntax. The motif "/*-" will be 
  369. looked for, and the keyword is said to reside on the following line, 
  370. in position 3 on this line. Note that the program counts the first 
  371. position as 0, in true C fashion!
  372.  
  373.     It is sufficient to respect some systematic way of writing the 
  374. header of functions, in order to find very easily the called 
  375. functions, the arguments they use, the types of the variables, etc. 
  376. The fact that GLOSS_IT! also gracefully calls your favourite editor, 
  377. with the line and column you have selected in your text makes it an 
  378. invaluable tool for any program developer.
  379.  
  380.    So, if you want to get the best out of GLOSS_IT!, have some kind of 
  381. organisation in the file, and more precisely in the part of it where 
  382. you want to define the keywords.
  383.  
  384.     GLOSS_IT! has been used by several people, working in very 
  385. different contexts from journalism (to keep various kind of documents 
  386. in an ordered and manageable manner) to laboratory practice (files of 
  387. how to prepare all kind of solutions, with the quantities, 
  388. concentrations, volumes, etc) and especially in computer programming! 
  389. In fact, the author of GLOSS_IT! extensively used (and still uses...) 
  390. GLOSS_IT! to develop the program itself. .
  391.  
  392.  
  393.     D. Keyboard shortcuts
  394.     =====================
  395.  
  396. F1               : Previous subject
  397. F2               : Next subject
  398. ^P (Control+P)   : Print Top Window (all the index or subject)
  399. ^Q Control+Q     : Quit
  400. ^U Control+U     : Close window(and show previous)
  401. Clr(Shift Home)  : Delete the stack of the top window;
  402. Up arrow         : row up
  403. Down arrow       : row down
  404. Shift up arrow   : pageup
  405. Shift down arrow : page down
  406.  
  407.     E. Limits
  408.     =========
  409.  
  410.     The limits of the full blown GLOSS_IT! program are :
  411.     - Number of File    : 24.
  412.     - Number of Indexes : 6 for each file.
  413.     - Windows           : 8 (or less, depending on your configuration)
  414.     - Line length       : 255 characters.
  415.     - File length       : only depends on your hardware (mass memory)
  416.     - Subject length    : limited by memory
  417.     - Number of keys    : limited by memory.
  418.  
  419.     The limits of the Accessory are :
  420.     - Number of File    : 1
  421.     - Number of Index   : 3
  422.     - Windows           : 1
  423.     - Line length       : 255 characters.
  424.     - File length       : no limit
  425.     - Subject length    : limited by memory
  426.     - Number of keys    : limited by memory.
  427.  
  428.     The demo program and accessory are limited by :
  429.     - 6 files
  430.     - 3 indexes
  431.     - 8 keywords each index
  432.     - The program doesn't free the memory.
  433.  
  434.     The time to make an index is in the range of 1 min/megabyte of 
  435. text with a 65 ms hard disk.
  436.  
  437.     The indexes are about 5-10 % of the length of the source text. The 
  438. use of GLOSS_IT! with CDROM is as easy as with floppy disk. A database 
  439. of 20 Mb is actually used, with about 2 Mb of indexes in central 
  440. memory.
  441.  
  442.     On a standard Atari ST (68000, 8MHz), the program requires about 
  443. 1 second of search for 5000 keywords. Note that the indexes are loaded 
  444. in memory. This can take several seconds for large indexes.
  445.  
  446.     F. Copyright
  447.     ============
  448.  
  449.     This manual and the accompanying computer program are copyright 
  450. (c)1989 by Patrick INSTALLE. They may not be copied by any means 
  451. without the prior written permission from the author. Purchasers may 
  452. only make copies for use on their own system.
  453.  
  454.     There are no warranty expressed or implied concerning the 
  455. applicability of this program to any specific purpose. It is solely 
  456. the purchaser's responsibility to determine the suitability for a 
  457. particular application.
  458.  
  459.     I accept no liability for loss or damages caused or alleged to be 
  460. caused, directly or indirectly, by programs sold, including, but not 
  461. limited to, any interruption of service, loss of business, or 
  462. anticipated profits.    This statement of limited liability is in lieu 
  463. of all other warranties or garantees, expressed or implied, including 
  464. warranties of merchantability or fitness for a particular purpose.
  465.  
  466.     E. Final remark
  467.     ===============
  468.  
  469.     Your comments regarding GLOSS_IT! program or any suggestions you 
  470. have for extensions are welcome. The disponibility of a commercial 
  471. full version will depend of your reactions.
  472.  
  473.  
  474.  
  475.      Bruxelles, the 1 march 1990.
  476.  
  477.       INSTALLE, Patrick 
  478.  
  479.