Subject: REVIEW: XRef version 1.1
From: [email-masked] (Andreas Mixich)
Date: 22 Oct 1996 00:25:53 GMT
Newsgroups: comp.sys.amiga.reviews

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:		[email-masked]
			[email-masked]
	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
	[email-masked]

---

   Accepted and posted by Daniel Barrett, comp.sys.amiga.reviews moderator
   Send reviews to:	[email-masked]
   Request information:	[email-masked]
   Moderator mail:	[email-masked]
   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