home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / srev13g.zip / BYBROWSR.DOC < prev    next >
Text File  |  1999-04-09  |  15KB  |  389 lines
  1. 15 Apr 1998: ByBROWSR.RXX :  Using Browser Specific Documents.
  2.  
  3. Abstract:
  4.   ByBROWSR.RXX is an "INTERPRETable" SRE-http addon that simplifies the
  5.   deliver of "browser specific" documents to your WWW clients.
  6.  
  7. Contents:
  8.  
  9. 1.0 Introduction
  10. 2.0  Using ByBROWSR.RXX
  11. 2.1 A Simple Example
  12. 2.2 More Options
  13. 3.0 Configuring ByBROWSR.RXX
  14. 3.1 User-Configurable Parameters in ByBROWSR.RXX
  15. 4.0 A simple, working example
  16.  
  17.                         --------    ----   ---------
  18.  
  19. 1.0) Introduction
  20.  
  21. ByBROWSR.RXX is an "INTERPRETable" SRE-http addon that simplifies the
  22. delivery of "browser specific" documents to your WWW clients.  Although
  23. it requires a bit of initial setup, once you have ByBROWSR.RXX
  24. customized to your needs, it's quite easy to use.  Of course, you 
  25. still are responsible for content-creation -- but with ByBROWSR.RXX,
  26. that's about all you need to be concerned with.
  27.  
  28.                         --------    ----   ---------
  29.  
  30. 2.0) Using ByBROWSR.RXX
  31.  
  32. To use ByBROWSR.RXX, you just need to include
  33.  
  34.     <!-- INTERPRET FILE ByBROWSR.RXX -->
  35.  
  36. "SSI keyphrases" in a "base document". When this "base document is
  37. requested by a client,  SRE-http will call (actually, SRE-http will 
  38. read and "interpret") ByBROWSR.RXX. ByBROWSR.RXX will lookup the
  39. client's browser (using the "user-agent" request header), and then try and
  40. find a "browser specific" version of the "base document".
  41.  
  42. Browser specific versions are files that have the same name as the base 
  43. document, but have extensions that indicate which browser the 
  44. file is meant for. You can, and should, make several such documents 
  45. for the various types of browsers likely to visit your site; and you 
  46. should also make a default document for use when some unusual (or new) 
  47. browser comes a calling.
  48.  
  49. The trick is to know what extensions to use. This is explained in greater 
  50. detail in the Configuring ByBROWSR.RXX section. 
  51.  
  52. But first, how about a simple example?
  53.  
  54.                         --------    ----   ---------
  55.  
  56. 2.1) A Simple Example
  57.  
  58. Let's assume the following URL on your home page:
  59.     <A href="/MOREINFO.HTML">More info? </a>
  60. Let's also assume that /MOREINFO.HTML points to D:\WWW\MOREINFO.HTML.
  61.  
  62. D:\WWW\MOREINFO.HTML can consist of just the following line.
  63.  
  64.     <!-- INTERPRET FILE ByBROWSR.RXX -->
  65.  
  66. (that's right: no <HTML>, no <BODY> -- just one line of text.)
  67.  
  68. Now the hard part -- creation of several "browser-specific files".  Each of
  69. these files will be named D:\WWW\MOREINFO.an_ext; where an_ext is a
  70. a special "browser-specfic" extension. These an_ext animals are setup
  71. in ByBROWSR.RXX (again, we'll get to that in the configuration section).
  72. For now, let's assume you care about 4 major "classes" of browsers. The
  73. an_ext for these should be....
  74.    NetScape 2.x   :   an_ext = NETSCAPE2
  75.    NetScape 3.x   :   an_ext = NETSCAPE3
  76.    MSIE 3.x       :   an_ext = MSIE3
  77.    all others     :   an_ext=  DEF
  78.      (for sake of simplicity, let's ignore NetScape 4, MSIE 4 ,etc.)
  79.  
  80. Thus, you should also create the following files, each of which will contain
  81. "browser specific" HTML code.  For this simple example,  each of these 
  82. "browser specific" files should be a fully contained HTML document
  83. (i.e; one that starts with <HTML>  or <!DOCTYPE>, and ends with </HTML>).
  84.  
  85.   D:\WWW\MOREINFO.NETSCAPE2   (used with Netscape 2.x browsers),
  86.   D:\WWW\MOREINFO.NETSCAPE3   (used with Netscape 3.x browsers),
  87.   D:\WWW\MOREINFO.MSIE3       (used with MSIE 3.x browsers),
  88.   D:\WWW\MOREINFO.DEF         (used with all otherbrowsers),
  89.  
  90. That's it!  When a client asks for /MOREINFO.HTM; one of the above 4
  91. files will be returned.  
  92.  
  93. A FAT Note:
  94.   If you are using a FAT system:, some extra configuration is needed in
  95.   order to use ByBROWSR.RXX, and your "extensions" can only be three
  96.   characters long,  but otherwise there is no difference.
  97.  
  98.                         --------    ----   ---------
  99.  
  100. 2.2) More options:
  101.  
  102. ByBROWSR.RXX is actually a "browser specfic #INCLUDE".  Specifically,
  103. SRE-http will convert a "SSI keyphrase" of
  104.         <!-- INTERPRET FILE ByBROWSR.RXX --> 
  105. into
  106.        <!-- #include file=filename.an_ext -->
  107. where filename is the  name (minus extension) of the requested document
  108. (i.e.; MOREINFO), and an_ext is determined from the User-Agent request
  109. header and the "file matching rules" specified in ByBROWSR.RXX.
  110.  
  111. Thus,  the "browser specfic files" need NOT be an entire HTML document -- 
  112. they can just be a component of an otherwise "all-browser" document. 
  113.  
  114. That is:  
  115.    you can use <!-- INTERPRET FILE ByBROWSR.RXX --> in pretty
  116.    much the same way you use a <!-- #include file=xxx --> statement.
  117.  
  118.    For example, MOREINFO.HTM could be a regular HTML document, with 
  119.    <!-- INTERPRET FILE ByBROWSR.RXX --> used to specify a <TABLE>
  120.    that uses browser specific <TABLE> extensions. 
  121.  
  122. The astute reader might ask: what if I want to have several such 
  123. "browser-specific components"? And the answer is ---- Yes, it's easy
  124. to do. All you need to do is place the "selector" for this 
  125. "base document" after the ByBROWSR.RXX, as in: 
  126.      <!-- Interpret file ByBrowsr.RXX  webdir/other_filename -->
  127.  
  128. For example:
  129.    Suppose you have a BBars directory that contain sets browser-specific
  130.    button-bars (such as NAVIGATE.NETSCAPE2, NAVIGATE.DEF, and 
  131.    NAVIGATE.MSIE4)
  132.  
  133.    To include the appropriate button bar, use the following:
  134.        <!-- Interpret file ByBrowsr.RXX  BBARS/NAVIGAT -->
  135.  
  136. Notes:
  137.   * the "selector" (i.e.; BBARS/NAVIGAT) will be interpreted using the
  138.     regular SRE-http rules -- it should either be under the GoServe default
  139.     data  directory or should point to a virtual directory (either of which
  140.      may be host-specific)
  141.   * you needn't bother putting an extension after NAVIGAT -- it will
  142.     be stripped off. 
  143.  
  144.                         --------    ----   ---------
  145.  
  146. 3.0) Configuration
  147.  
  148. The heart of ByBROWSR.RXX is a set of "file-matching" rules. These rules
  149. are used to match an "user-agent" request header to a "file extension".
  150.  
  151. Note: ByBROWSR.RXX is installed into your SRE-http "addons" directory
  152. (perhaps D:\GOSERVE\ADDON).
  153.  
  154. There are three levels of rules:
  155.   1) Primary Rules. Each primary rule consists of a candidate user-agent
  156.      string, and the extension it maps to.
  157.      ByBROWSR.RXX will find the primary rule that "best" matches the
  158.      user-agent.
  159.   2) Secondary Rules. If the primary rule fails (either because there is
  160.      no match, or a file with the matching extension does not exist), a set
  161.      of secondary rules are examined. These are similar to primary rules; with
  162.      the notion being you will use more "generic" names. In addition, ALL
  163.      matching secondary rules are attempted starting with the "best" match
  164.      and continuing until a matching file name exists (or until there are
  165.      no more matching secondary rules).
  166.    
  167.   3) Default rule. If the primary and secondary rules do not yield a match, 
  168.      a default extension is used. As shipped, the default extension is
  169.      DEF -- but you can change that.
  170.  
  171. This "best" matching is based on the following algorithim:
  172.   1) All spaces are removed from the user-agent, and from each of the
  173.      primary (and secondary) rules. 
  174.   2) A case-insensitive "wild card" match is attempted -- with * in the 
  175.     "rules" treated as a wildcard characters. You can have multiple *s 
  176.      in each rule (* in the user-agent are treated as normal characters).
  177.   3) If there are multiple "wild card" matches, the "best" match is used
  178.      (for seconday rules, the "best" matches are "used first").  Best
  179.      match is a function of how many characters in the "user-agent" also
  180.      appear in the rule -- the more "early occurences", the better the
  181.      match.
  182.       For example:
  183.        if 
  184.           the user-agent=MOZILLA/2.0(emulator),
  185.        and two candidate rules are:
  186.           i) Mozilla*2
  187.          ii) Moz*2.0*(
  188.       then both match, but i is better (since "Mozilla" is longer then "Moz".
  189.  
  190.      Note that * can "wildcard match" a 0-length string (that's why ii
  191.      is a valid match).
  192.  
  193. ByBROWSR.RXX is shipped with about 50 primary rules that map unique 
  194. "user-agents" to unique extensions, and several secondary rules that
  195. deal with the most popular "families" of browsers. The following lists 
  196. several of these "shipped with" primary rules, and the extensions they map to.
  197.  
  198.     Extension        Primary Matching Rule
  199.     -------         ----------------------------------------
  200.    WEBEX11           IBMWebExplorerDLL/v1.1* 
  201.    WEBEX12           IBMWebExplorerDLL/v1.2* 
  202.      MSIE3           Mozilla/2.0*(compatible*MSIE3.* 
  203.      MSIE2           Mozilla/*compatible*MSIE2.* 
  204.      MSIE4           MicrosoftInternetExplorer/4.*
  205.  NETSCAPE4           Mozilla/4.* 
  206.  NETSCAPE3           Mozilla/3.* 
  207.  NETSCAPE2           Mozilla/2.* 
  208.  NETSCAPE1           Mozilla/1.* 
  209.   MOSAIC27           NCSA_Mosaic/2.7* 
  210.  
  211. Reminder: when the user-agent is compared to a matching rule -- all
  212.           spaces are removed, case is ignored, and * is a wildcard.
  213.           Furthermore, the "best" match is used. Hence, a user-agent of
  214.                Mozilla/2.0*(compatible*MSIE 3.*Windows 3.1*)*                  
  215.           would yield MSIE3.
  216.          
  217. Since it is quite likely that you will NOT have all these zillions of
  218. browser specific files; in most cases a matching primary rule WILL be 
  219. found, but the corresponding file will NOT exist.  In such cases,
  220. the secondary rules are examined. ByBROWSR.RXX is shipeed with the
  221. following secondary rules:
  222.  
  223.     Extension        Secondary Matching Rule
  224.     -------         ----------------------------------------
  225.      NETSCAPE2         Mozilla/2.*  
  226.      NETSCAPE2         Mozilla/3.*
  227.      NETSCAPE2         Mozilla/4.*
  228.         MOSAIC         MOSAIC
  229.            NET          Mozilla*  
  230.  
  231. Example (assuming the "base document" name is xxxx):
  232.     If the user-agent matches the Mozilla/3.* "primary rule", but
  233.      a xxxx.NETSCAPE3 file does not exist: 
  234.         i) A xxxx.NETSCAPE2 file will be tried. 
  235.     If this fails:
  236.        ii) A xxxx.NET file will be tried  
  237.     And if this also fails,
  238.       iii) A xxxx.DEF file will be used
  239.  
  240.  
  241.  
  242. If you want to modify these rules (and it's probably a wise idea to at
  243. least consider modifying the secondary rules), you'll need to edit
  244. the following varibles in ByBROWSR.RXX:  
  245.  
  246.    BROWSER.!    -- Primary Rules 
  247.    BROWSER_2.!  -- Secondary rules.
  248.    DEFAULT      -- Default
  249.  
  250. ByBROWSR.RXX contains a description of the syntax of these variables.
  251. Or, you can read the "User-configurable Variables" section that coming
  252. upt next.
  253.  
  254.                         --------    ----   ---------
  255.  
  256. 3.1) User-Configurable Variables in ByBROWSR.RXX
  257.  
  258. This section contains information on the structure of the various
  259. "user-configurable" variables.  
  260.  
  261. DEFAULT -- The default extension.
  262.    DEFAULT should equal the extension to use if there is no match, or
  263.    if  matching rules point  to a non-existent file.
  264.  
  265.    Example: DEFAULT='DEF'
  266.  
  267. BROWSERS.! -- Primary Rules
  268.    A list of User Agents and associated extensions.
  269.    The BROWSER.! variables should have the following syntax:
  270.        BROWSER.!an_ext='u_agent'
  271.    where
  272.        an_ext is the extension to use 
  273.        u_agent is compared against user-agent request headers
  274.    Example: BROWSER.!NETSCAPE3='Mozilla/3.*'
  275.  
  276.  Notes:
  277.   *  Be sure to include the .! before the an_extension (it's a REXX
  278.      "stem variable" subtlety). PLEASE NOTE THAT THE ! IS NOT USED IN THE EXTENSION.                
  279.   *  Be sure to surround the u_agent with ' quotes
  280.   *  Spaces in the user_agent are ignored, case is ignored,
  281.      and * are treated as wild-card characters.
  282.   *  The "best" match (of the u_agent field against a requesting browser's
  283.      user-agent request header) is used
  284.   *  If you are using a FAT (3 character extension) system, you'll need to
  285.      modify the an_ext "tails" of all the BROWSER.! and BROWSER_2.! rules.
  286.   *  To specify U_agents mapping to the same an_ext, use syntax e 
  287.  Examples:
  288.  
  289.    BROWSER.!WEBTV='Mozilla/1.*WebTV/1.*compatible*MSIE2.*' 
  290.    BROWSER.!EINETMACWEB='MacWeb/1.00*libwww/2*' 
  291.    BROWSER.!WEBEX12='IBMWebExplorerDLL/v1.2*' 
  292.    BROWSER.!WEBEX11='IBMWebExplorerDLL/v1.1*' 
  293.    BROWSER.!MCI='internetMCI/1.0(Windows)*' 
  294.    BROWSER.!MSIE3='Mozilla/2.0*(compatible*MSIE3.*' 
  295.    BROWSER.!MSIE4='MicrosoftInternetExplorer/4.*' 
  296.    BROWSER.!NETSCAPE4='Mozilla/4.*' 
  297.    BROWSER.!NETSCAPE3='Mozilla/3.*' 
  298.  
  299.  
  300. BROWSER_2.! -- Secondary Rules.
  301.   The BROWSER_2.! variables are used when a matching BROWSER.! "primary rule"
  302.   can not be found. It uses the same syntax as BROWSER.!.
  303.   Notes:
  304.     *  We advice using very generic (short, with early use of *) u_agents!
  305.     *  You can use u_agents specified in BROWSER.! rules.
  306.  
  307. Examples:
  308.  
  309.   BROWSER_2.!MOSAIC='*MOSAIC'
  310.   BROWSER_2.!NETSCAPE2.1='Mozilla/2.*' 
  311.   BROWSER_2.!NETSCAPE2.2='Mozilla/3.*'
  312.   BROWSER_2.!NETSCAPE2.3='Mozilla/4.*'
  313.  
  314. Note the use of NETSCAPE.1, NETSCAPE.2 and NETSCAPE.3 -- all three u_agents
  315. will map to the NETSCAPE2 an_ext extension.
  316.  
  317.                        --------    ----   ---------
  318.  
  319. 4.0) A simple, working example
  320.  
  321. For a simple working example of how ByBROWSR.RXX works, cut out the 
  322. following code and create the appropriate (mostly 1 line) files. 
  323. Then, hit TESTBRWS.HTM with you favorite browser(s); and see what happens. 
  324.  
  325. Notes: 
  326.   * Since you are unlikely to have browser that sends a "FOOBAR" 
  327.     user-agent, you can use the SRE-http DOGET.CMD utility to fake it.
  328.   * For status info, set VERBOSE=4 and run PMPRINTF.
  329.  
  330. ------------------- Save as TESTBRWS.HTM (in your GoServe Data Directory)
  331.  
  332. <!doctype html public "-//IETF//DTD HTML 2.0//EN">
  333. <html><head><title>Test of ByBROWSR.RXX </title></head><body>
  334.  
  335. This is a test of browser specific document includes using the
  336. ByBROWSR.RXX utility. You might want to set verbose=4, and watch
  337. what PMPRINTF tells you.
  338. <p>
  339. Test1: Including the generic (own file name) browser-specific document:
  340. <!-- $bybrowsr.rxx -->
  341. <ul><li>
  342. <!-- $ bybrowsr.rxx -->
  343. </ul>
  344. <hr>
  345. Test2: Including a specified <em>browser specfic</em> document (that
  346. may be in another web directory):
  347. <!-- $bybrowsr.rxx  /samples/testinc --> (note that the extension is not used)
  348.  
  349. <ul>
  350. <li> <!-- $ bybrowsr.rxx  /samples/test1inc-->
  351.  
  352. </ul>
  353.  
  354. <hr>
  355.  
  356. End of test
  357. </body></html>
  358.  
  359.  
  360. ------------------- Save as TESTBRWS.DEF (in your GoServe Data Directory)
  361.  
  362. This is the default include
  363.  
  364. ------------------- Save as TESTBRWS.FOO (in your GoServe Data Directory)
  365.  
  366. This is the foo include
  367.  
  368. ------------------- Save as TESTBRWS.NET (in your GoServe Data Directory)
  369.  
  370. This is the netscape specific include.
  371.  
  372. ------------------- Save as SAMPLES/TEST1INC.DEF (relative to your GoServe Data Directory)
  373.  
  374. This is the default browser specfic include of a non-generic file (TEST1INC)
  375.  
  376. ------------------- Save as SAMPLES/TEST1INC.NET (relative to your GoServe Data Directory)
  377.  
  378. This is the netscape specific include.
  379.  
  380. ------------------- Save as SAMPLES/TEST1INC.FOO (relative to your GoServe Data Directory)
  381.  
  382. This is the foo include
  383.  
  384. --------------------- End of files to create.
  385.  
  386.  
  387. .End of document
  388.  
  389.