1\name{Rdo2Rdf}
2\alias{Rdo2Rdf}
3%- Also NEED an '\alias' for EACH other topic documented here.
4\title{
5  Convert an Rd object to Rd file format
6}
7\description{
8  Converts an Rd object to Rd format and saves it to a file or returns
9  it as a character vector. It escapes percents where necessary and
10  (optionally) backslashes in the examples section.
11}
12\usage{
13Rdo2Rdf(rdo, deparse = FALSE, ex_restore = FALSE, file = NULL,
14        rcode = TRUE, srcfile = NULL)
15}
16%- maybe also 'usage' for other objects documented here.
17\arguments{
18  \item{rdo}{an Rd object or a character vector, see `Details'.}
19  \item{deparse}{logical, passed to the print method for Rd objects,
20    see `Details'.
21  }
22  \item{ex_restore}{logical, if \code{TRUE} escapes backslashes where
23    necessary.
24  }
25  \item{file}{a filename where to store the result. If \code{NULL} or
26    "missing", the result is returned as a character vector.
27  }
28  \item{rcode}{if TRUE, duplicate backslahes in RCODE elements, see
29    Details.
30  }
31  \item{srcfile}{NULL or a file name, see 'Details'.}
32}
33\details{
34  The description here is rather technical and incomplete. In any case
35  it concerns almost exclusively Rd files which use escape sequences
36  containing multiple consecutive backslashes or escaped curly braces
37  (such things appear in regular expressions, for example).
38
39  In principle, this function should be redundant, since the
40  \code{print} and \code{as.character} methods for objects of class "Rd"
41  would be expected to do the job. I was not able to get the desired
42  result that way (the \code{deparse} option to \code{print} did not
43  work completely for me either).
44
45  Arguments \code{ex_restore} and \code{rcode} were added on an ad-hoc
46  basis. \code{rcode} is more recent and causes \code{Rdo2Rdf} to
47  duplicate backslashes found in any element \code{Rd_tag}-ed with
48  "RCODE". \code{ex_restore} does the same but only for the examples
49  section. In effect, if \code{rcode} is TRUE, \code{ex_restore} is
50  ignored.
51
52  The initial intent of this function (and the package Rdpack as a whole
53  was not to refer to the Rd source file. However, there is some
54  flexibility in the Rd syntax that does not allow the source file to be
55  restored identically from the parsed object. This concerns mainly
56  backslahes (and to some extent curly braces) which in certain contexts
57  may or may not be escaped and the parsed object is the same. Although
58  this does not affect functionality, it may be annoying if the escapes
59  in sections not examined by \code{reprompt} were changed.
60
61  If \code{srcfile} is the name of a file, the file is parsed and the Rd
62  text of sections of \code{rdo} that are identical to sections from
63  \code{srcfile} is taken directly from \code{srcfile}, ensuring that
64  they will be identical to the original.
65
66
67
68}
69\value{
70  \code{NULL}, if \code{file} is not \code{NULL}. Otherwise the Rd
71  formatted text as a character vector.
72}
73
74\author{Georgi N. Boshnakov}
75
76\note{
77  Here is an example when the author's Rd source cannot be restored
78  exactly from the parsed object.
79
80  In the Rd source "author" has two backslashes here: \verb{\\author}.
81
82  In the Rd source "author" has one backslash here: \verb{\author}.
83
84  Both sentences are correct and the parsed file contains only one
85  backslash in both cases. If \code{reprompt} looks only at the parsed
86  object it will export one backslash in both cases. So, further
87  reprompt()-ing will not change them again. This is if \code{reprompt}
88  is called with \code{sec_copy = FALSE}.  With the default
89  \code{sec_copy = TRUE}, \code{reprompt} calls \code{Rdo2Rdf} with
90  argument \code{srcfile} set to the name of the Rd file and since
91  \code{reprompt} does not modify section "Note", its text is copied
92  from the file and the author's original preserved.
93
94
95  However, the arguments of \verb{\eqn} are parse_Rd-ed differently (or
96  so it seems) even though they are also in verbatim.
97
98
99}
100%% ~Make other sections like Warning with \section{Warning }{....} ~
101
102
103\examples{
104# # this keeps the backslashes in "author" (see Note above)
105# reprompt(infile="./man/Rdo2Rdf.Rd")
106
107# # this output "author" preceded by one backslash only.
108# reprompt(infile="./man/Rdo2Rdf.Rd", sec_copy = FALSE)
109}
110\keyword{Rd}
111