path: root/doc/csvn-ui.rc.5.md

# [csvn-ui.rc(5) Config File](https://csvn.radix.pro/csvn-ui/trunk/doc/csvn-ui.rc.5.md)

**/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](#file-format)
    * [Data Types](#data-types)
    * [Reserved Variables](#reserved-variables)
    * [Repository Declaration](#repository-declaration)
* [Working Example](#working-example)
* [See Also](#see-also)


## File Format

**/etc/csvn-ui.rc** is a regular text file created by user to present Subversion repositories. This file
reads by [**cscnd(8)**](https://csvn.radix.pro/cscm/trunk/doc/cscmd.8.md) 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:

```dts
/****************************
  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:

>> ```dts
>> true = 1;
>> ```


> **string** – string constants. Example declaration:

>> ```dts
>> name = "Apache Subversion";
>> ```


> **path** – path constants. Example declaration:

>> ```dts
>> 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:

```dts
svn-utc-offset = +0300; /* Europe/Moscow time zone */
```


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

```dts
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:

```dts
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:

```dts
branches = 'branches';
trunk    = 'trunk';
tags     = 'tags';
```


#### snapshots

The extension of snapshot tarballs. Default value: *'tar.xz'*. Example declaration:

```dts
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:

```dts
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:

```dts
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:

```dts
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:

```dts
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:

```dts
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:

```dts
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:

```dts
syntax-highlight-css = '_csvn.css';
```

**cSvn-ui** CGI Script uses [highlight.js](https://highlightjs.org/) 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:

```dts
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:

```dts
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:

```dts
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:

```dts
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:

```dts
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:

```dts
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:

```dts
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:

```dts
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:

```dts
copyright = "© John Smith (explorer), 1580 - 1631.";
```


#### home-page

The URL of the home page of the project. Default value: *"https://example.org"*.
Example declaration:

```dts
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:

```dts
analytic-links = '/analytics/links';
```

Where the file */analytics/links* may contains HTML tags like follow:

```html
<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 &lt;HEAD&gt; tag before
&lt;/HEAD&gt; entry of each HTML page. Example declaration:

```dts
analytic-scripts = '/analytics/scripts';
```

Where the file */analytics/scripts* may contains code like follow:

```html
<!-- 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 *&lt;script&gt;* 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:

```dts
donate = 1;
```

#### donate-css

The name of file contains the stylesheet for donation modal dialogue. Example declaration:

```dts
donate-css = '/donations/donate.css';
```

#### donate-html

The name of file contains the HTML code of donation modal dialogue. Example declaration:

```dts
donate-html = '/donations/donate.html';
```

#### donate-js

The name of file contains the javascript code for donation modal dialogue automation. Example declaration:

```dts
donate-js = '/donations/donate.js';
```

**cSvn-ui** CGI Script includes these files at end of &lt;BODY&gt; tag just before the closing &lt;/BODY&gt; 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:

```dts
donate-header = "Donations";
```

#### donate-purpose

The donation purpose used as value of &lt;input value="..."&gt; 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:

```dts
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:

```dts
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:

```php
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:

```dts
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.

```dts
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:

```dts
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.

```dts
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 = "&#169; Andrey V. Kosteltsev, 2019 &#8211; 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 &#8211; is a web interface for Subversion&#8482; Repositories written in C";
    home-page = "https://radix.pro/";
  }
}

```


## See Also

> [**README**](https://csvn.radix.pro/csvn/trunk/README.md),
> [**cscmd(8)**](https://csvn.radix.pro/cscm/trunk/doc/cscmd.8.md)