Path: kernighan.cs.umass.edu!barrett From: kmpty@tomate.tng.oche.de (Andreas Mixich) Newsgroups: comp.sys.amiga.reviews Subject: REVIEW: XRef version 1.1 Followup-To: comp.sys.amiga.programmer Date: 22 Oct 1996 00:25:53 GMT Organization: The Amiga Online Review Column - ed. Daniel Barrett Lines: 298 Sender: amiga-reviews@math.uh.edu (comp.sys.amiga.reviews moderator) Distribution: world Message-ID: <54h4ah$ggb@kernighan.cs.umass.edu> Reply-To: kmpty@tomate.tng.oche.de (Andreas Mixich) NNTP-Posting-Host: knots.cs.umass.edu Keywords: programming, shared library, ARexx, documentation, shareware X-Review-Number: Volume 1996 Number 27 Originator: barrett@knots.cs.umass.edu PRODUCT NAME XRef 1.1 BRIEF DESCRIPTION Package of a shared library, ARexx function-library and utils to generate and handle binary xref files on AutoDocs, Includes, UNIX man pages and AmigaGuides. AUTHOR/COMPANY INFORMATION Address: Stefan Ruppert Windthorststrasse 5 65439 Floersheim am Main GERMANY E-mail: ruppert@vs3.informatik.fh-wiesbaden.de ruppert@goofy.zdv.uni-mainz.de WWW: http://www.uni-mainz.de/~ruppert/amiga/amiga.html LIST PRICE DM 20 or US$ 15 DEMO VERSION Identical with full release. SPECIAL HARDWARE AND SOFTWARE REQUIREMENTS HARDWARE Some harddisk space for installation and to store converted docs is required SOFTWARE AmigaGuide installation AmigaDOS 2.x COPY PROTECTION None HD installation possible, installer script included. MACHINE USED FOR TESTING Amiga 1200, Blizzard 1220 (68020/28), 68882 FPU, 8MB Fast Ram, 540 MB HD AmigaOS 3.0 Amiga 4000, CyberStorm060/CyberSCSI, CyberVision/4 16MB Fast Ram NEC 4x CD-ROM MFC III 2x Floppy Kickstart 40.70, Workbench 40.42 On both machines, several well known patches were installed. INSTALLATION Installation is comfortably done by Commodore's Installer. A second installer scriot exists, to create a basic conversion of all system-Includes&AutoDocs. INTRO Are you a programmer ? Do you like to hit a key in your editor to look up a functions' AutoDoc page ? Do you fear the next time of preparation and conversion of some new AutoDocs with ADoc2XRef ? Or maybe want to convert Includes as well or, include your UNIX man pages in your Amiga-hypertext documentation ? Do you want to have a search capability for XRef entries in your AmigaGuide reader ? Or maybe you want to program a new application, that shall have XRef capabilities ? Or you want to have a standard on your Amiga to access docs in an easy way ? Here is the solution: XRef 1.1 by Stefan Ruppert, who also wrote some well known datatypes as the C-,CLI-,MAN.datatype, the HTDS dataypes system, DTPatch and MultiPrint. FEATURES It will allow you to automatically create binary XRef files of all previously mentioned document types. These XRef files are handled by a shared library, which comes well documented and with all the needed developer stuff. The library offers functions for pattern-matching handling of these XRef files, creation of 'dynamic nodes' for the AmigaGuide system and more. Several tools exist, that may do all you could imagine with the XRef files, like loading them, locking (Avail Flush won't remove them from memory then), print out statistics, general information. The most important tools are the ones you need to generate the XRef files and convert the documents to AmigaGuide format. Another tool allows to generate an AmigaGuide INDEX of one or many AmigaGuide documents at once. The whole system is blazingly fast when compared to the old way in using ADoc2Guide. XRef generation and conversion of all OS3.1 Includes & Autodocs took about 45 minutes on the accelerated A1200, as listed above. Note, that this includes time for loading, scanning, xref-creation, conversion to Amigaguide and writing back to disk. You may get some speed-up if you put the "raw" documents into a Ram Disk. For the text editor 'GoldED V3' there is also an API available, that allows phrase-completion from within the XRef files. Preferences allow to except several expressions and words from being processed when generating XRef files or converting docs to guides. There is also an AmigaGuide-like reader, that will display the documents and features some search-gadgets. There exist versions customized for V37 and V39 of the operating system. An ARexx macro is delivered for looking up the word under the cursor within GoldED V3, but may be adapted easily to any other editor. INSTALLATION It's easy! The Installer script does everything for you. A second Installer script is delievered to create a basic conversion of all System Includes&Autodocs. SOURCE The SAS/C sourcecode is available for all tools, except the libraries. USAGE There are a lot ways to use this nice package. The basic use, of course, is hunting for functions, macros or defines in the system's documentation. Thanks to the ARexx version of the library this is done very easy. Another way to use it is invocation of the special AmigaGuide reader by submitting a pattern. All found occurences will be listed in a dynamic node and are ready for selection. Given the fact, that this is a shared library one might imagine a lot of other functionality: Writing a text reader, that includes XRef support, writing some AmigaGuide authoring tool, that uses the XRefs to generate global links, 'Man'-type programs that not only display documents, but also hunt for specified patterns and a lot more. Don't forget, that you can scan existing AmigaGuides and create XRefs for them. So you are not only forced to ADoc&Inc type docs. PERSONAL EXPERIENCES As soon as I got XRef1.1 I converted all my system's Includes & Autodocs and a bit later the ones supplied with 3rd party distributions, such as MUI or else. Some of the MUI AutoDocs cause probles, but this is due to the fact, that these are not always conforimg the standard. Additionally I have created XRef files which store all my ARexx docs' links (ARexxGuide V2, RexxReqTools.guide and so on) and the SAS/C online help. It might be interesting to create xrefs for the RKM Amigaguide Edition, as available on the CATS V2 CD. Although, I have no experiences with that. One might simply use it for scanning the AmigaE or any other well structured guide, too. I was astonished ! With the aid of this system I was now finally able to generate a documentary on my system, which I can access globally, have a better overview and much more easy access. Also I could wirte a MAN command, that not only would display documents, but search for certain strings in all docs and display found occurances. FAZIT All in all I must say, that this is a tool I have been waiting for a long time and am glad to have it. I believe this will make every programming environment a "Dream Development System" since it offers quick access to all available functions etc. by a simple keystroke. The big speed over ADoc2Guide, the fact of automatically generated XRef files, and the implementation as library make it unique. It is on Aminet for over a year now (dev/misc/xref_v1_1.lha), but seems to be mainly unnoticed. This is the reason I wanted to give it credit. It comes in the status of ShareWare but is uncrippled, no functionality is lacking. The fee is an affordable DM 20 or US$ 15. DOCUMENTATION Documentation is complete. The library comes with includes and an AutoDoc. The tools are documented seperatly, each tool has its own doc. Some additional developer support, that was used during creation of this package is included as well (FinalReadArgs()) For an advanced Amiga user (programmer) there should be nothing lacking. LIKES Well, not much to add. It is really a nice peace of software and I would be glad to see this kind of implementation on any upcoming Amiga operating system implemented from the very beginning. DISLIKES AND SUGGESTIONS No dislikes. I would be glad to see further development being done, and the ARexx library expanded. COMPARISON TO OTHER SIMILAR PRODUCTS ADoc2Guide does a similar task, but is, in opposite to XRef1.1 very limited. BUGS Since AmigaGuide seems to have some problems with paths, it is recommended to add the PATH/K option when generating XRef files and to include the paths, where the converted documents are stored in the $AMIGAGUIDE/PATH variable. Then all should be perfect. You should also edit the second Installer-script not to use an AG: assign. Running a resident MultiView will cause problems, but this is a bug in MultiView's path handling, I believe. The ARexx library returns RC_WARN (RC=5) if no entries were found, which is interpreted by ARexx as 'Unmatched Quote'. VENDOR SUPPORT I have contacted Stefan several times with suggestions and ideas. He was very kind and helpfull. WARRANTY I guess the standard disclaimer for software belongs here.... CONCLUSIONS Product is very good and a brilliant add-on in any developer environment. I would say: It's a must-have ! 4 stars out of 5 COPYRIGHT NOTICE Copyright 1996 Andreas Mixich humpty@tomate.tng.oche.de --- Accepted and posted by Daniel Barrett, comp.sys.amiga.reviews moderator Send reviews to: amiga-reviews-submissions@math.uh.edu Request information: amiga-reviews-requests@math.uh.edu Moderator mail: amiga-reviews@math.uh.edu Anonymous ftp site: math.uh.edu, in /pub/Amiga/comp.sys.amiga.reviews Web site: ftp://math.uh.edu/pub/Amiga/comp.sys.amiga.reviews/index.html