catalogLoad               package:XML               R Documentation

_M_a_n_i_p_u_l_a_t_e _X_M_L _c_a_t_a_l_o_g _c_o_n_t_e_n_t_s

_D_e_s_c_r_i_p_t_i_o_n:

     These functions allow the R user to programmatically control the 
     XML catalog table used in the XML parsing tools in the C-level
     libxml2 library and hence in R packages that use these, e.g. the
     XML and Sxslt packages. Catalogs are consulted whenever an
     external document needs to be loaded. XML catalogs allow one to
     influence how such a document is loaded by mapping document
     identifiers to  alternative locations, for example to refer to
     locally  available versions. They support mapping URI prefixes to
     local file directories/files, resolving both SYSTEM and PUBLIC
     identifiers used in DOCTYPE declarations at the  top of an
     XML/HTML document, and delegating resolution to other catalog
     files. Catalogs are written using an XML format.

     Catalogs allow resources used in XInclude nodes and XSL templates
     to refer to generic network URLs and have these be mapped to local
     files and so avoid potentially slow network retrieval.  Catalog
     files are written in XML  We might have a catalog file that
     contains the XML In the IDynDocs package, we  refer to OmegahatXSL
     files and  DocBook XSL files have a catalog file of the form 

     The functions provided here allow the R programmer to  empty the
     current contents of the global catalog table and so  start from
     scratch ( 'catalogClearTable' ),  load the contents of a catalog
     file into the global catalog table ( 'catalogLoad' ), and to add
     individual entries programmatically without the need for a catalog
     table.

     In addition to controlling the catalogs via these functions, we
     can  use 'catalogResolve' to use the catalog to resolve the name
     of a resource and map it to 

     More information can be found at <URL:
     http://xmlsoft.org/catalog.html> and <URL:
     http://www.sagehill.net/docbookxsl/Catalogs.html> among many
     resources and the specification for the catalog format at <URL:
     http://www.oasis-open.org/committees/entity/spec-2001-08-06.html>.

_U_s_a_g_e:

     catalogLoad(fileNames)
     catalogClearTable()
     catalogAdd(orig, replace, type = "rewriteURI")

_A_r_g_u_m_e_n_t_s:

    orig: a character vector of identifiers, e.g. URIs, that are to be
          mapped to a different  name via the catalog. This can be a
          named character vector where the names are the original URIs
          and the values are the  corresponding rewritten values. 

 replace: a character vector of the rewritten or resolved values for
          the identifiers given in orig. Often this omitted and the 
          original-rewrite pairs are given as a named vector via orig. 

    type: a character vector with the same length as orig (or recycled
          to have the same length) which specifies the type of the
          resources in the elements of orig. Valid values are
          rewriteURI, rewriteSystem, system, public. 

fileNames: a character vector giving the names of the  catalog files to
          load.

_V_a_l_u_e:

     These functions are used for their side effects on the global
     catalog table maintained in C by libxml2. Their return values are
     logical values/vectors indicating whether the particular operation
     were successful or not.

_R_e_f_e_r_e_n_c_e_s:

     This provides an R-like interface to a small subset of the catalog
     API made available in libxml2.

_S_e_e _A_l_s_o:

     'catalogResolve'

     XInclude, XSL and import/include directives.

     In addition to these functions, there is an un-exported,
     undocumented function named 'catalogDump' that can be used to  get
     the contents of the (first) catalog table.

_E_x_a_m_p_l_e_s:

       
               # Add a rewrite rule
          # 
          #  
               catalogAdd(c("http://www.omegahat.org/XML" = system.file("XML", package = "XML")))
               catalogAdd("http://www.omegahat.org/XML", system.file("XML", package = "XML"))
               catalogAdd("http://www.r-project.org/doc/", paste(R.home(), "doc", "", sep = .Platform$file.sep))
             
               # 
          #          This shows how we can load a catalog and then resolve a system identifier 
          #           that it maps.
          #  
               catalogLoad(system.file("exampleData", "catalog.xml", package = "XML"))

               catalogResolve("docbook4.4.dtd", "system")
               catalogResolve("-//OASIS//DTD DocBook XML V4.4//EN", "public")
             
        

