Rd2HTML                package:tools                R Documentation

_W_o_r_k _w_i_t_h _a_n _R_d _o_b_j_e_c_t

_D_e_s_c_r_i_p_t_i_o_n:

     These experimental functions take the output of the 'parse_Rd'
     function and check it or produce a help page from it.  Their
     interfaces (and existence!) are subject to change.

_U_s_a_g_e:

     Rd2HTML(Rd, out = "", package = "", defines = .Platform$OS.type,
             encoding = "unknown", Links = NULL, CHM = FALSE)

     Rd2txt(Rd, out = "", package = "", defines = .Platform$OS.type)

     Rd2latex(Rd, out = "", defines = .Platform$OS.type, encoding = "unknown")

     Rd2ex(Rd, out = "", defines = .Platform$OS.type, encoding = "unknown")

     checkRd(Rd, defines = .Platform$OS.type, encoding = "unknown",
             unknownOK = FALSE, listOK = TRUE)

     findHTMLlinks(pkgDir = "", lib.loc = NULL)

_A_r_g_u_m_e_n_t_s:

      Rd: the 'Rd' object. 

     out: a filename or connection object to which to write the output. 

 package: the package to list in the output. 

 defines: string(s) to use in '"#ifdef"' tests. 

encoding: encoding to use if the file does not specify one. 

   Links: 'NULL' or a named (by topics) character vector of links, as
          returned by 'findHTMLlinks'.

     CHM: logical: prepare HTML suitable for Compiled HTML?

unknownOK: unrecognized macros are treated as errors if 'FALSE',
          otherwise warnings. 

  listOK: unnecessary non-empty braces (e.g. around text, not as an
          argument) are treated as errors if 'FALSE', otherwise
          warnings. 

  pkgDir: The top-level directory of an installed package.

 lib.loc: character vector describing the location of R library trees
          to scan: the default indicates '.libPaths()'.

_D_e_t_a_i_l_s:

     The 'Rd2HTML' converter is still in development, and currently has
     the following known deficiencies:

        *  '"\enc"' is not supported.

        *  Error messages are not as informative as they could be. 
           Often using 'parse_Rd(..., verbose = TRUE)' will give a
           better idea of what is wrong.

        *  Formatting is not always optimal.

     'Rd2ex' extracts the examples in the format used by 'example' and
     R utilities.  it reproduces the previous version up to

        *  The parser does not interpret markup in R comments: this
           used to be done.

        *  Small improvements in layout.

     'findHTMLlinks' uses in decreasing priority

        *  The package in 'pkgDir': this is used when converting HTML
           help for that package.

        *  The packages that are loaded in a vanilla R session.

        *  Other packages found in the library trees specified by
           'lib.loc' in the order of the trees and alphabetically
           within a library tree.

_V_a_l_u_e:

     'Rd2*' are executed mainly for the side effect of writing the
     converted help page.  Its value is the name of that page.

     'checkRd' returns 'TRUE' if the file has no errors; it generates
     an R error otherwise.

     'findHTMLlinks' returns a namesd character vector of relative file
     paths, in the same package or in a package in the same library
     tree.

_A_u_t_h_o_r(_s):

     Duncan Murdoch, Brian Ripley

_R_e_f_e_r_e_n_c_e_s:

     <URL: http://developer.r-project.org/parseRd.pdf>

_S_e_e _A_l_s_o:

     'parse_Rd'

_E_x_a_m_p_l_e_s:

     toolsRd <- Rd_db("tools")
     con <- textConnection(toolsRd[[grep("Rd2HTML.Rd", names(toolsRd))]], "rt")
     outfile <- paste(tempfile(), ".html", sep="")
     browseURL(Rd2HTML(con, outfile, package="tools"))
     close(con)
      
     con <- textConnection(toolsRd[["Rd2HTML.Rd"]], "rt")
     checkRd(con) # A stricter test than Rd2HTML uses
     close(con)