From bmarwick at uw.edu  Fri Jun 30 04:33:10 2017
From: bmarwick at uw.edu (Ben Marwick)
Date: Fri, 30 Jun 2017 12:33:10 +1000
Subject: [Rd] suggestion: mention how to format DOIs in "Writing R
	Extensions"
Message-ID: <272a4aaf-7862-90d9-2b14-21de5326711f@uw.edu>

Hi Everyone,

I recently has some problems formatting DOIs correctly in a pkg 
submitted to CRAN. Kurt kindly informed me that in the man pages they 
must be \{doi:XXX} (noted in 
https://cran.r-project.org/doc/manuals/r-release/R-exts.html#User_002ddefined-macros) 
and in the DESCRIPTION they must be <DOI:XXX> (not specifically noted 
anywhere).

I wondered if others had similar problems getting DOIs correct in pkg 
documentation, and I thought it could save the CRAN maintainers some 
time if the "Writing R Extensions" document was updated to include a 
mention of DOIs in the in DESCRIPTION.

For example, section "1.1.1 The DESCRIPTION file" currently has this text:

"URLs should be enclosed in angle brackets, e.g. 
'<https://www.r-project.org>'"

and I'd like to propose we replace that with this new text that 
specifically mentions DOIs:

""URLs, DOIs and other Uniform Resource Identifiers should be enclosed 
in angle brackets, e.g. '<https://www.r-project.org>'"

That will help others like me who might be unsure of the proper way to 
format DOIs in the DESCRIPTION file, and save the CRAN maintainers some 
bother.

Making a direct mention of DOIs will also encourage well-formatted and 
visible citations of relevant scholarly work in package DESCRIPTIONs, 
which is a desirable behavior for package authors, and helps to 
strengthen ties between programming and research activities.

What do you think?

best,

Ben



[Rd] suggestion: mention how to format DOIs in "Writing R Extensions"
Ben Marwick