Provided by: libsvn-web-perl_0.63-3.1_all bug

NAME

       SVN::Web - Subversion repository web frontend

SYNOPSIS

       If you are upgrading an existing SVN::Web installation then please see UPDATING.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.

       To get started with SVN::Web.

       1.  Create a directory for SVN::Web's configuration files, templates, stylesheets, and
           other data.

             mkdir svnweb

       2.  Run "svnweb-install" in this directory to configure the environment.

             cd svnweb
             svnweb-install

       3.  Edit the file config.yaml that's been created, and add the following two lines:

             repos:
               test: 'file:///path/to/repo'

           "file:///path/to/repo" should be the URL for an existing Subversion repository.

       4.  Either configure your web server (see "WEB SERVERS") to use SVN::Web, or run with
           "plackup" to start a simple web server for testing.

             plackup -Ilib/ ./SVN-Web.psgi

       5.  Point your web browser at the correct URL to browse your repository.  If you've run
           "plackup" then this is <http://localhost:5000/>.

       See <https://github.com/djzort/SVN-Web> for the SVN::Web source code.

DESCRIPTION

       SVN::Web provides a web interface to subversion repositories. It's features include:

       •   Viewing multiple Subversion repositories.  SVN::Web is a full Subversion client, so
           you can access repositories on the local disk (with the "file:///" scheme) or that are
           remotely accessible using the "http://" and "svn://" schemes.

       •   Browsing every revision of the repository.

       •   Viewing the contents of files in the repository at any revision.

       •   Viewing diffs of arbitrary revisions of any file.  Diffs can be viewed as plain
           unified diffs, or HTML diffs that use colour to more easily show what's changed.

       •   Viewing the revision log of files and directories, see what was changed when, by who.

       •   Viewing the blame/annotation details of any file.

       •   Generating RSS feeds of commits, down to the granularity of individual files.  The RSS
           feeds are auto-discoverable in modern web browsers.

       •   Viewing everything that was changed in a revision, and step through revisions one at a
           time, viewing the history of the repository.

       •   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.

       •   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:

             Reported in: t#1234

           then SVN::Web can turn "t#1234" 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.

       •   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.

       •   As SVK repositories are also Subversion repositories, you can do all of the above with
           those too.

       Additional actions can easily be added to the base set supported by the core of SVN::Web.

