home *** CD-ROM | disk | FTP | other *** search
/ Amiga MA Magazine 1998 #6 / amigamamagazinepolishissue1998.iso / www / cucug / amiga / amiinfo / reviews / xref.txt < prev    next >
Internet Message Format  |  1997-11-07  |  10KB
  1. Path: kernighan.cs.umass.edu!barrett
  2. From: kmpty@tomate.tng.oche.de (Andreas Mixich)
  3. Newsgroups: comp.sys.amiga.reviews
  4. Subject: REVIEW: XRef version 1.1
  5. Followup-To: comp.sys.amiga.programmer
  6. Date: 22 Oct 1996 00:25:53 GMT
  7. Organization: The Amiga Online Review Column - ed. Daniel Barrett
  8. Lines: 298
  9. Sender: amiga-reviews@math.uh.edu (comp.sys.amiga.reviews moderator)
  10. Distribution: world
  11. Message-ID: <54h4ah$ggb@kernighan.cs.umass.edu>
  12. Reply-To: kmpty@tomate.tng.oche.de (Andreas Mixich)
  13. NNTP-Posting-Host: knots.cs.umass.edu
  14. Keywords: programming, shared library, ARexx, documentation, shareware
  15. X-Review-Number: Volume 1996 Number 27
  16. Originator: barrett@knots.cs.umass.edu
  17.  
  18.  
  19. PRODUCT NAME
  20.  
  21.        XRef 1.1
  22.  
  23.  
  24. BRIEF DESCRIPTION
  25.  
  26.     Package of a shared library, ARexx function-library and utils
  27. to generate and handle binary xref files on AutoDocs, Includes, UNIX
  28. man pages and AmigaGuides.
  29.  
  30.  
  31.  
  32. AUTHOR/COMPANY INFORMATION
  33.  
  34.     Address:    Stefan Ruppert
  35.             Windthorststrasse 5
  36.             65439 Floersheim am Main
  37.             GERMANY
  38.  
  39.     E-mail:        ruppert@vs3.informatik.fh-wiesbaden.de
  40.             ruppert@goofy.zdv.uni-mainz.de
  41.     WWW:        http://www.uni-mainz.de/~ruppert/amiga/amiga.html
  42.  
  43.  
  44. LIST PRICE
  45.  
  46.     DM 20 or US$ 15
  47.  
  48.  
  49. DEMO VERSION
  50.  
  51.     Identical with full release.
  52.  
  53.  
  54. SPECIAL HARDWARE AND SOFTWARE REQUIREMENTS
  55.  
  56.  
  57.     HARDWARE
  58.  
  59.         Some harddisk space for installation and to store
  60.         converted docs is required
  61.  
  62.     SOFTWARE
  63.     
  64.         AmigaGuide installation
  65.         AmigaDOS 2.x
  66.  
  67.  
  68. COPY PROTECTION
  69.  
  70.     None
  71.  
  72.     HD installation possible, installer script included.
  73.  
  74.  
  75. MACHINE USED FOR TESTING
  76.  
  77.  
  78.     Amiga 1200, Blizzard 1220 (68020/28), 68882 FPU, 8MB Fast Ram,
  79.     540 MB HD
  80.     AmigaOS 3.0
  81.  
  82.     Amiga 4000, CyberStorm060/CyberSCSI,
  83.     CyberVision/4
  84.     16MB Fast Ram
  85.     NEC 4x CD-ROM
  86.     MFC III
  87.     2x Floppy
  88.     Kickstart 40.70, Workbench 40.42
  89.  
  90.     On both machines, several well known patches were installed.
  91.  
  92.     
  93.  
  94. INSTALLATION
  95.  
  96.     Installation is comfortably done by Commodore's Installer.
  97.     A second installer scriot exists, to create a basic conversion
  98.     of all system-Includes&AutoDocs.
  99.  
  100.  
  101. INTRO
  102.  
  103.     Are you a programmer ? Do you like to hit a key in your editor to
  104.     look up a functions' AutoDoc page ? Do you fear the next time of
  105.     preparation and conversion of some new AutoDocs with ADoc2XRef ?
  106.     Or maybe want to convert Includes as well or, include your UNIX man
  107.     pages in your Amiga-hypertext documentation ?
  108.  
  109.     Do you want to have a search capability for XRef entries in your
  110.     AmigaGuide reader ?
  111.  
  112.     Or maybe you want to program a new application, that shall have XRef
  113.     capabilities ?
  114.  
  115.     Or you want to have a standard on your Amiga to access docs in an
  116.     easy way ?
  117.  
  118.     Here is the solution: XRef 1.1 by Stefan Ruppert, who also wrote
  119.     some well known datatypes as the C-,CLI-,MAN.datatype,
  120.     the HTDS dataypes system, DTPatch and MultiPrint.
  121.  
  122.  
  123. FEATURES
  124.  
  125.     It will allow you to automatically create binary XRef files of
  126.     all previously mentioned document types. These XRef files are
  127.     handled by a shared library, which comes well documented and
  128.     with all the needed developer stuff. The library offers
  129.     functions for pattern-matching handling of these XRef files,
  130.     creation of 'dynamic nodes' for the AmigaGuide system and
  131.     more. Several tools exist, that may do all you could imagine
  132.     with the XRef files, like loading them, locking (Avail Flush
  133.     won't remove them from memory then), print out statistics,
  134.     general information. The most important tools are the ones you
  135.     need to generate the XRef files and convert the documents to
  136.     AmigaGuide format.  Another tool allows to generate an
  137.     AmigaGuide INDEX of one or many AmigaGuide documents at once.
  138.  
  139.     The whole system is blazingly fast when compared to the old way in
  140.     using ADoc2Guide. XRef generation and conversion of all OS3.1
  141.     Includes & Autodocs took about 45 minutes on the accelerated A1200,
  142.     as listed above. Note, that this includes time for loading,
  143.     scanning, xref-creation, conversion to Amigaguide and writing back
  144.     to disk. You may get some speed-up if you put the "raw" documents
  145.     into a Ram Disk.
  146.  
  147.     For the text editor 'GoldED V3' there is also an API available, that
  148.     allows phrase-completion from within the XRef files.
  149.  
  150.     Preferences allow to except several expressions and words from
  151.     being processed when generating XRef files or converting docs
  152.     to guides.
  153.  
  154.     There is also an AmigaGuide-like reader, that will display the
  155.     documents and features some search-gadgets. There exist
  156.     versions customized for V37 and V39 of the operating system.
  157.  
  158.     An ARexx macro is delivered for looking up the word under the
  159.     cursor within GoldED V3, but may be adapted easily to any
  160.     other editor.
  161.  
  162.  
  163.  
  164. INSTALLATION
  165.  
  166.     It's easy! The Installer script does everything for you.  A
  167.     second Installer script is delievered to create a basic
  168.     conversion of all System Includes&Autodocs.
  169.  
  170.  
  171. SOURCE
  172.  
  173.     The SAS/C sourcecode is available for all tools, except the
  174.     libraries.
  175.  
  176.  
  177. USAGE
  178.  
  179.     There are a lot ways to use this nice package. The basic use, of
  180.     course, is hunting for functions, macros or defines in the system's
  181.     documentation. Thanks to the ARexx version of the library this is
  182.     done very easy.
  183.  
  184.     Another way to use it is invocation of the special AmigaGuide reader by
  185.     submitting a pattern. All found occurences will be listed in a dynamic
  186.     node and are ready for selection.
  187.  
  188.     Given the fact, that this is a shared library one might imagine a lot
  189.     of other functionality:  Writing a text reader, that includes XRef
  190.     support, writing some AmigaGuide authoring tool, that uses the XRefs to
  191.     generate global links, 'Man'-type programs that not only display
  192.     documents, but also hunt for specified patterns and a lot more.
  193.  
  194.     Don't forget, that you can scan existing AmigaGuides and create
  195.     XRefs for them. So you are not only forced to ADoc&Inc type docs.
  196.  
  197. PERSONAL EXPERIENCES
  198.  
  199.     As soon as I got XRef1.1 I converted all my system's Includes &
  200.     Autodocs and a bit later the ones supplied with 3rd party
  201.     distributions, such as MUI or else. Some of the MUI AutoDocs cause
  202.     probles, but this is due to the fact, that these are not always
  203.     conforimg the standard.
  204.  
  205.     Additionally I have created XRef files which store all my ARexx docs'
  206.     links (ARexxGuide V2, RexxReqTools.guide and so on) and the SAS/C
  207.     online help. It might be interesting to create xrefs for the RKM
  208.     Amigaguide Edition, as available on the CATS V2 CD. Although, I have
  209.     no experiences with that.
  210.  
  211.     One might simply use it for scanning the AmigaE or any other well
  212.     structured guide, too.
  213.  
  214.     I was astonished ! With the aid of this system I was now finally able
  215.     to generate a documentary on my system, which I can access globally,
  216.     have a better overview and much more easy access.
  217.  
  218.     Also I could wirte a MAN command, that not only would display
  219.     documents, but search for certain strings in all docs and display found
  220.     occurances.
  221.  
  222.  
  223. FAZIT
  224.  
  225.     All in all I must say, that this is a tool I have been waiting for a
  226.     long time and am glad to have it. I believe this will make every
  227.     programming environment a "Dream Development System" since it offers
  228.     quick access to all available functions etc. by a simple keystroke.
  229.     The big speed over ADoc2Guide, the fact of automatically generated XRef
  230.     files, and the implementation as library make it unique.
  231.  
  232.     It is on Aminet for over a year now (dev/misc/xref_v1_1.lha), but
  233.     seems to be mainly unnoticed. This is the reason I wanted to give it
  234.     credit. It comes in the status of ShareWare but is uncrippled, no
  235.     functionality is lacking. The fee is an affordable DM 20 or US$ 15.
  236.  
  237.  
  238. DOCUMENTATION
  239.  
  240.     Documentation is complete. The library comes with includes and
  241.     an AutoDoc.  The tools are documented seperatly, each tool has
  242.     its own doc.  Some additional developer support, that was used
  243.     during creation of this package is included as well
  244.     (FinalReadArgs())
  245.  
  246.     For an advanced Amiga user (programmer) there should be
  247.     nothing lacking.
  248.  
  249. LIKES
  250.  
  251.     Well, not much to add. It is really a nice peace of software and
  252.     I would be glad to see this kind of implementation on any upcoming
  253.     Amiga operating system implemented from the very beginning.
  254.  
  255.  
  256. DISLIKES AND SUGGESTIONS
  257.  
  258.     No dislikes. I would be glad to see further development being done,
  259.     and the ARexx library expanded. 
  260.  
  261.  
  262. COMPARISON TO OTHER SIMILAR PRODUCTS
  263.  
  264.     ADoc2Guide does a similar task, but is, in opposite to XRef1.1 very
  265.     limited.
  266.  
  267.  
  268. BUGS
  269.  
  270.     Since AmigaGuide seems to have some problems with paths, it is
  271.     recommended to add the PATH/K option when generating XRef files and to
  272.     include the paths, where the converted documents are stored in the
  273.     $AMIGAGUIDE/PATH variable. Then all should be perfect. You should
  274.     also edit the second Installer-script not to use an AG: assign.
  275.     Running a resident MultiView will cause problems, but this is a bug
  276.     in MultiView's path handling, I believe.
  277.  
  278.     The ARexx library returns RC_WARN (RC=5) if no entries were
  279.     found, which is interpreted by ARexx as 'Unmatched Quote'.
  280.  
  281.  
  282. VENDOR SUPPORT
  283.  
  284.     I have contacted Stefan several times with suggestions and ideas.
  285.     He was very kind and helpfull.
  286.  
  287.  
  288. WARRANTY
  289.  
  290.     I guess the standard disclaimer for software belongs here....
  291.  
  292.  
  293. CONCLUSIONS
  294.  
  295.     Product is very good and a brilliant add-on in any developer
  296. environment.  I would say: It's a must-have !
  297.  
  298.     4 stars out of 5
  299.  
  300.  
  301.  
  302. COPYRIGHT NOTICE
  303.  
  304.  
  305.     Copyright 1996 Andreas Mixich
  306.     humpty@tomate.tng.oche.de
  307.  
  308. ---
  309.  
  310.    Accepted and posted by Daniel Barrett, comp.sys.amiga.reviews moderator
  311.    Send reviews to:    amiga-reviews-submissions@math.uh.edu
  312.    Request information:    amiga-reviews-requests@math.uh.edu
  313.    Moderator mail:    amiga-reviews@math.uh.edu
  314.    Anonymous ftp site:  math.uh.edu, in /pub/Amiga/comp.sys.amiga.reviews
  315.    Web site: ftp://math.uh.edu/pub/Amiga/comp.sys.amiga.reviews/index.html
  316.