\documentclass[a4paper]{article}
\usepackage{a4}

\oddsidemargin  0.15 in
\evensidemargin 0.35 in
\marginparwidth 1 in
\oddsidemargin 0.25 in
\evensidemargin 0.25 in
\marginparwidth 0.75 in
\textwidth 5.875 in

\setlength{\parskip}{0.7ex plus0.1ex minus0.1ex}
\setlength{\parindent}{0em}

\begin{document}

\SweaveOpts{engine=R}
%\VignetteIndexEntry{Writing CRAN Task Views}
%\VignetteDepends{XML}
%\VignetteKeywords{CRAN task views, repository, packages, installation}
%\VignettePackage{ctv}

\title{Writing CRAN Task Views}
\author{Achim Zeileis}
\date{}
\maketitle

CRAN task views should provide some guidance which part
of the growing number of packages on CRAN are useful for
a certain topic. They should give a brief overview of the
contained packages and allow automatic installation. Infrastructure
for both tasks is provided in \verb/.ctv/ files, an XML-based
specification of CRAN task views. The format is based on just
a handful of new tags and is mostly self-explanatory. A brief
artificial example is given here, more detailed explanations
are given below:

\begin{verbatim}
<CRANTaskView>

  <name>Econometrics</name>
  <topic>Econometrics</topic>
  <maintainer email="Achim.Zeileis@R-project.org">Achim Zeileis</maintainer>
  <version>2016-09-14</version>
  <url>https://CRAN.R-project.org/view=Econometrics</url>

  <info>
    Emphasize something <b>important</b> with standard HTML tags,
    and reference the package <pkg>foo</pkg> and also the view
    <view>TimeSeries</view>.
  </info>

  <packagelist>
    <pkg>foo</pkg>
    <pkg priority="core">bar</pkg>
  </packagelist>

  <links>
    <a href="http://path/to/homepage/">The Title of a Relevant Homepage</a>
    <view>TimeSeries</view>
  </links>

</CRANTaskView>
\end{verbatim}

The whole document is framed by an opening and closing \verb/<CRANTaskView>/
tag. Within these, there are the following sections: \verb/<name>/, \verb/<topic>/,
\verb/<maintainer>/, \verb/<version>/, \verb/<url>/,
\verb/<info>/, \verb/<packagelist>/ and \verb/<links>/.

\verb/<name>/ gives the name of the task view. This is used as the identifier
for installing the view and as the name for the XML file, e.g., \verb/Econometrics.ctv/,
and the auto-generated HTML file, e.g., \verb/Econometrics.html/. Hence, it should be
not too long and contain no special characters like spaces.

\verb/<topic>/ is a plain text specification of the topic of the task view.
(Note that in XML files there are three special characters \verb/</, \verb/>/
and \verb/&/ that need to be escaped by their HTML counterparts.)

\verb/<maintainer>/ gives the name of the maintainer in plain text
with support for specification of an e-mail address.

\verb/<version>/ is specified by a date (in ISO format).

\verb/<url>/ is an optional URL. For official CRAN view URLs, this is added automatically.

\verb/<info>/ should be a short description of the packages that explains
which packages are useful for which tasks. It can also contain any further
informations and should be written in plain HTML code, i.e., any HTML markup
can be used (preferably following XHTML conventions). There are seven additional
tags available: \verb/<pkg>/, \verb/<view>/,
\verb/<bioc>/, \verb/<ohat>/, \verb/<rforge>/, \verb/<gcode>/, and \verb/<code>/. \verb/<pkg>/ and
\verb/<view>/ should be used as markup for packages and views (in the same repository), respectively.
During generation of the corresponding HTML file, they will be replaced by
hyperlinks to the packages/views.
Similarly, \verb/<bioc>/, \verb/<ohat>/, \verb/<rforge>/, and \verb/<gcode>/
can be used to refer to projects on Bioconductor, Omegahat, \textsf{R}-Forge, and Google Code.
These will be replaced by the appropriate hyperlinks to the project on
\texttt{http://www.Bioconductor.org/}, \texttt{http://www.Omegahat.org/},
\texttt{http://R-Forge.R-project.org/}, and \texttt{http://Code.Google.com/}, respectively.
Finally, \verb/<code>/ can be used as markup for \textsf{R} code which will 
simply be set in a typewriter font.

\verb/<packagelist>/ contains the list of packages associated with the view.
It should contain (at least) all packages mentioned in the \verb/<info>/ section
and allows for a distinction between \verb/"core"/ and \verb/"normal"/ (default)
priority packages. The distinction is only important for the installation of
certain views because the user can specify whether all packages (default) or only
the most important core packages should be installed (with all their dependencies).

\verb/<links>/ is a means of specifying further places where information about
the discussed topic and related issues is discussed, e.g., manuals/books/tutorials
on how to do Econometrics, say, with \textsf{R}.

\textit{Remark:} If you need to include special characters, e.g., an umlaut, in
a \verb/.ctv/ file, you can do so in the \verb/<info>/ section by simply writing
it in HTML code (note, however, that \verb/&/ is the escape character in XML/HTML).
Otherwise, you can include special characters
in UTF-8 encoding provided you add the declaration
\verb/<?xml version="1.0" encoding="UTF-8"?>/ in the first line of the \verb/.ctv/ file.
This applies in particular if you need an umlaut in the \verb/<maintainer>/ field.

For a template of a \verb/.ctv/ file, look at the included \verb/Econometrics.ctv/.
It can be read and printed by

<<>>=
library("ctv")
x <- read.ctv(system.file("ctv", "Econometrics.ctv", package = "ctv"))
x
@

The resulting object can be transformed into HTML by \verb/ctv2html(x)/.
Once this view has been installed at a CRAN-style repository as
\texttt{http://CRAN.R-project.org/web/views/}, it can be installed by
the user by \verb/install.views("Econometrics")/ or \verb/update.views("Econometrics")/
(which first checks whether up-to-date versions of any packages are already
installed).

\end{document}