CONFIGURATION

       Various aspects of SVN::Web's behaviour can be controlled through the configuration file
       config.yaml.  See the "YAML" documentation for information about writing YAML format
       files.

   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.

         version: 0.53

   Repositories
       Local and remote repositories

       SVN::Web can show information from one or more Subversion repositories.  These
       repositories do not have to be located on the same server.

       Repositories are specified as a hash items under the "repos" key.  Each key is the
       repository name (defined by you), the value is the repository's URL.

       The three types of repository are specified like so.

         repos:
           my_local_repo: 'file:///path/to/local/repo'
           my_http_repo: 'http://hostname/path'
           my_svn_repo: 'svn://hostname/path'

       You may list as many repositories as you need.

       For backwards compatibility, if a repository URL is specified without a scheme, and starts
       with a "/" then the "file:///" scheme is assumed.  So

         repos:
           my_local_repo: /path/to/local/repo

       is also valid.

       Local repositories under a single root

       If you have multiple repositories that are all under a single parent directory then use
       "reposparent".

         reposparent: '/path/to/parent/directory'

       If you set "reposparent" then you can selectively block certain repositories from being
       browseable by specifying the "block" setting.

         block:
           - 'first_subdir_to_block'
           - 'second_subdir_to_block'

       "repos" and "reposparent" are mutually exclusive.

   Templates
       SVN::Web's output is entirely template driven.  SVN::Web ships with a number of different
       template styles, installed in to the templates/ subdirectory of wherever you ran
       "svnweb-install".

       The default templates are installed in templates/trac.  These implement a look and feel
       similar to the Trac (<http://www.edgewall.com/trac/>) output.

       To change to another set, use the "templatedirs" configuration directive.

       For example, to use a set of templates that implement a much plainer look and feel:

         templatedirs:
           - 'template/plain'

       Alternatively, if you have your own templates elsewhere you can specify a full path to the
       templates.

         templatedirs:
           - '/full/path/to/template/directory'

       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.

       For example, if an action is using a template called "view", and "templatedirs" is
       configured like so:

         templatedirs:
           - '/my/local/templates'
           - '/templates/that/ship/with/svn-web'

       then /my/local/templates/view will first by checked.  If it exists the search terminates
       and it's used.  If it does not exist then the search continues in
       /templates/that/ship/with/svn-web.

       For more information about writing your own templates see "ACTIONS, SUBCLASSES, AND URLS".

   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.

       Localisation directories

       SVN::Web's localisation information is stored in files with names that take the form
       "language".po.  SVN::Web ships with a number of localisations that are automatically
       installed with SVN::Web.

       You can configure SVN::Web to search in additional directories for localisation files.
       There are typically three reasons for this.

       1.  You wish to add support for a new language, and have placed your localisation files in
           a different directory.

       2.  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.

       3.  You have installed a third party SVN::Web::action, and this action includes its own
           localisation files stored in a different directory.

       Use the "language_dirs" configuration to specify all the additional directories that
       SVN::Web should search.  For example:

         language_dirs:
           - /path/to/my/local/translation
           - /path/to/third/party/action/localisation

       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 last in this directive will be
       used.

       Available languages

       "languages" specifies the localisations that are considered available.  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.  "svnweb-install" will have set this to a
       default value.

       To find the available localisation files look in the po/ directory that was created in the
       directory in which you ran "svnweb-install", and in the directories listed in the
       "language_dirs" directive (if any).

       For example, the default (as of SVN::Web 0.48) is:

         languages:
           en: English
           fr: Fran&ccedil;ais
           zh_cn: Chinese (Simplified)
           zh_tw: Chinese (Traditional)

       Default language

       "default_language", 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 "languages".  For example;

         default_language: fr

   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.

       This cache is not enabled by default.

       To enable the cache you must specify a class that implements a Cache::Cache interface.
       Cache::SizeAwareFileCache is a good choice.

         cache:
           class: Cache::SizeAwareFileCache

       The class' constructor may take various options.  Specify those under the "opts" key.

       For example, Cache::SizeAwareFileCache supports (among others) options called "max_size",
       "cache_root", and "directory_umask".  These could be configured like so:

         # 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

       Note: The "namespace" option, if specified, is ignored, and is always set to the name of
       the repository being accessed.

   Template cache
       Template Toolkit can cache the results of template processing to make future processing
       faster.

       By default the cache is not enabled.  Use "tt_compile_dir" to enable it.  Set this
       directive to the name of a directory where the UID that SVN::Web is being run as can
       create files.

       For example:

          tt_compile_dir: /var/tmp/tt-cache

       A literal "." and the UID 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 UID 80
       then the final directory name is /var/tmp/tt-cache.80.  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.

       This directive has no default value.  If it is not defined then no caching will take
       place.

   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.

       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.

       In SVN::Web this is accomplished using a Template::Toolkit MACRO called "log_msg".  The
       trac templates define this in a template called _log_msg, which is included in the
       relevant templates by this line:

         [% PROCESS _log_msg %]

       You may redefine this macro yourself to filter log messages through additional plugins
       depending on your requirements.  As a MACRO 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 _log_msg
       template included with this distribution for more details.

   Time and date formatting
       There are a number of places in the web interface where SVN::Web will display a timestamp
       from Subversion.

       Internally, Subversion stores times in UTC.  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.

       To do this use the "timezone" and "timedate_format" configuration options.

       "timezone" takes one of three settings.

       1.  If not set, or set to the empty string, SVN::Web will show all times in UTC.  This is
           the default behaviour.

       2.  If set to the string "local" 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).

       3.  If set to a timezone name, such as "BST" or "EST", then SVN::Web will adjust all
           timestamps to that timezone.

       When displaying timestamps SVN::Web uses the POSIX "strftime()" function.  You can change
       the format string that is provided, thereby changing how the timestamp is formatted.  Use
       the "timedate_format" configuration directive for this.

       The default value is:

         timedate_format: '%Y/%m/%d %H:%M:%S'

       Using this format, a quarter past one in the afternoon on the 15th of May 2006 would
       appear as:

         2006/05/15 13:15:00

       If instead that was:

         timedate_format: '%a. %b %d, %l:%M%p'

       then the same timestamp would appear as:

         Mon. May 15, 1:15pm

       Note that strftime(3) on different operating systems supports different format specifiers,
       so consult your system's strftime(3) manual page to see which specifiers are available.

   Actions, action classes, and action options
       Each action that SVN::Web can carry out is implemented as a class (see "ACTIONS,
       SUBCLASSES, AND URLS" 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.

       The complete list of actions is listed in the "actions" configuration directive.

       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 RSS feed of changes, just
       delete the "- rss" entry from the list.

       To provide your own behaviour for standard actions just specify a different value for the
       "class" key.  For example, to specify your own class that implements the "view" action;

         actions:
           ...
           view:
             class: My::View::Class
           ...

       If you wish to implement your own action, give the action a name, add it to the "actions"
       list, and then specify the class that carries out the action.

       For example, SVN::Web currently provides no action that generates ATOM feeds.  If you
       implement this, you would write:

         actions:
           ...
           atom:
             class: My::Class::That::Implements::Atom
           ...

       Please feel free to submit any classes that implement additional functionality back to the
       maintainers, so that they can be included in the distribution.

       Actions may have configurable options specified in config.yaml under the "opts" key.
       Continuing the "annotate" example, the action may be written to provide basic output by
       default, but feature a "verbose" flag that you can enable globally.  That would be
       configured like so:

         actions:
           ...
           annotate:
             class: My::Class::That::Implements::Annotate
             opts:
               verbose: 1
           ...

       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.

       If an action is listed in "actions" and there is no corresponding "class" directive then
       SVN::Web takes the action name, converts the first character to uppercase, and then looks
       for an "SVN::Web::<Action>" package.

   Action menu configuration
       In the user interface the "action menu" 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.

       The metadata is written as a hash, with each key corresponding to a particular piece of
       metadata.  The hash is rooted at the "action_menu" key.

       A worked example may prove instructive.  Here is the default entry for SVN::Web::RSS.
       This shows all the valid keys under "action_menu".

         rss:
           class: SVN::Web::RSS
           action_menu:
             show:
               - file
               - directory
             link_text: (rss)
             head_only: 1
             icon: /css/trac/feed-icon-16x16.png

       The keys, and their meanings, are:

       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:

           file
               The action is acting on a single file.  E.g., SVN::Web::View or SVN::Web::Blame.

           directory
               The action is acting on a single directory.  E.g., SVN::Web::Browse.

           revision
               The action is acting on a single revision.  E.g., SVN::Web::Revision.

           Valid values are any of the three items above, plus the special value "global",
           indicating that the action should always appear in the action menu.

           In this example, the "rss" action is available when browsing directories and viewing
           files.  It makes no sense to make the RSS action available when browsing an individual
           revision, so that is not listed as a valid context.

       link_text
           The text that should appear in the action menu for this item.  This text is passed
           through the localisation system.

       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 HEAD revision in a
           particular context.

           In this example it makes no sense to clamp the RSS feed to a particular revision, so
           it is flagged as only being available when looking at the HEAD of a file or directory.

       icon
           The (relative) path to the icon to use for this menu item (if any).

       For comparison, this is the recommended setting for SVN::Web::Checkout.

         checkout:
           class: SVN::Web::Checkout
           action_menu:
             show:
               - file
             link_text: (checkout)

       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 "head_only" can be omitted
       ("head_only: 0" would have the same effect).  And there is no icon for this action.

       For details of how this information is used see the template/trac/_action_menu template.

       The "action_menu" metadata is optional.  Some actions might not merit a menu option (e.g.,
       "diff" or "revision"), so those actions should not have "action_menu" metadata.

   CGI class
       SVN::Web can use a custom CGI class.  By default SVN::Web will use CGI::Fast if it is
       installed, and fallback to using CGI otherwise.

       Of course, if you have your own class that implements the CGI interface you may specify it
       here too.

         cgi_class: 'My::CGI::Subclass'

ACTIONS, SUBCLASSES, AND URLS

       SVN::Web URLs are broken down in to four components.

         .../index.cgi/<repo>/<action>/<path>?<arguments>

       or

         .../apache-handler/<repo>/<action>/<path>?<arguments>

       repo
           The repository the action will be performed on.  SVN::Web can be configured to operate
           on multiple Subversion repositories.

       action
           The action that will be run.

       path
           The path within the <repository> that the action is performed on.

       arguments
           Any arguments that control the behaviour of the action.

       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 "Template::Toolkit" template that displays the action's
       results.

       The standard actions, and the Perl modules that implement them, are:

       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.

       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 URL.

       checkout, SVN::Web::Checkout
           Returns the raw data for the file at a given repository path and revision.

       diff, SVN::Web::Diff
           Shows the difference between two revisions of the same file.

       list, SVN::Web::List
           Lists the available Subversion repositories.  This is the default command if no
           repository is specified in the URL.

       log, SVN::Web::Log
           Shows log information (commit messages) for a given repository path.

       revision, SVN::Web::Revision
           Shows information about a specific repository revision.

       rss, SVN::Web::RSS
           Generates an RSS feed of changes to the repository path.

       view, SVN::Web::View
           Shows the commit message and file contents for a specific repository path and
           revision.

       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.

WEB SERVERS

       This section explains how to configure some common webservers to run SVN::Web.  In all
       cases, "/path/to/svnweb" in the examples is the directory you ran "svnweb-install" in, and
       contains config.yaml.

       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 PSGI, nginx_perl and anything else cooked
       up in the future.

       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.

   plackup
       "plackups" 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:

         plackup SVN-Web.psgi

       See "perldoc plackup" for details about additional options you can use.

   Apache as CGI (not recommended)
       See Plack::Handler::CGI

   Apache with mod_perl or mod_perl2
       See Plack::Handler::Apache1 or Plack::Handler::Apache2 respectively.

   Apache with FastCGI
       See Plack::Handler::FCGI

   IIS
       For now this is probably broken.

SEE ALSO

       SVN::Web::action, svnweb-install(1), plackup(1), Plack

BUGS

       Please report any bugs or feature requests to "bug-svn-web@rt.cpan.org", 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.

AUTHORS

       Chia-liang Kao "<clkao@clkao.org>"

       Nik Clayton "<nik@FreeBSD.org>"

       Dean Hamstead "<dean@fragfest.com.au>"

COPYRIGHT

       Copyright 2003-2004 by Chia-liang Kao "<clkao@clkao.org>".

       Copyright 2005-2007 by Nik Clayton "<nik@FreeBSD.org>".

       Copyright 2012 by Dean Hamstead "<dean@fragfest.com.au>".

       This program is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.

       See <http://www.perl.com/perl/misc/Artistic.html>