home *** CD-ROM | disk | FTP | other *** search
/ BCI NET 2 / BCI NET 2.iso / archives / programming / misc / xref_v1.1.lha / XRef / Doc / english / xref-system.doc < prev    next >
Encoding:
Text File  |  1995-01-26  |  16.3 KB  |  459 lines
  1.  
  2.  
  3. Cross-Reference-System (XRef-System)
  4. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  5.  
  6. Welcome to the XRef-System Version 1.1.
  7.  
  8. The XRef-System is a cross-reference system using the AmigaGuide Format to display
  9. documents. It provides many more features than normal AmigaGuide XRefs. It is much
  10. faster, more flexible and allows you to easily add own projects.
  11.  
  12. Topics :
  13.  
  14.       Copyright and Registration
  15.       XRef-System and Feature List
  16.       Installation
  17.       XRef.Library
  18.       Tools
  19.       How to use it for own projects
  20.       To Do
  21.       Thanks
  22.       Address
  23.       Compiler and Software Tools
  24.       AmigaGuide Setup and Problems
  25.  
  26. xref.library :
  27.       Documentation
  28.       History
  29.  
  30.  
  31.  
  32. The XRef-System is Shareware, but has no restrictions.
  33.  
  34. Permission is hereby granted to distribute the program's archive
  35. containing the executable's and documentation for non-commercial purposes
  36. as long as the archive and its contents are not modified in any way.
  37. You can modify the given tools for your own use, but don't distribute such
  38. changed files !!! You can send me these changes, so that I can coordinate the
  39. distribution of the XRef-System !!!
  40.  
  41. It is forbidden to include this archive in any kind of software collection
  42. except the Fish Amiga-Library, AmiNet-CD/FileServer or BBS fileareas !
  43.  
  44. No guarantee of any kind is given that the programs described in
  45. this document are 100% reliable. You are using this material at your
  46. own risk. The author takes no responsibility for any damage which 
  47. is caused by using these programs.
  48.  
  49. Registration :
  50.  
  51. If you use the XRef-System, you have to send me a fee of DM 20 or US$ 15.
  52. If you do so, send the fee to the following address:
  53.  
  54. Stefan Ruppert
  55. Windthorststraße 5
  56. 65439 Flörsheim am Main
  57. GERMANY
  58.  
  59. EMail: rupperts3.informatik.fh-wiesbaden.de
  60.  
  61. Copyright (C) 1994,1995 by Stefan Ruppert
  62.  
  63.  
  64.  
  65. The main reason for writing the XRef-System was that the current implementation of
  66. the amigaguide.library is very slow. Also, I wanted to integrate some concepts from
  67. HotHelp (such as searching using patterns), which has the disadvantage of not
  68. supporting the AmigaGuide document standard.
  69. The result satisfies my demands, and I think it is a very useful utility especially
  70. for programmers.
  71. All programs and the library are compiled with SAS-C V6.50! (see Compiler and Software
  72. Tools)
  73.  
  74. Note: All the links you see within this database are generated via the
  75.       XRefConvert tool (except of three links, which I had to create manually).
  76.  
  77. These are the features the XRef-System offers you:
  78.  
  79.          o generates xref entries for almost any C expression (#defines,
  80.            #includes, structures, functions, typedefs etc.), for Commodore's
  81.            autodoc file format, amigaguide files, and unix man pages.
  82.  
  83.          o XRefConvert - A tool to convert all common files to AmigaGuide
  84.            databases (autodoc files, header files, doc files and other
  85.            AmigaGuide files).
  86.            Now implements an option to generate AmigaGuide files for use with
  87.            the amigaguide.datatype V40 and higher, using the smartwrap
  88.            algorithm.
  89.  
  90.          o optional search with AmigaDOS patterns. In case of more than one
  91.            entry is matching, XRef generates a temporary AmigaGuide database
  92.            (AGuideXRefV37).
  93.  
  94.          o a new tool replacing AmigaGuide, which has a direct interface to
  95.            the xref.library and some additional features (AGuideXRefV39)
  96.  
  97.          o xref files can be held resident in memory (xref.library). It is
  98.            also possible to lock individual databases, so that they can't be
  99.            freed when memory is flushed.
  100.  
  101.          o xref.library can be configured via xref.prefs, with AUTOOPEN
  102.            mechanism during xref.library startup and some global settings.
  103.  
  104.          o xref database files can have different priorities assigned, so that your
  105.            most-used files are searched first (see Enqueue()).
  106.  
  107.          o memory allocation is fully implemented using V39 memory pool functions
  108.            (including the V37 library version)!
  109.  
  110.          o Dynamic AmigaGuide nodes for tables of:
  111.                - xref files
  112.                - all file references in an xref file
  113.                - all generic entries
  114.                - all function entries
  115.                - all device command entries
  116.                - all include file entries
  117.                - all macro entries
  118.                - all define entries
  119.                - all structure entries
  120.                - all typedef entries
  121.  
  122.          o categorization (with patterns) of XRef files gives you more flexibility.
  123.  
  124.          o binary search algorithm for normal strcmp()/strncmp()
  125.            parse modes (XRefConvert uses only these modes, therefore
  126.            being very fast! Better than AD2AG utility from Commodore.)
  127.  
  128.          o GoldED API-Client XRefAPI for completing phrases.
  129.            For example, "ow" would be completed to "OpenWindow(".
  130.  
  131.          o Workbench support for all tools (some using a small status window)
  132.            using FinalReadArgs() function (also included).
  133.  
  134.          o configuration directory can be specified with an environment
  135.            variable
  136.  
  137.          o dynamically loadable xreffiles (see Configuration-File).
  138.  
  139.          o rexxxref.library ARexx function FindXRef() to use the XRef-System
  140.            from ARexx
  141.  
  142.          If you missed a feature, please contact me (see Address).
  143.  
  144.  
  145.  
  146. The configuration file "xref.prefs"
  147.  
  148. This file should be placed in your "Sys:Config/XRef" directory.
  149. If you don't want to put it there, you can specify a directory with the
  150. XREFCONFIGDIR environment variable.
  151.  
  152. The file must be an ASCII text and is parsed line-oriented. Each line is
  153. interpreted to match one of the following templates (using ReadArgs()) :
  154.  
  155.     - AUTOOPEN/S/A,FILE/K/A,XREFPRI/N/K,LOCK/S,INDEX/S
  156.     - AUTOLOAD/S/A,FILE/K/A,XREFPRI/N/K,LOCK/S,INDEX/S
  157.     - MAINPAGE/S/A,LINELENGTH/N/K/A,COLUMNS/N/K/A
  158.     - CLEANUP/S/A,FORCE/S
  159.     - XREFDIR/S/A,DIR/A/K
  160.  
  161.     AUTOOPEN
  162.         This type of entry may exist several times in a prefs file.
  163.         It specifies an XRef file to be opened when parsing this
  164.         file. The specified arguments are passed to the XR_LoadXRef()
  165.         function. (see this document for further informations).
  166.  
  167.     AUTOLOAD
  168.         This entry specifies XRef files to be automatically loaded if an
  169.         entry wasn't found in the XRef files in memory.
  170.  
  171.     MAINPAGE
  172.         This entry specifies the line length and the column number which
  173.         will be used for all dynamic node layouts . Thus you can set
  174.         these values appropriate to your screen/window resolution.
  175.  
  176.     CLEANUP
  177.         If this line appears in a prefs file, all XRef files are flushed (removed)
  178.         from memory. If you specify the FORCE switch additionally, locked XRef
  179.         files are also flushed.
  180.  
  181.     XREFDIR
  182.         If you specify this line, the given path is used as the default path for
  183.         load XRef files.
  184.  
  185. Note: ReadArgs() doesn't support the "/S/A" combination, this is checked separately.
  186.  
  187.  
  188.  
  189. Installation
  190. ============
  191.  
  192. Simply run the Installer script in the Install directory. Make sure, that
  193. you have the Installer program in the Sys:Utilities directory, or on
  194. another place, where the workbench can find it.
  195.  
  196. Here is a short description, what and where this script installs on your
  197. system :
  198.  
  199. It copies the xref.library to your LIBS: directory according to your
  200. kickstart version a V37 or a V39 library.
  201.  
  202. The configuration files for the library and the tools are copied to
  203. Sys:config/xref or to a specified directory. I decided this default location
  204. instead of ENV: because these files aren't changed often, so I think it isn't worth
  205. wasting RAM! The following files are copied:
  206.  
  207.       keywords     - used by XRefConvert
  208.       keywords.v40 - used by XRefConvert
  209.       exceptions   - used by XRefConvert
  210.       xref.prefs   - used by xref.library during library startup
  211.  
  212. The script sets the xref.prefs file correctly for you. You can add any
  213. XRef file that should be loaded directly after the library init. Simply add a
  214. line like
  215.  
  216.     AUTOOPEN myxreffile.xref LOCK
  217.  
  218. or see section "The configuration file" for a more detailed descriptions of
  219. xref.prefs.
  220.  
  221. If you have installed the GoldEd Editor, the Installer script copies the
  222. xrefaguide.ged ARexx macro to the GoldEd:ARexx directory.
  223.  
  224. All other files are copied to the place you specify via the Installer.
  225.  
  226.  
  227.  
  228. The xref.library is the fundament of the XRef-System. It provides functions
  229. to load, expunge and parse XRef database files. The library can be configured
  230. using a file named xref.prefs. See section "The configuration file" or the
  231. LoadXRefPrefs() doc for further details.
  232.  
  233. In low memory situations, all libraries that aren't used currently
  234. are flushed. For this case, the xref.library has a locking mechanism for
  235. xref files. If you loaded an xref file with the LOCK switch turned on, this
  236. xref file isn't flushed, and the library neither. Thus you can decide if the
  237. xref.library should removed during a memory flush or not.
  238.  
  239. SEE ALSO
  240.     Library-Documentation
  241.     Library-History
  242.  
  243.  
  244.  
  245. AGuideXRefV37    parses the xref files searching for a given pattern/string and
  246.                  opens an AmigaGuide window using the amigaguide.library.
  247.                  If more than one entry matched, a temporary AmigaGuide database is
  248.                  created to allow you to select the desired entry
  249.  
  250. AGuideXRefV39    same as AGuideXRefV37, except that the window is opened using the
  251.                  amigaguide.datatype, providing you some new features according to
  252.                  the xref.library
  253.  
  254. ExpungeXRef      removes xref files from memory
  255.  
  256. LoadXRef         loads xref files into the memory
  257.  
  258. MakeAGuideIndex  generates an index file for given AmigaGuide files
  259.  
  260. MakeXRef         creates xref files from C includes, AutoDoc files, AmigaGuide files
  261.                  and unix manualpages files
  262.  
  263. ParseXRef        parses the xref files searching a given pattern/string and
  264.                  outputs to stdout
  265.  
  266. StatXRef         outputs the current settings of the xref.library
  267.  
  268. XRefAttrs        changes attributes of one or several xref file(s)
  269.  
  270. XRefConvert      converts AutoDoc or C Include files to AmigaGuide
  271.                  files
  272.  
  273. XRefAPI          This is not a tool but a GoldED API-Client for completing phrases
  274.                  like "of" to "OpenFont("
  275.  
  276.  
  277.  
  278. If you want to generate xref files for your own projects or to build all AutoDocs,
  279. you have to follow these steps:
  280.  
  281. 1. Generate an xref file from your C-Header or AutoDoc files.
  282.    The category option string is put into the generated file, therefore do not
  283.    specify the category explicitly ! (Note that if you set a global XRefPath,
  284.    you can only use the filenames as shown here!)
  285.  
  286.    Example: Generate two xref file for the directories include:myincludes and
  287.    docs:mydocs :
  288.  
  289.       MakeXRef FROM include:myincludes TO myinclude.xref \\
  290.                CATEGORY Include VERBOSE
  291.  
  292.       MakeXRef FROM docs:mydocs TO mydocs.xref CATEGORY AutoDoc \\
  293.                VERBOSE
  294.  
  295. 2. Load the generated files into memory:
  296.  
  297.       LoadXRef myinclude.xref mydocs.xref PRI 5
  298.  
  299. 3. Convert the include's and autodoc's to amigaguide databases:
  300.  
  301.       XRefConvert FROM include:myincludes TO AMIGAGUIDE:Includes VERBOSE
  302.  
  303.       XRefConvert FROM docs:mydocs TO AMIGAGUIDE:AutoDocs VERBOSE
  304.  
  305. 4. If everything went alright, the result is one or more AmigaGuide files in the
  306.    AMIGAGUIDE:Includes and/or AMIGAGUIDE:AutoDocs directories.
  307.  
  308.  
  309. Click here to perform these steps for the System Includes & Autodocs with the
  310. Installer, if you have the installer in your C: directory:
  311.  
  312.  
  313.  
  314. Work I'd like to do :
  315.  
  316. - a new gadgetclass for V39 and above, which integrates the amigaguide
  317.   datatype and a direct interface to the xref.library (this is currently the
  318.   AGuideXRefV39 program)
  319.  
  320. - a complete ARexx interface to the xref.library, at the moment only the
  321.   FindXRef(),LoadXRef() and ExpungeXRef() functions are available from ARexx
  322.   using the rexxxref.library
  323.  
  324. - perhaps a Preference editor
  325.  
  326. - localization of all tools (only the AGuideXRefV39 uses a catalog) (?)
  327.  
  328. - Maybe in future a new amigaguide class, which supports graphics and/or
  329.   other datatype formats. (But for this, I need a full documentation of the
  330.   amigaguide.datatype. With a system monitor, I found out that the amigaguide
  331.   datatype has 13 LVO function entry points. Where are the docs? Thanks to
  332.   Commodore for these not accessible docs... Arghhh!!!)
  333.  
  334. - More flexible MakeXRef and XRefConvert, that allows to add new scanners
  335.   for different languages.
  336.  
  337. - perhaps support of pipes for MakeXRef and XRefConvert
  338.  
  339.  
  340.  
  341. I'd like to thank some people for ideas and beta testing of the XRef-System :
  342.  
  343. Marius Gröger     - for his ideas, beta-testing, the small shared library
  344.                     init code and for correcting my english !
  345.  
  346. Alexander Barthel - for his patience of beta-testing my tools and for his
  347.                     GoldED ARexx-macros and PatchScreen tool.
  348.  
  349. Julian Scheid     - for his beta-testing and for correcting my english !
  350.  
  351. Manuel Nuñèz      - for his ideas.
  352.  
  353. And some other people :
  354.  
  355. Dietmar Eiltert   - for GoldED!
  356.  
  357. Markus Wild       - for his work in the unix area for the Amiga (GNU-C,
  358.                     ixemul.library and NetBSD)!
  359.  
  360. Micheal Sinz      - for the great Enforcer!
  361.  
  362. Fred Fish         - for his PD-Fish series!
  363.  
  364. Urban Mueller     - for his Aminet work !!!
  365.  
  366. And any other people, who helped to make the Amiga the only possibility!
  367.  
  368.  
  369.  
  370. If you have any comments, suggestions, bug reports or ideas please contact me :
  371.  
  372. Mail:
  373.  
  374. Stefan Ruppert
  375. Windthorststraße 5
  376. 65439 Flörsheim am Main
  377. GERMANY
  378.  
  379. EMail: rupperts3.informatik.fh-wiesbaden.de
  380.  
  381.  
  382.  
  383. Compilers used:
  384.  
  385. DICE-C      This isn't a tool but a great PD/SW C-Compiler I am using for
  386. V2.07.54    two years. Meanwhile I switched to SAS-C, but I look out for the
  387.             commercial version of DICE. I am still using the DMake make
  388.             utility for my projects.
  389.  
  390. SAS-C       The best C-Compiler for the Amiga. Think about the optimizer.
  391. V6.51       He reduces 2K from the xref.library .
  392.  
  393. GNU-C       I used this compiler for porting some unix tools and programs.
  394. V2.6.0      The Amiga port of the GNU-C/C++ compiler makes it easy to port
  395.             unix sources to the Amiga. Thanks to Markus Wild (ixemul.library)
  396.             for his work in this area, also to Fred Fish, Philippe Brand and
  397.             Lars Hecking for porting the latest version of GNU-C.
  398.  
  399. Software-Tools used:
  400.  
  401. Enforcer    A tool to detect illegal memory access. Great!
  402.  
  403. findhit,    Tools to find enforcer/mungwall hits in the source code. This
  404. findline    works only if you have turned line debugging on
  405.  
  406. DOSTrace    A Program that protocols dos.library function calls like Open()
  407.             Read(), Write(), Lock(), UnLock(), ...
  408.  
  409. makedoc     tool to extract documentation from source code or any other
  410.             Textfile. It's just like autodoc from Commodore DevCon disks,
  411.             but has a more flexible extraction and language support.
  412.  
  413. pragma_gen  tool to generate SAS-C pragma files. This program generates
  414.             also tagcall pragmas.
  415.  
  416.  
  417.  
  418. There are some rules you have to follow, if the XRef-System should work correctly
  419. with AmigaGuide:
  420.  
  421. Setup:
  422.  
  423.  - You must setup the ENV:AmigaGuide/Path file correctly. In this
  424.    file, you have to setup all directories with full pathnames,
  425.    where all your AmigaGuide databases reside (on one line, separated by spaces).
  426.  
  427. Problems :
  428.  
  429.  - For include files and all other files that have only a main node or links
  430.    with a line number, the ENV:AmigaGuide/Path directories doesn't work due to
  431.    a bug of AmigaGuide (I suppose). To fix this, generate xref entries for such
  432.    files with full pathnames like this:
  433.  
  434.        MakeXRef FROM include: TO include.xref CATEGORY Include PATH AG:SysInc
  435.  
  436.    In this release, I included the include-xref files with the "AG:SysInc"
  437.    global path for the system includes and "AG:OtherInc" global path for the
  438.    xref-includes. Note that this global path is only stored one time in a xreffile,
  439.    so it doesn't take up much disk or memory space; yet the full path is used in all
  440.    dynamic nodes and in generated AmigaGuide files. Therefore, make sure that the
  441.    specified path name is not too long.
  442.  
  443.  - The amigaguide.datatype and DOSTrace 2.12 don't work together:
  444.    If DOSTrace is running, the amigaguide.datatype cannot open any database.
  445.    I have no idea why this happens.
  446.  
  447.    You can test this with MultiView or any other program that uses this
  448.    datatype.
  449.  
  450.    These problems appeared in amigaguide.library V40.4 and amigaguide.datatype
  451.    V40.11 (my actual system version).
  452.  
  453. Compatibility:
  454.  
  455.  - the column support works only with V40 and above. I used new features
  456.    from the amigaguide.datatype V40 (settabs)!
  457.  
  458.  
  459.