Chapter 13. Author, license and version information

So you have written a set of plugins, and you are getting ready to share your work. To make sure users will know what your work is all about, under what terms they can use and distribute it, and whom they should contact about issues or ideas, you should add some information about your plugins. This can be done using the <about> element. It can be used in either the .pluginmap or in individual plugin .xml files (in both cases as a direct child of the document tag). When specified in the .pluginmap it will apply to all plugins. If <about> is specified in both places, the <about> information in the plugin .xml file will override that in the .pluginmap file. You can also add an <about> element to .rkh-pages, which are not connected to a plugin, if there is a need for that.

Here is an example .pluginmap file with only a few explanations, below. In cases of doubt, more information may be available from the reference.

<document 
	namespace="rkward"
	id="SquaretheCircle_rkward"
>
	<about 
		name="Square the Circle"
		shortinfo="Squares the circle using Heisenberg compensation."
		version="0.1-3"
		releasedate="2011-09-19"
		url="http://eternalwondermaths.example.org/23/stc.html"
		license="GPL"
		category="Geometry"
	>
		<author 
			given="E.A."
			family="Dölle"
			email="[email protected]"
			role="aut"
		 />
		<author 
			given="A."
			family="Assistant"
			email="[email protected]"
			role="cre, ctb"
		 />
	</about>
	<dependencies>
		...
	</dependencies>
	<components>
		...
	</components>
	<hierarchy>
		...
	</hierarchy>
</document>

Most of this should explain itself, so we’ll not discuss each and every tag element. But let’s look at some details that probably need some commentary for easier understanding.

The category element in <about> can be defined rather freely, but should be meaningful, as it’s thought to be used to order plugins into groups. All other attributes in this opening tag are mandatory and must be filled with reasonable content.

At least one <author> with a valid email address and the role aut (author) must also be given. In case your plugin causes problems or someone would like to share its gratitude with you, it should be easy to contact someone who’s involved. For further information on other valid roles, like ctb for code contributors or cre for package maintenance, please refer to the R documentation on person().

Note

Remember that you can use <include> and / or <insert> to repeat information across several .xml files (e.g. information on an author who was involved with several plugins). More information.

Tip

You do not have to write this XML code by hand. If you use the function rk.plugin.skeleton() from the rkwarddev package and provide all necessary information via the about option, it will automatically create a .pluginmap file with a working <about> section for you.