.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "SVN::Web 3pm"
.TH SVN::Web 3pm "2016-11-12" "perl v5.24.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
SVN::Web \- Subversion repository web frontend
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
If you are upgrading an existing SVN::Web installation then please see
\&\s-1UPDATING\s0.pod.  Installing new SVN::Web versions without making sure
the configuration file, templates, and localisations are properly updated
and merged will likely break your current installation.
.PP
To get started with SVN::Web.
.IP "1." 4
Create a directory for SVN::Web's configuration files, templates,
stylesheets, and other data.
.Sp
.Vb 1
\&  mkdir svnweb
.Ve
.IP "2." 4
Run \f(CW\*(C`svnweb\-install\*(C'\fR in this directory to configure the environment.
.Sp
.Vb 2
\&  cd svnweb
\&  svnweb\-install
.Ve
.IP "3." 4
Edit the file \fIconfig.yaml\fR that's been created, and add the following
two lines:
.Sp
.Vb 2
\&  repos:
\&    test: \*(Aqfile:///path/to/repo\*(Aq
.Ve
.Sp
\&\f(CW\*(C`file:///path/to/repo\*(C'\fR should be the \s-1URL\s0 for an existing Subversion
repository.
.IP "4." 4
Either configure your web server (see \*(L"\s-1WEB SERVERS\*(R"\s0) to use SVN::Web,
or run with \f(CW\*(C`plackup\*(C'\fR to start a simple web server for testing.
.Sp
.Vb 1
\&  plackup \-Ilib/ ./SVN\-Web.psgi
.Ve
.IP "5." 4
Point your web browser at the correct \s-1URL\s0 to browse your repository.
If you've run \f(CW\*(C`plackup\*(C'\fR then this is <http://localhost:5000/>.
.PP
See <https://github.com/djzort/SVN\-Web> for the SVN::Web source code.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
SVN::Web provides a web interface to subversion repositories. It's
features include:
.IP "\(bu" 4
Viewing multiple Subversion repositories.  SVN::Web is a full
Subversion client, so you can access repositories on the local disk
(with the \f(CW\*(C`file:///\*(C'\fR scheme) or that are remotely accessible using
the \f(CW\*(C`http://\*(C'\fR and \f(CW\*(C`svn://\*(C'\fR schemes.
.IP "\(bu" 4
Browsing every revision of the repository.
.IP "\(bu" 4
Viewing the contents of files in the repository at any revision.
.IP "\(bu" 4
Viewing diffs of arbitrary revisions of any file.  Diffs can be viewed
as plain unified diffs, or \s-1HTML\s0 diffs that use colour to more easily
show what's changed.
.IP "\(bu" 4
Viewing the revision log of files and directories, see what was changed
when, by who.
.IP "\(bu" 4
Viewing the blame/annotation details of any file.
.IP "\(bu" 4
Generating \s-1RSS\s0 feeds of commits, down to the granularity of individual
files.  The \s-1RSS\s0 feeds are auto-discoverable in modern web browsers.
.IP "\(bu" 4
Viewing everything that was changed in a revision, and step through revisions
one at a time, viewing the history of the repository.
.IP "\(bu" 4
Viewing the interface in a number of different languages.  SVN::Web's
interface is fully templated and localised, allowing you to change the
look-and-feel without writing any code; all strings in the interface
are stored in a separate file, to make localising to different
languages easier.
.IP "\(bu" 4
Rich log message linking.  You can configure SVN::Web to recognise
patterns in your log messages and automatically generate links to other
web based systems.  For example, if your log messages often refer to
tickets in your request tracking system:
.Sp
.Vb 1
\&  Reported in: t#1234
.Ve
.Sp
then SVN::Web can turn \f(CW\*(C`t#1234\*(C'\fR in to a link to that ticket.  SVN::Web
can also be configured to recognise e\-mail addresses, URLs, and anything
else you wish to make clickable.
.IP "\(bu" 4
Caching.  Internally, SVN::Web caches most of the data it gets from
the repository, helping to speed up repeated visits to the same page,
and reducing the impact on your repository server.
.IP "\(bu" 4
As \s-1SVK\s0 repositories are also Subversion repositories, you can do all of
the above with those too.
.PP
Additional actions can easily be added to the base set supported by the
core of SVN::Web.
.SH "CONFIGURATION"
.IX Header "CONFIGURATION"
Various aspects of SVN::Web's behaviour can be controlled through the
configuration file \fIconfig.yaml\fR.  See the \f(CW\*(C`YAML\*(C'\fR documentation for
information about writing \s-1YAML\s0 format files.
.SS "Version number"
.IX Subsection "Version number"
SVN::Web's configuration file must contain a version number.  If this
number is missing, or does not match the version number of the version
of SVN::Web that is being used then a fatal error will occur.
.PP
.Vb 1
\&  version: 0.53
.Ve
.SS "Repositories"
.IX Subsection "Repositories"
\fILocal and remote repositories\fR
.IX Subsection "Local and remote repositories"
.PP
SVN::Web can show information from one or more Subversion repositories.
These repositories do not have to be located on the same server.
.PP
Repositories are specified as a hash items under the \f(CW\*(C`repos\*(C'\fR key.  Each
key is the repository name (defined by you), the value is the repository's
\&\s-1URL.\s0
.PP
The three types of repository are specified like so.
.PP
.Vb 4
\&  repos:
\&    my_local_repo: \*(Aqfile:///path/to/local/repo\*(Aq
\&    my_http_repo: \*(Aqhttp://hostname/path\*(Aq
\&    my_svn_repo: \*(Aqsvn://hostname/path\*(Aq
.Ve
.PP
You may list as many repositories as you need.
.PP
For backwards compatibility, if a repository \s-1URL\s0 is specified without a
scheme, and starts with a \f(CW\*(C`/\*(C'\fR then the \f(CW\*(C`file:///\*(C'\fR scheme is assumed.  So
.PP
.Vb 2
\&  repos:
\&    my_local_repo: /path/to/local/repo
.Ve
.PP
is also valid.
.PP
\fILocal repositories under a single root\fR
.IX Subsection "Local repositories under a single root"
.PP
If you have multiple repositories that are all under a single parent
directory then use \f(CW\*(C`reposparent\*(C'\fR.
.PP
.Vb 1
\&  reposparent: \*(Aq/path/to/parent/directory\*(Aq
.Ve
.PP
If you set \f(CW\*(C`reposparent\*(C'\fR then you can selectively block certain repositories
from being browseable by specifying the \f(CW\*(C`block\*(C'\fR setting.
.PP
.Vb 3
\&  block:
\&    \- \*(Aqfirst_subdir_to_block\*(Aq
\&    \- \*(Aqsecond_subdir_to_block\*(Aq
.Ve
.PP
\&\f(CW\*(C`repos\*(C'\fR and \f(CW\*(C`reposparent\*(C'\fR are mutually exclusive.
.SS "Templates"
.IX Subsection "Templates"
SVN::Web's output is entirely template driven.  SVN::Web ships with a
number of different template styles, installed in to the \fItemplates/\fR
subdirectory of wherever you ran \f(CW\*(C`svnweb\-install\*(C'\fR.
.PP
The default templates are installed in \fItemplates/trac\fR.  These implement
a look and feel similar to the Trac (<http://www.edgewall.com/trac/>)
output.
.PP
To change to another set, use the \f(CW\*(C`templatedirs\*(C'\fR configuration directive.
.PP
For example, to use a set of templates that implement a much plainer look
and feel:
.PP
.Vb 2
\&  templatedirs:
\&    \- \*(Aqtemplate/plain\*(Aq
.Ve
.PP
Alternatively, if you have your own templates elsewhere you can
specify a full path to the templates.
.PP
.Vb 2
\&  templatedirs:
\&    \- \*(Aq/full/path/to/template/directory\*(Aq
.Ve
.PP
You can specify more than one directory in this list, and templates
will be searched for in each directory in turn.  This makes it possible for
actions that are not part of the core SVN::Web to ship their own templates,
and for you to override specific templates of your choice.
.PP
For example, if an action is using a template called \f(CW\*(C`view\*(C'\fR, and
\&\f(CW\*(C`templatedirs\*(C'\fR is configured like so:
.PP
.Vb 3
\&  templatedirs:
\&    \- \*(Aq/my/local/templates\*(Aq
\&    \- \*(Aq/templates/that/ship/with/svn\-web\*(Aq
.Ve
.PP
then \fI/my/local/templates/view\fR will first by checked.  If it exists
the search terminates and it's used.  If it does not exist then the search
continues in \fI/templates/that/ship/with/svn\-web\fR.
.PP
For more information about writing your own templates see
\&\*(L"\s-1ACTIONS, SUBCLASSES, AND URLS\*(R"\s0.
.SS "Languages"
.IX Subsection "Languages"
SVN::Web's interface is fully localised and ships with a number of
translations.  The default web interface allows the user to choose
from the available localisations at will, and the user's choice is
saved in a cookie.
.PP
\fILocalisation directories\fR
.IX Subsection "Localisation directories"
.PP
SVN::Web's localisation information is stored in files with names that
take the form \fI\f(CI\*(C`language\*(C'\fI.po\fR.  SVN::Web ships with a number
of localisations that are automatically installed with SVN::Web.
.PP
You can configure SVN::Web to search in additional directories for
localisation files.  There are typically three reasons for this.
.IP "1." 4
You wish to add support for a new language, and have placed your
localisation files in a different directory.
.IP "2." 4
You wish to change the localisation for a language that SVN::Web already
supports, and don't wish to overwrite the localisation file that SVN::Web
ships with.
.IP "3." 4
You have installed a third party SVN::Web::action, and this action
includes its own localisation files stored in a different directory.
.PP
Use the \f(CW\*(C`language_dirs\*(C'\fR configuration to specify all the \fIadditional\fR
directories that SVN::Web should search.  For example:
.PP
.Vb 3
\&  language_dirs:
\&    \- /path/to/my/local/translation
\&    \- /path/to/third/party/action/localisation
.Ve
.PP
If files in more than one directory contain the same localisation key
for the same language then the file in the directory that is listed
\&\fIlast\fR in this directive will be used.
.PP
\fIAvailable languages\fR
.IX Subsection "Available languages"
.PP
\&\f(CW\*(C`languages\*(C'\fR specifies the localisations that are considered
\&\fIavailable\fR.  This is a hash.  The keys are the basenames of
available localisation files, the values are the language name as it
should appear in the interface.  \f(CW\*(C`svnweb\-install\*(C'\fR will have set this
to a default value.
.PP
To find the available localisation files look in the \fIpo/\fR directory
that was created in the directory in which you ran \f(CW\*(C`svnweb\-install\*(C'\fR,
and in the directories listed in the \f(CW\*(C`language_dirs\*(C'\fR directive (if any).
.PP
For example, the default (as of SVN::Web 0.48) is:
.PP
.Vb 5
\&  languages:
\&    en: English
\&    fr: Fran&ccedil;ais
\&    zh_cn: Chinese (Simplified)
\&    zh_tw: Chinese (Traditional)
.Ve
.PP
\fIDefault language\fR
.IX Subsection "Default language"
.PP
\&\f(CW\*(C`default_language\*(C'\fR, specifies the language to use if the user has not
selected one.  The value for this option should be one of the keys
defined in \f(CW\*(C`languages\*(C'\fR.  For example;
.PP
.Vb 1
\&  default_language: fr
.Ve
.SS "Data cache"
.IX Subsection "Data cache"
SVN::Web can use any module implementing the Cache::Cache interface
to cache the data it retrieves from the repository.  Since this data does
not normally change this reduces the time it takes SVN::Web to generate
results.
.PP
This cache is \fBnot\fR enabled by default.
.PP
To enable the cache you must specify a class that implements a
Cache::Cache interface.  Cache::SizeAwareFileCache is a good
choice.
.PP
.Vb 2
\&  cache:
\&    class: Cache::SizeAwareFileCache
.Ve
.PP
The class' constructor may take various options.  Specify those under
the \f(CW\*(C`opts\*(C'\fR key.
.PP
For example, Cache::SizeAwareFileCache supports (among others)
options called \f(CW\*(C`max_size\*(C'\fR, \f(CW\*(C`cache_root\*(C'\fR, and \f(CW\*(C`directory_umask\*(C'\fR.
These could be configured like so:
.PP
.Vb 9
\&  # Use the SizeAwareFileCache.  Place it under /var/tmp instead of
\&  # the default (/tmp), use a custom umask, and limit the cache size to
\&  # 1MB
\&  cache:
\&    class: Cache::SizeAwareFileCache
\&    opts:
\&      max_size: 1000000
\&      cache_root: /var/tmp/svn\-web\-cache
\&      directory_umask: 077
.Ve
.PP
\&\fBNote:\fR The \f(CW\*(C`namespace\*(C'\fR option, if specified, is ignored, and is always
set to the name of the repository being accessed.
.SS "Template cache"
.IX Subsection "Template cache"
Template Toolkit can cache the results of template processing to make
future processing faster.
.PP
By default the cache is not enabled.  Use \f(CW\*(C`tt_compile_dir\*(C'\fR to enable it.
Set this directive to the name of a directory where the \s-1UID\s0 that SVN::Web is
being run as can create files.
.PP
For example:
.PP
.Vb 1
\&   tt_compile_dir: /var/tmp/tt\-cache
.Ve
.PP
A literal \f(CW\*(C`.\*(C'\fR and the \s-1UID\s0 of the process running SVN::Web will be appended
to this string to generate the final directory name.  For example, if
SVN::Web is being run under \s-1UID 80\s0 then the final directory name is
\&\fI/var/tmp/tt\-cache.80\fR.  Since the cached templates are always created
with mode 0600 this ensures that different users running SVN::Web can not
overwrite one another's cached templates.
.PP
This directive has no default value.  If it is not defined then no caching
will take place.
.SS "Log message filters"
.IX Subsection "Log message filters"
Many of the templates shipped with SVN::Web include log messages from
the repository.  It's likely that these log messages contain e\-mail
addresses, links to other web sites, and other rich information.
.PP
The Template::Toolkit makes it possible to filter these messages through
one or more plugins and/or filters that can recognise these and insert
additional markup to make them active.
.PP
In SVN::Web this is accomplished using a Template::Toolkit \s-1MACRO\s0 called
\&\f(CW\*(C`log_msg\*(C'\fR.  The \fItrac\fR templates define this in a template called
\&\fI_log_msg\fR, which is included in the relevant templates by this line:
.PP
.Vb 1
\&  [% PROCESS _log_msg %]
.Ve
.PP
You may redefine this macro yourself to filter log messages through
additional plugins depending on your requirements.  As a \s-1MACRO\s0 this
also has access to the template's variables, allowing you to easily
specify different filters depending on the values of different
variables (perhaps per-repository, or per-author filtering).  See the
\&\fI_log_msg\fR template included with this distribution for more details.
.SS "Time and date formatting"
.IX Subsection "Time and date formatting"
There are a number of places in the web interface where SVN::Web will
display a timestamp from Subversion.
.PP
Internally, Subversion stores times in \s-1UTC. \s0 You may wish to show them in
your local timezone (or some other timezone).  You may also wish to change
the formatting of the timestamp.
.PP
To do this use the \f(CW\*(C`timezone\*(C'\fR and \f(CW\*(C`timedate_format\*(C'\fR configuration options.
.PP
\&\f(CW\*(C`timezone\*(C'\fR takes one of three settings.
.IP "1." 4
If not set, or set to the empty string, SVN::Web will show all times in
\&\s-1UTC. \s0 This is the default behaviour.
.IP "2." 4
If set to the string \f(CW\*(C`local\*(C'\fR then SVN::Web will adjust all timestamps to
the web server's local timezone (which may not be the same timezone as
the server that hosts the repository).
.IP "3." 4
If set to a timezone name, such as \f(CW\*(C`BST\*(C'\fR or \f(CW\*(C`EST\*(C'\fR, then SVN::Web will
adjust all timestamps to that timezone.
.PP
When displaying timestamps SVN::Web uses the \s-1POSIX\s0 \f(CW\*(C`strftime()\*(C'\fR
function.  You can change the format string that is provided, thereby
changing how the timestamp is formatted.  Use the \f(CW\*(C`timedate_format\*(C'\fR
configuration directive for this.
.PP
The default value is:
.PP
.Vb 1
\&  timedate_format: \*(Aq%Y/%m/%d %H:%M:%S\*(Aq
.Ve
.PP
Using this format, a quarter past one in the afternoon on the 15th of
May 2006 would appear as:
.PP
.Vb 1
\&  2006/05/15 13:15:00
.Ve
.PP
If instead that was:
.PP
.Vb 1
\&  timedate_format: \*(Aq%a. %b %d, %l:%M%p\*(Aq
.Ve
.PP
then the same timestamp would appear as:
.PP
.Vb 1
\&  Mon. May 15, 1:15pm
.Ve
.PP
Note that \fIstrftime\fR\|(3) on different operating systems supports different
format specifiers, so consult your system's \fIstrftime\fR\|(3) manual page to
see which specifiers are available.
.SS "Actions, action classes, and action options"
.IX Subsection "Actions, action classes, and action options"
Each action that SVN::Web can carry out is implemented as a class (see
\&\*(L"\s-1ACTIONS, SUBCLASSES, AND URLS\*(R"\s0 for more).  You can specify your own
class for a particular action.  This lets you implement your own actions,
or override the behaviour of existing actions.
.PP
The complete list of actions is listed in the \f(CW\*(C`actions\*(C'\fR configuration
directive.
.PP
If you delete items from this list then the corresponding action becomes
unavailable.  For example, if you would like to prevent people from retrieving
an \s-1RSS\s0 feed of changes, just delete the \f(CW\*(C`\- rss\*(C'\fR entry from the list.
.PP
To provide your own behaviour for standard actions just specify a
different value for the \f(CW\*(C`class\*(C'\fR key.  For example, to specify your
own class that implements the \f(CW\*(C`view\*(C'\fR action;
.PP
.Vb 5
\&  actions:
\&    ...
\&    view:
\&      class: My::View::Class
\&    ...
.Ve
.PP
If you wish to implement your own action, give the action a name, add
it to the \f(CW\*(C`actions\*(C'\fR list, and then specify the class that carries out
the action.
.PP
For example, SVN::Web currently provides no action that generates \s-1ATOM\s0
feeds.  If you implement this, you would write:
.PP
.Vb 5
\&  actions:
\&    ...
\&    atom:
\&      class: My::Class::That::Implements::Atom
\&    ...
.Ve
.PP
Please feel free to submit any classes that implement additional
functionality back to the maintainers, so that they can be included in
the distribution.
.PP
Actions may have configurable options specified in \fIconfig.yaml\fR under
the \f(CW\*(C`opts\*(C'\fR key.  Continuing the \f(CW\*(C`annotate\*(C'\fR example, the action may be
written to provide basic output by default, but feature a \f(CW\*(C`verbose\*(C'\fR
flag that you can enable globally.  That would be configured like so:
.PP
.Vb 7
\&  actions:
\&    ...
\&    annotate:
\&      class: My::Class::That::Implements::Annotate
\&      opts:
\&        verbose: 1
\&    ...
.Ve
.PP
The documentation for each action should explain in more detail how it
should be configured.  See SVN::Web::action for more information
about writing actions.
.PP
If an action is listed in \f(CW\*(C`actions\*(C'\fR and there is no corresponding
\&\f(CW\*(C`class\*(C'\fR directive then SVN::Web takes the action name, converts the
first character to uppercase, and then looks for an
\&\f(CW\*(C`SVN::Web::<Action>\*(C'\fR package.
.SS "Action menu configuration"
.IX Subsection "Action menu configuration"
In the user interface the \f(CW\*(C`action menu\*(C'\fR is a list of actions that are
valid in the current context.  This menu is built up programmatically
from additional metadata about each action included in the config file.
.PP
The metadata is written as a hash, with each key corresponding to a
particular piece of metadata.  The hash is rooted at the \f(CW\*(C`action_menu\*(C'\fR
key.
.PP
A worked example may prove instructive.  Here is the default entry for
SVN::Web::RSS.  This shows all the valid keys under \f(CW\*(C`action_menu\*(C'\fR.
.PP
.Vb 9
\&  rss:
\&    class: SVN::Web::RSS
\&    action_menu:
\&      show:
\&        \- file
\&        \- directory
\&      link_text: (rss)
\&      head_only: 1
\&      icon: /css/trac/feed\-icon\-16x16.png
.Ve
.PP
The keys, and their meanings, are:
.IP "show" 4
.IX Item "show"
The contexts in which this action should appear in the action menu.  Each
SVN::Web action produces a result in a particular context.  The valid
contexts are:
.RS 4
.IP "file" 4
.IX Item "file"
The action is acting on a single file.  E.g., SVN::Web::View or
SVN::Web::Blame.
.IP "directory" 4
.IX Item "directory"
The action is acting on a single directory.  E.g., SVN::Web::Browse.
.IP "revision" 4
.IX Item "revision"
The action is acting on a single revision.  E.g., SVN::Web::Revision.
.RE
.RS 4
.Sp
Valid values are any of the three items above, plus the special value
\&\f(CW\*(C`global\*(C'\fR, indicating that the action should always appear in the
action menu.
.Sp
In this example, the \f(CW\*(C`rss\*(C'\fR action is available when browsing directories
and viewing files.  It makes no sense to make the \s-1RSS\s0 action available
when browsing an individual revision, so that is not listed as a valid
context.
.RE
.IP "link_text" 4
.IX Item "link_text"
The text that should appear in the action menu for this item.  This
text is passed through the localisation system.
.IP "head_only" 4
.IX Item "head_only"
A boolean that indicates whether the action is always available in the
listed contexts, or whether it should only appear when viewing the
\&\s-1HEAD\s0 revision in a particular context.
.Sp
In this example it makes no sense to clamp the \s-1RSS\s0 feed to a particular
revision, so it is flagged as only being available when looking at the
\&\s-1HEAD\s0 of a file or directory.
.IP "icon" 4
.IX Item "icon"
The (relative) path to the icon to use for this menu item (if any).
.PP
For comparison, this is the recommended setting for SVN::Web::Checkout.
.PP
.Vb 6
\&  checkout:
\&    class: SVN::Web::Checkout
\&    action_menu:
\&      show:
\&        \- file
\&      link_text: (checkout)
.Ve
.PP
This action is only valid when viewing files \*(-- checking out a directory
does not make sense.  A file can be checked out at any revision, so
\&\f(CW\*(C`head_only\*(C'\fR can be omitted (\f(CW\*(C`head_only: 0\*(C'\fR would have the same effect).
And there is no icon for this action.
.PP
For details of how this information is used see the
\&\fItemplate/trac/_action_menu\fR template.
.PP
The \f(CW\*(C`action_menu\*(C'\fR metadata is optional.  Some actions might not merit
a menu option (e.g., \f(CW\*(C`diff\*(C'\fR or \f(CW\*(C`revision\*(C'\fR), so those actions should
not have \f(CW\*(C`action_menu\*(C'\fR metadata.
.SS "\s-1CGI\s0 class"
.IX Subsection "CGI class"
SVN::Web can use a custom \s-1CGI\s0 class.  By default SVN::Web will use
CGI::Fast if it is installed, and fallback to using \s-1CGI\s0 otherwise.
.PP
Of course, if you have your own class that implements the \s-1CGI\s0 interface
you may specify it here too.
.PP
.Vb 1
\&  cgi_class: \*(AqMy::CGI::Subclass\*(Aq
.Ve
.SH "ACTIONS, SUBCLASSES, AND URLS"
.IX Header "ACTIONS, SUBCLASSES, AND URLS"
SVN::Web URLs are broken down in to four components.
.PP
.Vb 1
\&  .../index.cgi/<repo>/<action>/<path>?<arguments>
.Ve
.PP
or
.PP
.Vb 1
\&  .../apache\-handler/<repo>/<action>/<path>?<arguments>
.Ve
.IP "\fIrepo\fR" 4
.IX Item "repo"
The repository the action will be performed on.  SVN::Web can be
configured to operate on multiple Subversion repositories.
.IP "\fIaction\fR" 4
.IX Item "action"
The action that will be run.
.IP "\fIpath\fR" 4
.IX Item "path"
The path within the <repository> that the action is performed on.
.IP "\fIarguments\fR" 4
.IX Item "arguments"
Any arguments that control the behaviour of the \fIaction\fR.
.PP
Each action is implemented as a Perl module.  By convention, each module
carries out whatever processing is required by the action, and returns a
reference to a hash of data that is used to fill out a \f(CW\*(C`Template::Toolkit\*(C'\fR
template that displays the action's results.
.PP
The standard actions, and the Perl modules that implement them, are:
.IP "\fIblame\fR, \fISVN::Web::Blame\fR" 4
.IX Item "blame, SVN::Web::Blame"
Shows the blame (also called annotation) information for a file.  On a
per line basis it shows the revision in which that line was last changed
and the user that committed the change.
.IP "\fIbrowse\fR, \fISVN::Web::Browse\fR" 4
.IX Item "browse, SVN::Web::Browse"
Shows the files and directories in a given repository path.  This is
the default command if no path is specified in the \s-1URL.\s0
.IP "\fIcheckout\fR, \fISVN::Web::Checkout\fR" 4
.IX Item "checkout, SVN::Web::Checkout"
Returns the raw data for the file at a given repository path and revision.
.IP "\fIdiff\fR, \fISVN::Web::Diff\fR" 4
.IX Item "diff, SVN::Web::Diff"
Shows the difference between two revisions of the same file.
.IP "\fIlist\fR, \fISVN::Web::List\fR" 4
.IX Item "list, SVN::Web::List"
Lists the available Subversion repositories.  This is the default
command if no repository is specified in the \s-1URL.\s0
.IP "\fIlog\fR, \fISVN::Web::Log\fR" 4
.IX Item "log, SVN::Web::Log"
Shows log information (commit messages) for a given repository path.
.IP "\fIrevision\fR, \fISVN::Web::Revision\fR" 4
.IX Item "revision, SVN::Web::Revision"
Shows information about a specific repository revision.
.IP "\fIrss\fR, \fISVN::Web::RSS\fR" 4
.IX Item "rss, SVN::Web::RSS"
Generates an \s-1RSS\s0 feed of changes to the repository path.
.IP "\fIview\fR, \fISVN::Web::View\fR" 4
.IX Item "view, SVN::Web::View"
Shows the commit message and file contents for a specific repository path
and revision.
.PP
See the documentation for each of these modules for more information
about the data that they provide to each template, and for information
about customising the templates used for each module.
.SH "WEB SERVERS"
.IX Header "WEB SERVERS"
This section explains how to configure some common webservers to run
SVN::Web.  In all cases, \f(CW\*(C`/path/to/svnweb\*(C'\fR in the examples is the
directory you ran \f(CW\*(C`svnweb\-install\*(C'\fR in, and contains \fIconfig.yaml\fR.
.PP
SVN::Web now uses Plack to provide connectivity to the web server.
Previously a cgi, stand alone, fastcgi, mod_perl1 and a mod_perl2
interface was provided as part of this software. All of which have been
removed and replaced by Plack. In doing so, Plack now will connect
SVN::Web to all of the above, plus \s-1PSGI,\s0 nginx_perl and anything else
cooked up in the future.
.PP
If you've configured a web server that isn't listed here for SVN::Web,
please send in the instructions so they can be included in a future
release.
.SS "plackup"
.IX Subsection "plackup"
\&\f(CW\*(C`plackups\*(C'\fR is a simple web server that can run SVN::Web stand alone,
and is included and installed by Plack.  It may be all you need to
productively use SVN::Web without needing to install a larger server.
To use it, run:
.PP
.Vb 1
\&  plackup SVN\-Web.psgi
.Ve
.PP
See \f(CW\*(C`perldoc plackup\*(C'\fR for details about additional options you can
use.
.SS "Apache as \s-1CGI \s0(not recommended)"
.IX Subsection "Apache as CGI (not recommended)"
See Plack::Handler::CGI
.SS "Apache with mod_perl or mod_perl2"
.IX Subsection "Apache with mod_perl or mod_perl2"
See Plack::Handler::Apache1 or Plack::Handler::Apache2 respectively.
.SS "Apache with FastCGI"
.IX Subsection "Apache with FastCGI"
See Plack::Handler::FCGI
.SS "\s-1IIS\s0"
.IX Subsection "IIS"
For now this is probably broken.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
SVN::Web::action, \fIsvnweb\-install\fR\|(1), \fIplackup\fR\|(1), Plack
.SH "BUGS"
.IX Header "BUGS"
Please report any bugs or feature requests to
\&\f(CW\*(C`bug\-svn\-web@rt.cpan.org\*(C'\fR, or through the web interface at
<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=SVN\-Web>.
I will be notified, and then you'll automatically be notified of progress on
your bug as I make changes.
.SH "AUTHORS"
.IX Header "AUTHORS"
Chia-liang Kao \f(CW\*(C`<clkao@clkao.org>\*(C'\fR
.PP
Nik Clayton \f(CW\*(C`<nik@FreeBSD.org>\*(C'\fR
.PP
Dean Hamstead \f(CW\*(C`<dean@fragfest.com.au>\*(C'\fR
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2003\-2004 by Chia-liang Kao \f(CW\*(C`<clkao@clkao.org>\*(C'\fR.
.PP
Copyright 2005\-2007 by Nik Clayton \f(CW\*(C`<nik@FreeBSD.org>\*(C'\fR.
.PP
Copyright 2012 by Dean Hamstead \f(CW\*(C`<dean@fragfest.com.au>\*(C'\fR.
.PP
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
.PP
See <http://www.perl.com/perl/misc/Artistic.html>