home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Professional / OS2PRO194.ISO / os2 / prgramer / wf_expl / ndxform.doc < prev    next >
Text File  |  1992-05-02  |  10KB  |  470 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.                                                                NDX FILE FORMATS
  14.  
  15.                                                                         DRAFT 1
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.                                                                     May 2, 1992
  24.  
  25.  
  26.  
  27.  
  28.                                                                             LTC
  29.                                                              Toronto Laboratory
  30.                                                        VNET  - KEHM at TOROLAB6
  31.                                                  email - workframe@vnet.ibm.com
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.   CONTENTS
  74.   ________
  75.  
  76.  
  77.  
  78.  
  79.  
  80.  
  81.  
  82.  
  83.  
  84.  
  85.  
  86.  
  87.  
  88.  
  89.  
  90.  
  91.  
  92.  
  93.  
  94.  
  95.  
  96.  
  97.  
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.                                                                    Contents  ii
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.  
  140.   FIGURES
  141.   _______
  142.  
  143.  
  144.  
  145.  
  146.  
  147.  
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197.                                                                    Figures  iii
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205.  
  206.  
  207.   NDX FILES
  208.   _________
  209.  
  210.  
  211.  
  212.  
  213.  
  214.   INTRODUCTION
  215.   ____________
  216.  
  217.   The purpose of the NDX file is to provide a means where one product (such as
  218.   a compiler) can document its keywords and associate a command to be invoked
  219.   when a match is found for that keyword.  Another product (such as an editor)
  220.   can find a match in the keyword list for a given string and perform the asso-
  221.   ciated command on behalf of the first product. The most obvious use of this
  222.   format is for the invocation of help text. For example, the OS/2 Toolkit
  223.   could ship a file containing all the API calls, TOOLKT20.NDX. A particular
  224.   API, could be documented such that when another product found a match for
  225.   that API it would know to invoke the VIEW utility for the topic.  If someone
  226.   requested help for DosOpen, the file would state that the command "VIEW
  227.   GUIREF20.INF DosOpen" should be issued.
  228.  
  229.  
  230.   FORMAT
  231.   ______
  232.  
  233.   An NDX file is comprised of at least three lines.  Each line must be less
  234.   than 254 characters long (followed by CRLF).
  235.  
  236.   1.  The FIRST line contains the keyword "EXTENSIONS:" followed by a list of
  237.       extensions (case insensitive) by which the interpreting product can iden-
  238.       tify the types of files for which these keywords are applicable.  The
  239.       extensions are 1 to 3 characters and entries are blank delimited.
  240.  
  241.       The character asterisk (*) is reserved to mean any file type is valid.
  242.       For example,
  243.  
  244.  
  245.         EXTENSIONS: C I SQC H
  246.  
  247.  
  248.       This would specifically be used to resolve ambiguities when multiple NDX
  249.       files are processed. For example the KEYWORD "if" would be valid for
  250.       REXX, C, or PASCAL. The tool processing the file would know which NDX
  251.       file to use based on matching the file's extension with the first NDX
  252.       file that supports that extension.
  253.  
  254.   2.  The second line contains the keyword DESCRIPTION: followed by text that
  255.       describes the product being supported. For example,
  256.  
  257.  
  258.         DESCRIPTION: IBM CSET/2 Language keywords
  259.  
  260.  
  261.       This information could be used in may ways. For example, if there were
  262.       two NDX files in affect for the same file extension, the supporting tool
  263.  
  264.  
  265.  
  266.                                                                    NDX Files  1
  267.  
  268.  
  269.  
  270.  
  271.  
  272.  
  273.  
  274.  
  275.  
  276.       could display a list of possible NDX files and ask the user to select one
  277.       (similar to the way ASSOCIATE works).
  278.  
  279.   3.  Lines 3 through N contain
  280.        one or more entries.  Each entry is of the form:
  281.  
  282.  
  283.           (keyword,command)
  284.  
  285.  
  286.       Where:
  287.  
  288.       RIGHT PARENTHESIS a delimiter to indicate the beginning of an entry,
  289.  
  290.       LEFT PARENTHESIS a delimiter to indicate the end of an entry,
  291.  
  292.       KEYWORD        a string on which a case sensitive match should be made.
  293.                      The keyword should NOT contain a left or right parenthesis
  294.                      and may contain a trailing asterisk.  The asterisk indi-
  295.                      cates that a match can be made if the string being
  296.                      searched for matches all the characters prior to the
  297.                      asterisk (see examples 1 and 7).  If an * is one of the
  298.                      characters in the keyword use a second asterisk (**) as
  299.                      the escape character. If two asterisks are required then 4
  300.                      asterisks must be entered (see examples 4 and 6).
  301.  
  302.                      If more than one instance of the same keyword is found
  303.                      then it is implementation-defined as to which one is used.
  304.  
  305.       COMMAND        any valid command supported by the Operating System.  The
  306.                      command may support any number of tildes (&tilde.) to
  307.                      indicate where in the invocation string the keyword for
  308.                      which a match is found is to be placed (see example 3).
  309.  
  310.       COMMENTS       Any characters not contained within parenthesis
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.                                                                    NDX Files  2
  333.  
  334.  
  335.  
  336.  
  337.  
  338.  
  339.  
  340.  
  341.  
  342.   EXAMPLE
  343.   _______
  344.  
  345.           SAMPLE.NDX
  346.  
  347.  
  348.             EXTENSIONS: SCR DOC TXT
  349.             DESCRIPTION: Product XXX's Keywords
  350.             (Ralph, VIEW mynames.inf RALPH) (Ral*, VIEW mynames.inf &tilde.)
  351.             (**, View mycomp.inf multiply)  (****, VIEW mycomp.inf exponentiation)
  352.             (*, View mynames.inf &tilde.)
  353.  
  354.  
  355.   The entries are explained as follows:
  356.  
  357.   1.  The search string must match the keyword "Ralph" exactly and if it does
  358.       invoke the command interpreter with "view mycomp.inf RALPH)
  359.  
  360.   2.  Any string beginning with "Ral" followed by zero or more characters
  361.       matches the keyword. Use the command VIEW mynames.inf <string> where is
  362.       the string for which a match was found.
  363.  
  364.   3.  Since * is the escape character the keyword <string> is really the single
  365.       character "*". If the string being used is also a single asterisk then
  366.       issue the command "View mycomp.inf multiply".
  367.  
  368.   4.  Two escape characters are used to indicate the keyword "**". If the
  369.       string matches the keyword exactly then issue the command "View
  370.       mycomp.inf exponentiation".
  371.  
  372.   5.  All other strings should cause the command "View mynames.inf <string>" to
  373.       be issued. <string> is the string for which the match was found.
  374.  
  375.   Examples:
  376.  
  377.   Consider the following text and assume that the user presses a predefined
  378.   help key for each word from left to right.
  379.  
  380.  
  381.         Ralphie = 3 ** 4 *  Ralph
  382.  
  383.  
  384.   1.  "Ralphie" will match the second entry since it does not match the first
  385.       entry exactly. "VIEW mynames.inf Ralphie" will be issued.
  386.  
  387.   2.  "=" will not match any specific entry so the catchall entry 5 will be
  388.       used and "VIEW mynames.inf =" will be issued.
  389.  
  390.   3.  "3" will not match any specific entry so the catchall entry 5 will be
  391.       used and "VIEW mynames.inf 3" will be issued.
  392.  
  393.   4.  "**" will match entry 4 and "VIEW mycomp.inf exponentiation" will be
  394.       issued.
  395.  
  396.  
  397.  
  398.  
  399.                                                                    NDX Files  3
  400.  
  401.  
  402.  
  403.  
  404.  
  405.  
  406.  
  407.  
  408.  
  409.   5.  "4" will not match any specific entry so the catchall entry 5 will be
  410.       used and "VIEW mynames.inf 4" will be issued.
  411.  
  412.   6.  "*" will match entry 3 and "VIEW mycomp.inf multiply" will be issued.
  413.  
  414.   7.  "Ralph" will match entry 1 exactly and "VIEW mynames.inf RALPH" will be
  415.       issued.
  416.  
  417.  
  418.   RECOMMENDATIONS:
  419.   ________________
  420.  
  421.   1.  NDX files should be searched for along the DPATH
  422.  
  423.   2.  One or more NDX files can be specified through the use of an environment
  424.       variable called HELPNDX.
  425.  
  426.       SET HELPNDX=DDE4.NDX+TOOLKT20.NDX
  427.  
  428.   3.  Each product may develop its own scheme for keyword conflict resolution
  429.       (extended attributes, INI files etc) but the EXTENSIONS and DESCRIPTION
  430.       lines will be present in each NDX file and should be used wherever pos-
  431.       sible.
  432.  
  433.   4.  An * entry should be avoided since when NDX files are combined the
  434.       affects of multiple * entries is unpredictable.
  435.  
  436.  
  437.   TOOLKT20 EXAMPLE:
  438.   _________________
  439.  
  440.   The following would probably be sufficient for the OS/2 2.0 toolkit.
  441.  
  442.     EXTENSIONS: *
  443.     DESCRIPTION: OS/2 2.0 Programming Interfaces
  444.     (Win*, VIEW PMWIN.INF &tilde.)                   (MM_*, VIEW PMMSG.INF &tilde.)
  445.     (Spl*, VIEW PMWIN.INF &tilde.)                   (LM_*, VIEW PMMSG.INF &tilde.)
  446.     (Prf*, VIEW PMWIN.INF &tilde.)                   (HM_*, VIEW PMMSG.INF &tilde.)
  447.     (Gpi*, VIEW PMGPI.INF &tilde.)                   (FNTM_*, VIEW PMMSG.INF &tilde.)
  448.     (WM_*, VIEW PMMSG.INF &tilde.)                   (FDM_*, VIEW PMMSG.INF &tilde.)
  449.     (PL_*, VIEW PMMSG.INF &tilde.)                   (EM_*, VIEW PMMSG.INF &tilde.)
  450.     (TBM_*, VIEW PMMSG.INF &tilde.)                  (DM_*, VIEW PMMSG.INF &tilde.)
  451.     (SM_*, VIEW PMMSG.INF &tilde.)                   (CBM_*, VIEW PMMSG.INF &tilde.)
  452.     (SPBM_*, VIEW PMMSG.INF &tilde.)                 (BM_*, VIEW PMMSG.INF &tilde.)
  453.     (SBM_*, VIEW PMMSG.INF &tilde.)                  (Dos*, VIEW GUIREF20.INF &tilde.)
  454.     (MLM_*, VIEW PMMSG.INF &tilde.)                  (Drg*, VIEW PMFUN.INF &tilde.)
  455.     (Dev*, VIEW PMFUN.INF &tilde.)
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.                                                                    NDX Files  4
  468.  
  469.  
  470.