home *** CD-ROM | disk | FTP | other *** search
/ BCI NET 2 / BCI NET 2.iso / archives / programming / misc / xref_v1.1.lha / XRef / Doc / english / xrefconvert.doc < prev   
Encoding:
Text File  |  1995-01-09  |  9.7 KB  |  222 lines
  1. XRef-Tools/XRefConvert                                   XRef-Tools/XRefConvert
  2.  
  3. $VER: xrefconvert.doc 1.14 (03.11.94)
  4.  
  5. NAME
  6.     XRefConvert - converts autodoc or header files to AmigaGuide files
  7.  
  8. TEMPLATE
  9.     FORM/M/A,TO/A,KEYWORDFILE/K,EXCEPTIONFILE/K,STDDELIMITERS/K,
  10.     EXCLUDETYPES/K,INCLUDETYPES/K,INDENT/N/K,TOOLPRI/N/K,NOICON/S,
  11.     NOAMIGAGUIDE/S,NOMAINPAGELINK/S,STATISTIC/S,V40/S,VERBOSE/S
  12.  
  13. FORMAT
  14.     XRefConvert [FROM] file|dir [file2|dir2] [TO] dir [CATEGORY categories]
  15.                 [KEYWORDFILE keyworddef] [EXCEPTIONFILE exceptdef] 
  16.                 [STDDELIMITERS string] [EXCLUDETYPES types]
  17.                 [INCLUDETYPES types] [INDENT number] [TOOLPRI priority]
  18.                 [NOICON] [NOAMIGAGUIDE] [NOMAINPAGELINK] [STATISTIC] [V40]
  19.                 [VERBOSE]
  20.  
  21. FUNCTION
  22.     Files:
  23.     converts a C header file or a autodoc file in a AmigaGuide file.Which type
  24.     a given file is, is determined by the suffix of the filename :
  25.        - ".h" for a C header file
  26.        - ".doc" or ".dok" for a doc file and
  27.        - these suffix with the "TABLE OF CONTENTS" for an autodoc file
  28.     If the switch NOAMIGAGUIDE is on, XRefConvert will generate the appropri-
  29.     ate files with out the headers for an AmigaGuide file.If this is not
  30.     turned on,it generates an AmigaGuide file. Thus you can use the keyword
  31.     format feature also to convert to AmigaGuide or to convert in normal ASCII
  32.     format.
  33.  
  34.     Delimiters:
  35.     This tool separates words by using of a delimiter-string. The default
  36.     string is " \t\n,<>=(){}\":.;*|!". Any of these charaters terminates a
  37.     word. You can specify an other delimiter string by using of the
  38.     STDDELIMITERS option for the command.
  39.  
  40.     Keyword file:
  41.     To specify keywords you must pass a keyword file, which contains keyword
  42.     definitions (see KEYWORDFILE option).XRefConvert loads first the
  43.     "Sys:config/xref/keywords" file is it exists.After this it loads the
  44.     specified keywordfile or it looks for a "keywords" file in the current
  45.     directory.
  46.  
  47.     Icon:
  48.     XRefConvert will use the ENV:sys/def_guide.info icon for each generated
  49.     AmigaGuide database. If this icon doesn't exists it uses a internal icon.
  50.  
  51. INPUTS
  52.     FROM (STRINGS) - specifies input files and/or directories
  53.  
  54.     TO (STRING) - specifies the output directory, in which the generated
  55.         direcotries/files are placed.
  56.  
  57.     CATEGORY (STRING) - category pattern to use for convertion. Only
  58.         xreffiles are parsed, which matches this category pattern.
  59.  
  60.     KEYWORDFILE (STRING) - file, which contains keyword definitions to substi-
  61.         tute such keywords.
  62.         The file must have the following format :
  63.         - First the file format is ASCII-text, which is line orientated.
  64.           Each line is parsed via ReadArgs() function of the dos.library with
  65.           the following template :
  66.           
  67.           KEYWORD/K/A,SUBSTITUTE/K/A,DELIMITERS/K,NEXTWORD/S
  68.  
  69.           if a line matches these template it will be stored and used by the
  70.           convertion.
  71.  
  72.           the format of line is (note in the file, it must be one line !!!) :
  73.  
  74.           KEYWORD keyword SUBSTITUTE substitute-string [DELIMITERS string] \
  75.           [NEXTWORD]
  76.  
  77.           KEYWORD (STRING) - specifies the word to search for, if this is
  78.               AUTODOC, the substitute string is used to substitute all words,
  79.               which matches a AutoDoc description word (f.e. : "NAME",
  80.               "SYNOPSIS",...). To detect such words it must match the
  81.               following : first in the line there can be 
  82.                           INDENT - 2 < n < INDENT + 2
  83.               n spaces, then the word must follow in uppercase letters and 
  84.               after this must be a newline !
  85.           SUBSTITUTE (STRING) - specifies the string to replace the keyword
  86.               in the generated file a "%s" in this string inserts the keyword
  87.               itself (just one time for now).
  88.           DELIMITERS (STRING) - specifies the delimiters for the next word.
  89.               This string is only valid if the NEXTWORD switch is turned on.
  90.           NEXTWORD (BOOLEAN) - indicates, that the next word should replaced,
  91.               instead of the keyword. If you also specify the DELIMITERS, the
  92.               end of the next word is defined by any character in this string.
  93.  
  94.           For the V40 option there exists a special keywordfile named
  95.           keywords.v40 in the config directory. In this file you can specify,
  96.           which text passages are wrapped and which not, using the new
  97.           smartwrap function. If you want a text passage be wrapped define a
  98.           KEYWORD with the description title like "FUNCTION" and use the
  99.           "@{mtext %s}" macro as the SUBSTITUTE string. Thus this text passage
  100.           should be smartwrapped (See also the default keywords.v40 file) !
  101.  
  102.     EXCEPTIONFILE (STRING) - file, which contain names that are only linked,
  103.         if a "()" is at the end of the name, see AD2AG. Each line has only one
  104.         name.The default is $XREFCONFIGDIR/exceptions .
  105.  
  106.     STDDELIMITERS (STRING) - string, which defines the delimiters characters
  107.         the default is : " \t\n,<>=(){}\":.;*|!"
  108.  
  109.     EXCLUDETYPES (STRING) - string, which defines the entrytypes that aren't
  110.         used during convertion. With this option you can subpress links to
  111.         the specified types. Each type in this string is separated by an '|'
  112.         character. For example you don't want links to typedef's and macro's.
  113.         Then you have to specify this : EXCLUDETYPES "typedef|macro" !
  114.         Types available for this option : "generic", "function", "command",
  115.         "include", "macro", "struct", "field", "typedef", "define" !
  116.         Default is "".
  117.  
  118.     INCLUDETYPES (STRING) - string , which defines the entrytypes that are
  119.         only used during convertion. See EXCLUDETYPES for string format and
  120.         available types.
  121.  
  122.     INDENT (NUMBER) - number of spaces, which are inserted before an AutoDoc
  123.         description word (see KEYWORDFILE/KEYWORD above).
  124.  
  125.     PRI (NUMBER) - task priority to use during converting
  126.  
  127.     NOAMIGAGUIDE (BOOLEAN) - indicates, that shouldn't create AmigaGuide 
  128.         headers for each file
  129.  
  130.     NOICON (BOOLEAN) - don't save an icon for the generated amigaguide file
  131.  
  132.     NOMAINPAGELINK (BOOLEAN) - don't generate a TABLE OF CONTENTS link to the
  133.         xref.library dynamic node main page.
  134.  
  135.     STATISTIC (BOOLEAN) - outputs statistics about the generated links to each
  136.         type of entries. Such as include's or functions.
  137.  
  138.     V40 (BOOLEAN) - generate amigaguide files for use with amigaguide.datatype
  139.         V40 or higher. This generates databases, which uses the smartwrap
  140.         option of the V40 version. This option works only with files in the
  141.         autodoc format and perhaps not with all files of this fileformat. So
  142.         convert and take a look at the generated files !
  143.         If this option is specified XRefConvert tries to load also the file
  144.         "Sys:config/xref/keywords.v40" , in which the keywords are defined to
  145.         use smartwrap !
  146.  
  147.     VERBOSE (BOOLEAN) - output informations of the current convertion state
  148.  
  149. EXAMPLE
  150.     XRefConvert include:amiga/ aguide:include/ KEYWORDFILE s:mykeywords \
  151.                 AMIGAGUIDE VERBOSE
  152.  
  153. SEE ALSO
  154.     MakeXRef, LoadXRef, ParseXRef, AGuideXRefV37, AGuideXRefV39, StatXRef,
  155.     XRefAttrs, MakeAGuideIndex
  156.  
  157. COPYRIGHT
  158.     (C) by Stefan Ruppert 1994
  159.  
  160. HISTORY
  161.     XRefConvert 1.14 (3.11.94) :
  162.        - default icon name now correct "Env:Sys/def_guide"
  163.        - time calculation now correct
  164.  
  165.     XRefConvert 1.13 (11.9.94) :
  166.        - workbench support added
  167.        - status window, if started from workbench added
  168.  
  169.     XRefConvert 1.12 (3.9.94) :
  170.         - now gets the nodename from the entry with ENTRYA_NodeName
  171.  
  172.     XRefConvert 1.11 (31.8.94) :
  173.         - added V40 option
  174.  
  175.     XRefConvert 1.10 (29.8.94) :
  176.         - unix manpage support added
  177.  
  178.     XRefConvert 1.9 (27.8.94) :
  179.         - main node title shows now the relative path instead of the first
  180.           path part
  181.         - uses now XREFA_CategoryParsed if a category is specified. This
  182.           speeds up the convertion.
  183.         - for AutoDoc TOC uses now the columns from the xref.library
  184.  
  185.     XRefConvert 1.8 (23.7.94) :
  186.         - added EXCLUDETYPPES,INCLUDETYPES option
  187.  
  188.     XRefConvert 1.7 (22.7.94) :
  189.         - some bug fixed.
  190.         - now can handle <entry>/<entry> pairs
  191.         - the InternXRef list wasn't free'd after convertion of a file
  192.           (this slowed down the convertion of more than one file per call).
  193.           This is fixed and some optimizations by stepping through the list.
  194.         - New statistic display
  195.         - PRI option added
  196.  
  197.     XRefConvert 1.6 (17.7.94) :
  198.         - now it supports amigaguide files to convert ! It tries to link all
  199.           internal @node titles in the text to the node. And links all found
  200.           xref entries.
  201.         - the point is now a special delimiter ! The following sequences are
  202.           now interpreted as a delimiter ". ",".\0",".\t",".\n" !
  203.         - category pattern added
  204.  
  205.     XRefConvert 1.5 (13.7.94) :
  206.         - now tries to set the index array for each xreffile to get the best
  207.           performance (then it uses a binary search algorithm)
  208.  
  209.     XRefConvert 1.4 (11.6.94) :
  210.         - ':','-',';','*' added to STDDELIMITERS default string
  211.         - now tries to load "Sys:config/xref/keywords" every time and then
  212.           tries to load the specified keyword file. If no one is specified
  213.           tries to load the "keywords" file in the current directory.
  214.         - save icon bug fixed , if the source file had an unknown type the
  215.           icon was saved even though. This is fixed.
  216.         - All structures , which have equal autodoc beginnings like , Window
  217.           struct "Window" * -> "Window"ToFront() aren't linked. This is fixed!
  218.  
  219.     XRefConvert 1.3 (29.5.94) :
  220.         - INDENT option added
  221.  
  222.