doc2Rd               package:mvbutils               R Documentation

_C_o_n_v_e_r_t_s _f_l_a_t _d_o_c_u_m_e_n_t_a_t_i_o_n _t_o _R_d _f_o_r_m_a_t

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

     For functions whose 'help' documentation is stored as a 'doc'
     attribute; the text in the 'doc' attribute is converted into a Rd
     format character vector. The documentation of the 'mvbutils'
     package and the 'debug' package was produced this way.

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

      doc2Rd( fun)

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

     fun: function object, or character string that names a function.

_D_e_t_a_i_l_s:

     Flat-format (plain-text) documentation in 'doc' attributes can be
     displayed by the replacement 'help' in 'mvbutils' (see 'dochelp').
     For informal purposes, you can write such documentation any way
     you want. However, if you want to use 'doc2Rd' to convert it to Rd
     format, the documentation must follow the rules below. At first
     sight, these might seem worse than having to learn how to write
     "native" Rd format, but in practice they are very simple. Check
     the file "sample.fun.rrr" in the "demo" subdirectory to see how
     it's done. The formal description below is harder to follow.

     The first line should be the docfile name (without the Rd)
     followed by a few spaces and the package descriptor, like so:

     utility-funs package:mypack

     When 'doc2Rd' runs, the docfile name will appear in both the
     name{} field and the first alias{} field. 'formalize.package' will
     actually create the file "utility-funs.Rd".

     The next non-blank lines form the other alias entries. Each line
     should consist of one word, preceded by one or more spaces for
     safety (not necessary if they have normal names).

     After the blank line at the end of the aliases, put a one-line
     title, without any quotes.

     Put section titles in capital letters. With multi-word section
     titles, replace the spaces by periods: e.g. write SEE.ALSO instead
     of SEE ALSO. The recognized sections are: DESCRIPTION, USAGE,
     SYNOPSIS, ARGUMENTS, VALUE, DETAILS, EXAMPLES, AUTHOR, SEE.ALSO,
     REFERENCES, NOTE, KEYWORDS.

     Other unrecognized section titles (in capitals) can be used, and
     will be sentence-cased and wrapped in a section{} construct. If an
     unrecognized section title ends with a period, the text up to the
     next section will be treated like ARGUMENTS; otherwise, it will be
     treated like DESCRIPTION (basically, as plain text).

     Bulleted lists within DESCRIPTION, DETAILS, AUTHOR, REFERENCES and
     NOTE sections are identified by lines starting with one or more
     spaces, then a "-", then another space. Such lists are converted
     into itemize{item ..., item ...} constructs.

     Each ARGUMENTS item, and optionally each VALUE item, should be on
     a line beginning with one or more spaces. Lines that don't start
     with a space will be interpreted as normal text in these sections.
     Normal text is fine, but you need to itemize arguments to satisfy
     RCMD CHECK.

     Almost anything between a pair of single quotes will be put into a
     code{} construct, and the quotes will be removed. Anything of the
     form "See XXX" or "see XXX" or "XXX (qv)", where XXX is in single
     quotes, will be put into a code{ link{ } } construct, and the "
     (qv)" will be removed (see also next para). In USAGE and EXAMPLES,
     and inside code fragments elsewhere, make sure that only double
     quotes " are used. The exception to code{} is that, with
     "[pP]ackage 'x'" and "'x' package", 'x' will go into a pkg{}
     construct rather than a code construct.

     Function names in SEE.ALSO should _not_ be in single quotes, and
     should be separated by commas or semicolons; they will be put into
     code{ link{ } } constructs. Single-quoted words (with "-" and "."
     allowed internally) not terminated by a comma or semicolon go into
     code{} constructs (i.e. no link{}), or pkg{} constructs if
     preceded or followed by "package". Unquoted words not terminated
     by a comma or semicolon or end-of-line will not be put into
     constructs. End-of-line spaces are stripped first. You can split
     SEE.ALSO across several lines; this won't matter for pager help,
     but can help produce tidier output in the file "***-manual.tex"
     produced by RCMD CHECK.

     For some reason, two successive closing braces without a space
     between them seem to cause problems for RCMD CHECK when creating
     "***-manual.tex"- so don't do that!

     For "don't run" examples, put a "## Don't run" line before and a
     "## End don't run" line after.

     Start the keyword list with a space, and separate keywords with
     commas or semicolons.

     Lines that start with a % will have the % removed before
     conversion. They aren't displayed by 'dochelp', though, so can be
     used to hide an unhelpful SYNOPSIS, say, or to hide an "#ifdef
     windows".

     Triple dots are converted to \\&..., regardless of whether they're
     in code or normal text. R is converted to \\R.

     Any "*emphatic*" constructions (no quotes, just the asterisks)
     will go into emph{} constructs. No other fancy constructs are
     supported (yet).

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

     Character vector containing the text as it would appear in an Rd
     file. Use 'cat' with 'sep="\\n"' to display this.

_A_u_t_h_o_r(_s):

     Mark Bravington

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

     To do a whole group at once: 'formalize.package' The file
     "sample.fun.rrr" and the demo "flatdoc.demo.r" in subdirectory
     "demo" Also: 'flatdoc', 'make.usage.section',
     'make.arguments.section', 'write.sourceable.function'

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

     ## Not run: 
     ## Needs a function with the right kind of "doc" attr
     text.doc <- doc2Rd( "source.mvb")
     cat( doc2Rd( doc2Rd), sep="\n")
     ## End(Not run)

