-
Notifications
You must be signed in to change notification settings - Fork 2
/
Rds.html
115 lines (107 loc) · 3.85 KB
/
Rds.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>Guidelines for Rd files</title>
</head>
<body bgcolor="#FFFFFF">
<h1 align="center">Guidelines for Rd files</h1>
<i>These are suggested guidelines for the system help files (in
<samp>.Rd</samp> format) that are intended for core developers but
may also be useful for package writers.</i>
<ul>
<li>
The page <samp>\title</samp> and the <samp>\section</samp> titles
should be capitalized and not end in a period.
<br>
It is best to avoid all markup in titles, which need to be
automatically processed for various hypertext search systems.
</li>
<li>
Argument lists need to cover all the arguments in all the functions
covered, including '<samp>...</samp>'.
<br>
This is also checked by <code>tools::checkDocFiles()</code>,
run as part of <samp>R CMD check</samp>.
</li>
<li>
Do provide text alternatives for all but the very simplest
<samp>\eqn</samp> and <samp>\deqn</samp> commands.
</li>
<li>
<samp>In \source</samp> and <samp>\references</samp> sections
<ul>
<li>
Use separate paragraphs (separated by a blank line) for each
reference.
<li>
Write authors' names in the form <samp>Author, A. B.</samp> and
separate them by a comma or <samp>and</samp> (but not both).
<li> Give a date immediately after the author(s), and do not put a
period after the date.
<li> Enclose titles of books and journals (but <em>not</em> articles)
in <samp>\emph{...}</samp>.
<li> Enclose volume numbers for journals in <samp>\bold{...}</samp>
and follow them by a comma.
<li> Use <samp>--</samp> for page ranges.
<li> If you give an address for a publisher (probably unnecessary)
use the form <samp>New York: Springer-Verlag</samp>.
</ul>
</li>
<li>
In <samp>\usage</samp> and <samp>\examples</samp> sections
<ul>
<li> Watch the line length: 65 characters is a reasonable limit.
<li> Use <samp>TRUE</samp> and <samp>FALSE</samp> rather than
<samp>T</samp> and <samp>F</samp>.
<li> Readability is greatly enhanced by adding spaces around binary
operators and after commas in argument lists. In particular,
<samp><-</samp> needs spaces around it.
<li> Always use <samp><-</samp> rather than <samp>=</samp> for
assignments.
<li> Follow the 'R core' indentation guidelines for example code
(which basically means an indentation level of 4 spaces and aligning
continuation lines suitably — but copy the code into a
<samp>.R</samp> Emacs buffer and reformat it there).
</ul>
</li>
<li>
Ensure that the <samp>\usage</samp> section exactly matches the
function definition.
<code>tools::codoc()</code> run as part of <samp>R CMD check</samp>
will complain if it doesn't.
</li>
<li>
Not only make sure that examples are directly executable, also make
sure that they are system-independent (do not use <samp>system</samp>)
and do not require special facilities (for example Internet access or
write permission to specific directories).
</li>
<li>
Use quotation marks sparingly: quotation marks are used for R objects
in text rendition. If you must use them, make them double
(<samp>\dQuote{a quotation}</samp>), and use <samp>\sQuote</samp> and
<samp>\dQuote</samp}.
</li>
<li>
Do not use tabs to indent (as these do not render correctly on all
possible pagers).
</li>
<li>
Please put two spaces after the end of a sentence in sections with
running text (<samp>\description</samp>, <samp>\details</samp>, ...).
</li>
<li>
For consistency, aim to use British (rather than American)
spelling. (NB: British spelling often uses <samp>-ize</samp> as in
'capitalize'. The view of <samp>spell -b</samp> of British spelling is
a flawed American one. There are English/Scottish differences too.)
</li>
<li>
Do not use <samp>&</samp> except where quoting (for example, the
publisher that has been called <samp>Chapman & Hall</samp> fairly
recently).
</li>
</ul>
</body>
</html>