csvn-ui.rc(5) Config File
/etc/csvn-ui.rc – cSvn-ui CGI Script configuration file describes the Subversion™ repositories that should be displayed on the client side.
Table of Contents
File Format
/etc/csvn-ui.rc is a regular text file created by user to present Subversion repositories. This file reads by cscnd(8) daemon and converts to binary form for cSvn-ui CGI script. Binary format allows to minimize the time needed for complete HTTP responses.
The configuration file consists of a set of variable or repository declarations also configuration file can contains section of repository descriptions. The C/C++ comments are available:
/****************************
Apache's SVN repositories:
*/
home-page = "https://svn.apache.org/";
repo 'subversion' {
owner = "Apache";
description = "Source repository of the Subversion.";
checkout-prefix-readonly = 'https://svn.apache.org/repos/asf';
}
section "Other Repositories" {
repo 'other-repository' {
. . .
}
. . .
}
Data Types
Configuration file assumes three types of variables.
int – integer constants. Example declaration:
true = 1;
string – string constants. Example declaration:
name = "Apache Subversion";
path – path constants. Example declaration:
path = '/etc/csvn-ui.rc';
Reserved Variables
There is a set of variable names used by cSvn-ui CGI Script.
svn-utc-offset
The integer or string value of UTC offset on the SVN server where repositories are published. For example:
svn-utc-offset = +0300; /* Europe/Moscow time zone */
repo-root
The name of directory where some repository is placed related to svn repositories root directory. For example:
repo-root = 'tools';
checkout-prefix-readonly
The checkout prefix for readonly access to the repository. The value of this variable should has path type without leadinfg dir-separator. Example declaration:
checkout-prefix-readonly = 'svn://example.com';
checkout-prefix-readonly = 'https://svn.example.com/svn';
Please note that svn protocol works match quickly.
checkout-prefix
The checkout prefix for readwrite access to the repository. The value of this variable should has path type without leadinfg dir-separator. Example declaration:
checkout-prefix = 'svn+ssh://svn@example.com';
This means the access on behalf svn system user.
branches
The name of directory where branches is places. Default value is 'branches'.
trunk
The name of the trunk directory. Default value is 'trunks'.
tags
The name of directory where tags are saved. Default value is 'tags'. Example declarations of directory names:
branches = 'branches';
trunk = 'trunk';
tags = 'tags';
snapshots
The extension of snapshot tarballs. Default value: 'tar.xz'. Example declaration:
snapshots = 'tar.xz';
Currently snapshot variable is not used by cSvn-ui CGI Script.
css
The full name of the CSS style sheet relative to the directory where cSvn-ui CGI Sctipt is installed. Example declaration:
css = '/.csvn/css/csvn.css';
logo
Url which specifies the source of an image which will be used as a logo (i.e right banner) on cSvn-ui pages. Default value: '/.csvn/pixmaps/csvn-banner-280x280.png'. The path to the logo also should be set relative to the directory where cSvn-ui CGI Script is installed. Example declaration:
logo = '/.csvn/pixmaps/csvn-banner-280x280.png';
logo-alt
The string used in HTML as a 'alt' property of the right banner <img> tag. Default value: "Example.org". Example declaration:
logo-alt = "Example.org";
logo-link
The string used in HTML as a 'href' property of the right banner image link <a> tag. Default value: "https://example.org". Example declaration:
logo-link = "https://example.org";
main-menu-logo
Url which specifies the source of an image which will be used as a logo of the main menu item on cSvn-ui pages. Default value: '/.csvn/pixmaps/logo/SVN-logo-white-744x744.svg'. The path to the main-menu-logo also should be set relative to the directory where cSvn-ui CGI Script is installed. Example declaration:
main-menu-logo = '/.csvn/pixmaps/logo/SVN-logo-white-744x744.svg';
favicon-path
The directory name of the favicon.ico file without leadind dir-separator. Default value: '/.csvn/pixmaps/favicon'. Example declaration:
favicon-path = '/.csvn/pixmaps/favicon';
This directory name used for finding additional images declared in the HTML header of all cSvn-ui pages.
syntax-highlight-css
The base name of the CSS style sheet file used for syntax highlighting. Default value: '_csvn.css'. Example declaration:
syntax-highlight-css = '_csvn.css';
cSvn-ui CGI Script uses highlight.js installed into
/.csvn/.engines/highlight/${hljs-version}/{css,js} directories where the default
_csvn.css file is palced too.
header
The content of the file specified with this option will be included verbatim at the top of all pages. Default value: '/.csvn/html/header.html'.
footer
The content of the file specified with this option will be included verbatim at the bottom of all pages. Default value: '/.csvn/html/footer.html'. Examle of the header and the footer declarations:
header = '/.csvn/html/header.html';
footer = '/.csvn/html/footer.html';
The header and the footer files used as template where cSvn-ui CGI Script substitute
placeholders such as ${variable-name} by their values. For example the ${css} placeholder
will be replaced by the value of css variable declared in the /etc/csvn-ui.rc config file.
page-size
The string or int variable which set the length of the repositories list or logs that shown in one page by the cSvn-ui CGI Script. Default value: 200. Example declaration:
page-size = 50; /* 10 ... 200 may be string or integer. Default value is page-size = 200 */
owner
The string variable used in the HTML header of all cSvn-ui pages and also in the Owner colon of the repository list. Default value: "Andrey V.Kosteltsev".
author
The string variable used in the HTML header of all cSvn-ui pages. Default value: "Andrey V.Kosteltsev". Example declarations of the owner and the author variables:
owner = "John Smith";
author = "John Smith";
title
The string variable used in the HTML header of all cSvn-ui pages as a page title. Default value: "SVN Repositories". Example declaration:
title = "Example.org SVN Repositories";
description
The string variable used in the HTML header of all cSvn-ui pages as a page description. Default value: "Subversion repositories hosted at Solar System, Earth". Example declaration:
description = "Subversion repositories hosted at example.org (St.-Petersburg)";
For a long description the value of this string variable can be splitted in the C-style by following way:
description = "Subversion repositories"
" hosted at example.org "
"(St.-Petersburg)";
keywords
The string variable contains space separated keywords used in the HTML header of all cSvn-ui pages as a page keywords. Default value: "cSvn repositories". Example declaration:
keywords = "cSvn-ui cSvn UI CGI Subversion Repositories scm SVN";
copyright-notice
The string variable used in the HTML footer of all cSvn-ui pages as a Copyright Notice. Default value: "By using any website materials you agree to indicate source.". Example declaration:
copyright-notice = "By using any materials you agree with ...";
copyright
The string variable used in the HTML footer of all cSvn-ui pages as a Copyright. Default value: "© 2020 Andrey V.Kosteltsev. All Rights Reserved.". Example declaration:
copyright = "© John Smith (explorer), 1580 - 1631.";
home-page
The URL of the home page of the project. Default value: "https://example.org". Example declaration:
home-page = "https://main-site-of-the-project.org";
Analytics variables:
analytic-links
The path to the file which contains meta tags with site ownership verificaton codes for engines such as Google Search Console or Yandex Webmaster. cSvn-ui CGI Script reads the file analytic-links in RAW format and includes it into <HEAD> tag of each HTML page. Example declaration:
analytic-links = '/analytics/links';
Where the file /analytics/links may contains HTML tags like follow:
<meta name="google-site-verification" content="..." />
The file name should be defined relative of the path where cSvn-ui CGI Script is installed. For example, if cSvn-ui CGI Script installed into /srv/www/htdocs/csvn directory and file name declared as /analytics/links then cSvn-ui CGI Script will try to read the file /srv/www/htdocs/csvn/analytics/links.
analytic-scripts
The path to the file which contains JavaScripts for engines such as Google Search Console or Yandex Webmaster. cSvn-ui CGI Script reads the file analytic-scripts in RAW format and includes it at the end of <HEAD> tag before </HEAD> entry of each HTML page. Example declaration:
analytic-scripts = '/analytics/scripts';
Where the file /analytics/scripts may contains code like follow:
<!-- Global site tag (gtag.js) - Google Analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'G-XXXXXXXXXX');
</script>
Please note that the <script> tags should be present in the /analytics/scripts because cSvn-ui CGI Script reads this file in RAW format and includes it as is.
The variables analytic-links and analytic-scripts should be declared on the global level of the /etc/csvn-ui.rc configuration file and cannot be overriden in a repository declaration.
Donation variables:
The cSvn-ui CGI Script provides the ability to create a custom donation dialogue. To do this, you need to create a set of three files: CSS, HTML, and JavaScript file for automation. You can add a donation dialogue for each repository separately, as well as for the entire list of repositories. To enable donation dialogue you have to set the value of donate variable to donate = 1:
donate
The integer variable used to enable or disable donation dialogue. Example declaration:
donate = 1;
donate-css
The name of file contains the stylesheet for donation modal dialogue. Example declaration:
donate-css = '/donations/donate.css';
donate-html
The name of file contains the HTML code of donation modal dialogue. Example declaration:
donate-html = '/donations/donate.html';
donate-js
The name of file contains the javascript code for donation modal dialogue automation. Example declaration:
donate-js = '/donations/donate.js';
cSvn-ui CGI Script includes these files at end of <BODY> tag just before the closing </BODY> tag. Unlike the others, the donate-html file should be no more than 8192 bytes in size due to the fact that this file is a template and the values of the following two variables are substituted into its body using placeholders ${donate-header} and ${donate-purpose}:
donate-header
The title of the donation modal dialogue defined in the donate-html file. Example declaration:
donate-header = "Donations";
donate-purpose
The donation purpose used as value of <input value="..."> tag property in payment form of systems such as PayPal or Yandex.Money. Also this value can be used as a header of modal dialogue content. Example declaration:
donate-purpose = "Support for our projects";
Donation dialogue can be defined for each repository separately or defined on global level. In the last case the dialogue header and payment purpose may be overriden in the body of a repository declaration like follow:
true = 1;
false = 0;
donate = true;
donate-css = '/donations/donate.css';
donate-html = '/donations/donate.html';
donate-js = '/donations/donate.js';
donate-header = "Donation";
donate-purpose = "Support our activities";
section "Tools" {
repo 'repo-path' {
. . .
donate-header = "Project Donation";
donate-purpose = "Support our Project";
. . .
}
}
To show the modal dialogue in javascript code donate-js the selector 'a.donate' should be used. For examle, like this:
var show = document.querySelector( "a.donate" );
/**************
Open Dialog:
*/
show.onclick = function() {
dialog.style.display = "block";
}
Where the variable dialog points to modal dialogue defined in the donate-html file.
Repository Declaration
The /etc/csvn-ui.rc config file should contains at least one repository declaration to be shown by the cSvn-ui CGI Script. When all expected variables declared in the global section the config file the repository declaration can be very simple:
repo 'tools' {
owner = "John Smith";
description = "John Smith's tools source code repository.";
}
The list of repositories can be splitted in several sections. The section has a name and can contains repository declarations only.
section "John Smith sources" {
repo 'tools' {
owner = "John Smith";
description = "John Smith's tools source code repository.";
}
repo 'examples' {
owner = "John Smith";
description = "John Smith's examples source code.";
}
}
Please note, repositories, unlike sections, do not have a name, but have a path to repository.
So if your repositories in the file system are stored in the /var/scm/svn directory, and the
tools repository is located in the /var/scm/svn/tools directory, then the path to the repository
is set relative to the /var/scm/svn directory as follows:
repo 'tools' {
owner = "John Smith";
description = "John Smith's tools source code repository.";
}
Working Example
As an example, we will give a working configuration file in which the cSvn-ui repository is presented.
svn-utc-offset = +0300;
checkout-prefix-readonly = 'svn://radix.pro';
checkout-prefix = 'svn+ssh://svn@radix.pro';
branches = 'branches';
trunk = 'trunk';
tags = 'tags';
snapshots = 'tar.xz';
css = '/.csvn/css/csvn.css';
logo = '/.csvn/pixmaps/csvn-banner-280x280.png';
logo-alt = "Radix.pro";
logo-link = "https://radix.pro";
main-menu-logo = '/.csvn/pixmaps/logo/SVN-logo-white-744x744.svg';
favicon-path = '/.csvn/pixmaps/favicon';
syntax-highlight-css = '_csvn.css';
header = '/.csvn/html/header.html';
footer = '/.csvn/html/footer.html';
page-size = 200;
owner = "Andrey V.Kosteltsev";
author = "Andrey V.Kosteltsev";
title = "Radix.pro SVN Repositories";
description = "Subversion repositories hosted at radix.pro (St.-Petersburg)";
keywords = "cSvn repositories";
copyright = "© Andrey V. Kosteltsev, 2019 – 2020.";
copyright-notice = "Where any material of this site is being reproduced, published or issued to others the reference to the source is obligatory.";
home-page = "https://radix.pro/";
section "Tools" {
repo 'csvn-ui' {
owner = "Andrey V.Kosteltsev";
title = "cSvn-ui for SVN Repositories";
description = "cSvn-ui – is a web interface for Subversion™ Repositories written in C";
home-page = "https://radix.pro/";
}
}