1% File src/library/utils/man/person.Rd
2% Part of the R package, https://www.R-project.org
3% Copyright 1995-2020 R Core Team
4% Distributed under GPL 2 or later
5
6\name{person}
7\title{Persons}
8\alias{person}
9\alias{as.person}
10\alias{as.person.default}
11\alias{[.person}
12\alias{$.person}
13\alias{as.character.person}
14\alias{c.person}
15\alias{format.person}
16\alias{print.person}
17\alias{toBibtex.person}
18\alias{personList}
19\alias{as.personList}
20\alias{as.personList.person}
21\alias{as.personList.default}
22\description{
23  A class and utility methods for holding information about persons
24  like name and email address.
25}
26\usage{
27person(given = NULL, family = NULL, middle = NULL,
28       email = NULL, role = NULL, comment = NULL,
29       first = NULL, last = NULL)
30\method{as.person}{default}(x)
31\method{format}{person}(x,
32       include = c("given", "family", "email", "role", "comment"),
33       braces = list(given = "", family = "", email = c("<", ">"),
34                     role = c("[", "]"), comment = c("(", ")")),
35       collapse = list(given = " ", family = " ", email = ", ",
36                       role = ", ", comment = ", "),
37       ...,
38       style = c("text", "R")
39       )
40}
41\arguments{
42  \item{given}{a character vector with the \emph{given} names,
43    or a list thereof.}
44  \item{family}{a character string with the \emph{family} name,
45    or a list thereof.}
46  \item{middle}{a character string with the collapsed middle name(s).
47    Deprecated, see \bold{Details}.}
48  \item{email}{a character string (or vector) giving an e-mail address
49    (each),
50    or a list thereof.}
51  \item{role}{a character vector specifying the role(s) of the person
52    (see \bold{Details}),
53    or a list thereof.}
54  \item{comment}{a character string (or vector) providing comments,
55    or a list thereof.}
56  \item{first}{a character string giving the first name.
57    Deprecated, see \bold{Details}.}
58  \item{last}{a character string giving the last name.
59    Deprecated, see \bold{Details}.}
60  \item{x}{a character string for the \code{as.person} default method;
61    an object of class \code{"person"} otherwise.}
62  \item{include}{a character vector giving the fields to be included
63    when formatting.}
64  \item{braces}{a list of characters (see \bold{Details}).}
65  \item{collapse}{a list of characters (see \bold{Details}).}
66  \item{\dots}{currently not used.}
67  \item{style}{a character string specifying the print style, with
68    \code{"R"} yielding formatting as R code.}
69}
70\value{
71  \code{person()} and \code{as.person()} return objects of class
72  \code{"person"}.
73}
74\details{
75  Objects of class \code{"person"} can hold information about an
76  arbitrary positive number of persons.  These can be obtained by one
77  call to \code{person()} with list arguments, or by first creating
78  objects representing single persons and combining these via
79  \code{c()}.
80
81  The \code{format()} method collapses information about persons into
82  character vectors (one string for each person): the fields in
83  \code{include} are selected, each collapsed to a string using the
84  respective element of \code{collapse} and subsequently
85  \dQuote{embraced} using the respective element of \code{braces}, and
86  finally collapsed into one string separated by white space.  If
87  \code{braces} and/or \code{collapse} do not specify characters for all
88  fields, the defaults shown in the usage are imputed.
89  If \code{collapse} is \code{FALSE} or \code{NA} the corresponding
90  field is not collapsed but only the first element is used.
91  The \code{print()} method calls the \code{format()} method and prints
92  the result, the \code{toBibtex()} method creates a suitable BibTeX
93  representation.
94
95  Person objects can be subscripted by fields (using \code{$}) or by
96  position (using \code{[}).
97
98  \code{as.person()} is a generic function.  Its default method tries to
99  reverse the default person formatting, and can also handle formatted
100  person entries collapsed by comma or \code{"and"} (with appropriate
101  white space).
102
103  Personal names are rather tricky, e.g.,
104  \url{https://en.wikipedia.org/wiki/Personal_name}.
105
106  The current implementation (starting from R 2.12.0) of the
107  \code{"person"} class uses the notions of \emph{given} (including
108  middle names) and \emph{family} names, as specified by \code{given}
109  and \code{family} respectively.  Earlier versions used a scheme based
110  on first, middle and last names, as appropriate for most of Western
111  culture where the given name precedes the family name, but not
112  universal, as some other cultures place it after the family name, or
113  use no family name.  To smooth the transition to the new scheme,
114  arguments \code{first}, \code{middle} and \code{last} are still
115  supported, but their use is deprecated and they must not be given in
116  combination with the corresponding new style arguments.  For persons
117  which are not natural persons (e.g., institutions, companies, etc.) it
118  is appropriate to use \code{given} (but not \code{family}) for the
119  name, e.g., \code{person("R Core Team", role = "aut")}.
120
121  The new scheme also adds the possibility of specifying \emph{roles}
122  based on a subset of the MARC Code List for Relators
123  (\url{https://www.loc.gov/marc/relators/relaterm.html}).
124  When giving the roles of persons in the context of authoring \R
125  packages, the following usage is suggested.
126  \describe{
127    \item{\code{"aut"}}{(Author) Use for full authors who have made
128      substantial contributions to the package and should show up in the
129      package citation.}
130    \item{\code{"com"}}{(Compiler) Use for persons who collected code
131      (potentially in other languages) but did not make further
132      substantial contributions to the package.}
133    \item{\code{"cph"}}{(Copyright holder) Use for all copyright
134      holders.  This is a legal concept so should use the legal name of
135      an institution or corporate body.}
136    \item{\code{"cre"}}{(Creator) Use for the package maintainer.}
137    \item{\code{"ctb"}}{(Contributor) Use for authors who have made
138      smaller contributions (such as code patches etc.) but should not
139      show up in the package citation.}
140    \item{\code{"ctr"}}{(Contractor) Use for authors who have been
141      contracted to write (parts of) the package and hence do not own
142      intellectual property.}
143    \item{\code{"dtc"}}{(Data contributor) Use for persons who
144      contributed data sets for the package.}
145    \item{\code{"fnd"}}{(Funder) Use for persons or organizations that
146      furnished financial support for the development of the package.}
147    \item{\code{"rev"}}{(Reviewer) Use for persons or organizations
148      responsible for reviewing (parts of) the package.}
149    \item{\code{"ths"}}{(Thesis advisor) If the package is part of a
150      thesis, use for the thesis advisor.}
151    \item{\code{"trl"}}{(Translator) If the R code is a translation from
152      another language (typically S), use for the translator to R.}
153  }
154
155  In the old scheme, person objects were used for single persons, and a
156  separate \code{"personList"} class with corresponding creator
157  \code{personList()} for collections of these.  The new scheme employs
158  a single class for information about an arbitrary positive number of
159  persons, eliminating the need for the \code{personList} mechanism.
160
161  The \code{comment} field can be used for \dQuote{arbitrary} additional
162  information about persons.  Elements named \code{"ORCID"} will be
163  taken to give ORCID identifiers (see \url{https://orcid.org/} for more
164  information), and be displayed as the corresponding URIs by the
165  \code{print()} and \code{format()} methods (see \bold{Examples}
166  below).
167
168}
169\seealso{
170  \code{\link{citation}}
171}
172\keyword{misc}
173\examples{
174## Create a person object directly ...
175p1 <- person("Karl", "Pearson", email = "pearson@stats.heaven")
176
177## ... or convert a string.
178p2 <- as.person("Ronald Aylmer Fisher")
179
180## Combining and subsetting.
181p <- c(p1, p2)
182p[1]
183p[-1]
184
185## Extracting fields.
186p$family
187p$email
188p[1]$email
189
190## Specifying package authors, example from "boot":
191## AC is the first author [aut] who wrote the S original.
192## BR is the second author [aut], who translated the code to R [trl],
193## and maintains the package [cre].
194b <- c(person("Angelo", "Canty", role = "aut", comment =
195         "S original, <http://statwww.epfl.ch/davison/BMA/library.html>"),
196       person(c("Brian", "D."), "Ripley", role = c("aut", "trl", "cre"),
197              comment = "R port", email = "ripley@stats.ox.ac.uk")
198     )
199b
200
201## Formatting.
202format(b)
203format(b, include = c("family", "given", "role"),
204   braces = list(family = c("", ","), role = c("(Role(s): ", ")")))
205
206## Conversion to BibTeX author field.
207paste(format(b, include = c("given", "family")), collapse = " and ")
208toBibtex(b)
209
210## ORCID identifiers.
211(p3 <- person("Achim", "Zeileis",
212              comment = c(ORCID = "0000-0003-0918-3766")))
213}
214