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