New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added full MARC role support, using the specification at http://www.loc.gov/marc/relators/relaterm.html #662

Merged
merged 4 commits into from Oct 2, 2017

Conversation

Projects
None yet
2 participants
@publicus
Contributor

publicus commented Sep 6, 2017

Hello,

First, thank you for your work on roxygen! It's a wonderful tool.

This Pull Request adds support for the full standardized list of MARC roles for contributors to a package.

This Pull Request stems from a question I posted on StackExchange earlier today. I noticed that ?mypackagename returns [NA] for any contributor under "Author(s)" when that person's role is listed as any of many valid MARC roles -- for example, if Jane Smith below is listed as csp (Consultant to a Project).

Example part of DESCRIPTION file:

Authors@R: c(
    person("John", "Doe", email = "jdoe@example1.com", role = c("aut", "cre")),
    person("Jane", "Smith", email = "jsmith@example2.com", role = "csp", comment = "Provided intellectual overview."))

Relevant output from ?mypackagename:

Maintainer: John Doe jdoe@example1.com

Other contributors:

Jane Smith jsmith@example2.com (Provided intellectual overview.) [NA]

Thus, aside from viewing the source code of the package, readers of the package documentation would not be able to tell what role Jane Smith had in the project.

This confused me for several reasons:

  1. Hadley Wickham's excellent book on R Packaging refers readers to the full list of MARC roles, noting, "The full list of roles is extremely comprehensive. Should your package have a woodcutter ('wdc'), lyricist ('lyr') or costume designer ('cst'), rest comfortably that you can correctly describe their role in creating your package."
    (I recognize that Dr. Wickham's book is not connected to this package, but it is a popular resource for users; thus, others may have the same confusion in the future.)
  2. The documentation for ?person states that "The new scheme ... adds the possibility of specifying roles based on a subset of the MARC Code List for Relators (https://www.loc.gov/marc/relators/relaterm.html). When giving the roles of persons in the context of authoring R packages, the following usage is suggested." [emphasis added]
    Thus, ?person does not state that only a subset of the MARC list should be recognized, only that it suggests the use of 9 roles (author, compiler, contributor, copyright holder, creator, contractor, data contributor, thesis advisor, and translator).
  3. The list of what roles roxygen recognizes is already larger than the list given in ?person: ?person suggests the 9 roles listed above, while roxygen additionally recognizes a 10th, funder.

With all this in mind, would you consider adding support for the full list of MARC roles (by accepting this Pull Request)? By doing so, the list would still by curated and standardized (through MARC), but would be less potentially confusing to users trying to figure out which roles are supported.

This PR makes just one change to the roxygen code, to expand the role_lookup vector in object-package.R.

Thank you for your work, and for your consideration!

@publicus

This comment has been minimized.

Contributor

publicus commented Sep 8, 2017

Following my comment earlier this week, I did think today to add one additional note through an example. While it is likely that most projects will not have a need to recognize woodcutters or lyricists, several MARC codes have been useful for me in a recent project to accurately assign credit where it's due: In addition to Author (aut) and Creator (cre), these have been helpful to use for this particular project:

  • Designer (dsr)
  • Engineer (eng)
  • Programmer (prg)
  • Conceptor (ccp)
  • Consultant to a project (csp)

Allowing use of all MARC roles also follows Allen, Scott, Brand, Hlava, and Altman's (2014) call in Nature to assign credit more broadly and accurately, by allowing authors to use codes that map well onto Allen et al.'s proposed taxonomy of credit.

Again, thank you for your work on this project!

@hadley

Can you please also add a bullet to NEWS briefly describing the change and acknowledging yourself and this PR, copying the style in the other entries.

"fnd" = "funder",
"ths" = "thesis advisor",
"trl" = "translator"
"abr" = "abridger",

This comment has been minimized.

@hadley

hadley Oct 1, 2017

Collaborator

Could you please match the existing indent?

@publicus

This comment has been minimized.

Contributor

publicus commented Oct 2, 2017

@hadley, can do! I've pushed two commits with the following changes:

  1. Replace tabs with two spaces in the changes I originally made.
  2. Add a bullet in NEWS under "Minor improvements and bug fixes" for roxygen2 6.0.1.9000, explaining the change and referencing my GitHub account and this PR.
@publicus

This comment has been minimized.

Contributor

publicus commented Oct 2, 2017

I included a link to the MARC Relator codes list from the Library of Congress in the NEWS bullet, but realize that links aren't included in any of the other bullets. Thus, I'm happy to remove it if necessary.

NEWS.md Outdated
@@ -52,6 +52,9 @@
## Minor improvements and bug fixes
* `person` now supports all [MARC Relator](http://www.loc.gov/marc/relators/relaterm.html "MARC Relator roles")

This comment has been minimized.

@hadley

hadley Oct 2, 2017

Collaborator

I think you can remove "MARC Relator roles"

This comment has been minimized.

@publicus

publicus Oct 2, 2017

Contributor

I've now removed it, in commit c771b0f.

@hadley hadley merged commit b2a3124 into klutometis:master Oct 2, 2017

1 check was pending

continuous-integration/travis-ci/pr The Travis CI build is in progress
Details
@hadley

This comment has been minimized.

Collaborator

hadley commented Oct 2, 2017

Thanks!

@publicus

This comment has been minimized.

Contributor

publicus commented Oct 2, 2017

Thank you! I appreciate your consideration, and your work more generally!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment