cSvn-UI for SVN Repositories

.\"
.TH "CSVN-UI.RC" 5 "2020-11-07" "cSvn-ui CGI script" "csvn-ui.rc"

.SH "NAME"
\fB/etc/csvn-ui.rc\fR \- cSvn CGI script config file

.SH "DESCRIPTION"
\fB/etc/csvn-ui.rc\fR file describes Subversion repositories which should be shown by \fBcSvn-ui\fR CGI script.

.SH "FILE FORMAT"
\fB/etc/csvn-ui.rc\fR is regular text file created by user to present Subversion repositories. This file reads by \fBcscmd\fR daemon
and converts to binary form for \fBcSvn-ui\fR CGI script. Binary format allows to minimize the time needed for complete HTTP responses.
.PP
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:
.PP
.in +4n
.EX
\fI
/****************************
  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' {
    . . .
  }
  . . .
}
\fR
.EE
.in

.SH "DATA TYPES"
Configuration file assumes three types of variables.

.PP
\fBint\fR \- integer constants. Example declaration:
.PP
.in +4n
.EX
\fItrue = 1;\fR
.EE
.in

.PP
\fBstring\fR \- string constants. Example declaration:
.PP
.in +4n
.EX
\fIname = "Apache Subversion";\fR
.EE
.in

.PP
\fBpath\fR \- path constants. Example declaration:
.PP
.in +4n
.EX
\fIpath = '/etc/csvn-ui.rc';\fR
.EE
.in

.SH "RESERVED VARIABLES"
There is a set of variable names used by \fBcSvn-ui\fR CGI Script.

.TP 4
\fBsvn-utc-offset\fR
The integer or string value of UTC offset on the SVN server where repositories are published. For example:
.PP
.in +6n
.EX
\fIsvn-utc-offset = +0300; /* Europe/Moscow time zone */\fR
.EE
.in

.TP 4
\fBrepo-root\fR
The name of directory where some repository is placed related to \fBsvn repositories root\fR directory. For example:
.PP
.in +6n
.EX
\fIrepo-root = 'tools';\fR
.EE
.in

.TP 4
\fBcheckout-prefix-readonly\fR
The checkout prefix for readonly access to the repository. The value of this variable should has \fBpath\fR type
without leadinfg dir-separator. Example  declaration:
.PP
.in +6n
.EX
\fIcheckout-prefix-readonly = 'svn://example.com';\fR
\fIcheckout-prefix-readonly = 'https://svn.example.com/svn';\fR
.EE
.in

.RS 4
Please note that \fBsvn\fR protocol works match quickly.
.RE

.TP 4
\fBcheckout-prefix\fR
The checkout prefix for readwrite access to the repository. The value of this variable should has \fBpath\fR type
without leadinfg dir-separator. Example declaration:
.PP
.in +6n
.EX
\fIcheckout-prefix = 'svn+ssh://svn@example.com';\fR
.EE
.in

.RS 4
This means the access on behalf \fIsvn\fR system user.
.RE

.TP 4
\fBbranches\fR
The name of directory where branches is places. Default value is \fIbranches\fR.
.TP 4
\fBtrunk\fR
The name of the \fItrunk\fR directory. Default value is \fItrunks\fR.
.TP 4
\fBtags\fR
The name of directory where tags are saved. Default value is \fItags\fR.
.RS 4
Example declarations of directory names:
.RE
.PP
.in +6n
.EX
\fIbranches = 'branches';\fR
\fItrunk    = 'trunk';\fR
\fItags     = 'tags';\fR
.EE
.in

.TP 4
\fBsnapshots\fR
The extension of snapshot tarballs. Default value: \fI'tar.xz'\fR. Example declaration:
.PP
.in +6n
.EX
\fIsnapshots = 'tar.xz';\fR
.EE
.in

.RS 4
Currently snapshot variable is not used by \fBcSvn-ui\fR CGI Script.
.RE

.TP 4
\fBcss\fR
.RS 4
The full name of the CSS style sheet relative to the directory where \fBcSvn-ui\fR CGI Sctipt is installed.
Example declaration:
.RE
.PP
.in +6n
.EX
\fIcss = '/.csvn/css/csvn.css';\fR
.EE
.in

.TP 4
\fBlogo\fR
Url which specifies the source of an image which will be used as a logo (i.e right banner) on \fBcSvn-ui\fR pages.
Default value: \fI'/.csvn/pixmaps/csvn-banner-280x280.png'\fR. The path to the \fBlogo\fR also should be set
relative to the directory where \fBcSvn-ui\fR CGI Script is installed. Example declaration:
.PP
.in +6n
.EX
\fIlogo = '/.csvn/pixmaps/csvn-banner-280x280.png';\fR
.EE
.in

.TP 4
\fBlogo-alt\fR
The string used in HTML as a 'alt' property of the right banner <img> tag. Default value: \fI"Example.org"\fR.
Example declaration:
.PP
.in +6n
.EX
\fIlogo-alt = "Example.org";\fR
.EE
.in

.TP 4
\fBlogo-link\fR
The string used in HTML as a 'href' property of the right banner image link <a> tag. Default value: \fI"https://example.org"\fR.
Example declaration:
.PP
.in +6n
.EX
\fIlogo-link = "https://example.org";\fR
.EE
.in

.TP 4
\fBmain-menu-logo\fR
Url which specifies the source of an image which will be used as a logo of the main menu item on \fBcSvn-ui\fR pages.
Default value: \fI'/.csvn/pixmaps/logo/SVN-logo-white-744x744.svg'\fR. The path to the \fBmain-menu-logo\fR also should be set
relative to the directory where \fBcSvn-ui\fR CGI Script is installed. Example declaration:
.PP
.in +6n
.EX
\fImain-menu-logo = '/.csvn/pixmaps/logo/SVN-logo-white-744x744.svg';\fR
.EE
.in

.TP 4
\fBfavicon-path\fR
The directory name of the 'favicon.ico' file without leadind dir-separator.
Default value: \fI'/.csvn/pixmaps/favicon'\fR. Example declaration:
.PP
.in +6n
.EX
\fIfavicon-path = '/.csvn/pixmaps/favicon';\fR
.EE
.in

.RS 4
This directory name used for finding additional images declared in the HTML \fBheader\fR of all \fBcSvn-ui\fR pages.
.RE

.TP 4
\fBsyntax-highlight-css\fR
The base name of the CSS style sheet file used for syntax highlighting.
Default value: \fI'_csvn.css'\fR. Example declaration:
.PP
.in +6n
.EX
\fIsyntax-highlight-css = '_csvn.css';\fR
.EE
.in

.RS 4
\fBcSvn-ui\fR CGI Script uses highlight.js
.UR https://\:highlightjs.org\:/
.UE
installed into \fI'/.csvn/.engines/highlight/${hljs-version}/{css,js}'\fR directories
where the default \fI'_csvn.css'\fR file is palced too.
.RE

.TP 4
\fBheader\fR
The content of the file specified with this option will be included verbatim at the top of all pages.
Default value: \fI'/.csvn/html/header.html'\fR.
.TP 4
\fBfooter\fR
The content of the file specified with this option will be included verbatim at the bottom of all pages.
Default value: \fI'/.csvn/html/footer.html'\fR. Examle of the \fBheader\fR and the \fBfooter\fR declarations:
.PP
.in +6n
.EX
\fIheader = '/.csvn/html/header.html';\fR
\fIfooter = '/.csvn/html/footer.html';\fR
.EE
.in

.RS 4
The \fBheader\fR and the \fBfooter\fR files used as template where \fBcSvn-ui\fR CGI Script substitute placeholders
such as \fI${variable-name}\fR by their values. For example the ${css} placeholder will be replaced by the value
of \fIcss\fR variable declared in the \fB/etc/csvn-ui.rc\fR config file.
.RE

.TP 4
\fBpage-size\fR
The \fBstring\fR or \fBint\fR variable which set the length of the repositories list or logs shown in one page by the \fBcSvn-ui\fR CGI Script.
Default value: 200. Example declaration:
.PP
.in +6n
.EX
\fIpage-size = 50; /* 10 ... 200 may be string or integer. Default value is page-size = 200 */\fR
.EE
.in

.TP 4
\fBowner\fR
The \fBstring\fR variable used in the HTML header of all \fBcSvn-ui\fR pages and also in the \fIOwner\fR colon of the repository list.
Default value: \fI"Andrey V.Kosteltsev"\fR.
.TP 4
\fBauthor\fR
The \fBstring\fR variable used in the HTML header of all \fBcSvn-ui\fR pages. Default value: \fI"Andrey V.Kosteltsev"\fR.
Example declarations of the \fBowner\fR and the \fBauthor\fR variables:
.PP
.in +6n
.EX
\fIowner  = "John Smith";\fR
\fIauthor = "John Smith";\fR
.EE
.in

.TP 4
\fBtitle\fR
The \fBstring\fR variable used in the HTML header of all \fBcSvn-ui\fR pages as a page title. Default value: \fI"SVN Repositories"\fR.
Example declaration:
.PP
.in +6n
.EX
\fItitle  = "Example.org SVN Repositories";\fR
.EE
.in

.TP 4
\fBdescription\fR
The \fBstring\fR variable used in the HTML header of all \fBcSvn-ui\fR pages as a page description.
Default value: \fI"Subversion repositories hosted at Solar System, Earth"\fR.
Example declaration:
.PP
.in +6n
.EX
\fIdescription  = "Subversion repositories hosted at example.org (St.-Petersburg)";\fR
.EE
.in

.RS 4
For a long description the value of this \fBstring\fR variable can be splitted in the C-style by following way:
.RE
.PP
.in +6n
.EX
\fIdescription  = "Subversion repositories"\fR
\fI               " hosted at example.org "\fR
\fI               "(St.-Petersburg)";\fR
.EE
.in

.TP 4
\fBkeywords\fR
The \fBstring\fR variable contains space separated keywords used in the HTML header of all \fBcSvn-ui\fR pages as a page keywords.
Default value: \fI"cSvn repositories"\fR.
Example declaration:
.PP
.in +6n
.EX
\fIkeywords = "cSvn UI CGI Subversion Repositories scm SVN";\fR
.EE
.in

.TP 4
\fBcopyright-notice\fR
The \fBstring\fR variable used in the HTML footer of all \fBcSvn-ui\fR pages as a Copyright Notice.
Default value: \fI"By using any website materials you agree to indicate source."\fR.
Example declaration:
.PP
.in +6n
.EX
\fIcopyright-notice = "By using any materials you agree with ...";\fR
.EE
.in

.TP 4
\fBcopyright\fR
The \fBstring\fR variable used in the HTML footer of all \fBcSvn-ui\fR pages as a Copyright.
Default value: \fI"&#169; 2020 Andrey V.Kosteltsev. All Rights Reserved."\fR.
Example declaration:
.PP
.in +6n
.EX
\fIcopyright = "&#169; John Smith (explorer), 1580 - 1631.";\fR
.EE
.in

.TP 4
\fBhome-page\fR
The URL of the home page of the project.
Default value: \fI"https://example.org"\fR.
Example declaration:
.PP
.in +6n
.EX
\fIhome-page = "https://main-site-of-the-project.org";\fR
.EE
.in

Analytics variables:

.TP 4
\fBanalytic-links\fR
The path to the file which contains meta tags with site ownership verificaton codes for engines such as \fIGoogle Search Console\fR or
\fIYandex Webmaster\fR. \fBcSvn-ui\fR CGI Script reads the file \fBanalytic-links\fR in RAW format and includes it into <HEAD> tag of each HTML page.
Example declaration:
.PP
.in +6n
.EX
\fIanalytic-links = '/analytics/links';\fR
.EE
.in

.RS 4
Where the file \fI/analytics/links\fR may contains HTML tags like follow:
.RE

.PP
.in +6n
.EX
\fI<meta name="google-site-verification" content="..." />\fR
.EE
.in

.RS 4
The file name should be defined relative of the path where \fBcSvn-ui\fR CGI Script is installed. For example, if \fBcSvn-ui\fR CGI Script installed
into \fI/srv/www/htdocs/csvn\fR directory and file name declared as \fI/analytics/links\fR then \fBcSvn-ui\fR CGI Script will try to read the
file \fI/srv/www/htdocs/csvn/analytics/links\fR.
.RE

.TP 4
\fBanalytic-scripts\fR
The path to the file which contains JavaScripts for engines such as \fIGoogle Search Console\fR or
\fIYandex Webmaster\fR. \fBcSvn-ui\fR CGI Script reads the file \fBanalytic-scripts\fR in RAW format and includes it at the end of <HEAD> tag before </HEAD>
entry of each HTML page.
Example declaration:
.PP
.in +6n
.EX
\fIanalytic-scripts = '/analytics/scripts';\fR
.EE
.in

.RS 4
Where the file \fI/analytics/scripts\fR may contains code like follow:
.RE

.PP
.in +6n
.EX
\fI
<!-- 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>
\fR
.EE
.in

.RS 4
Please note that the \fI<script>\fR tags should be present in the \fI/analytics/scripts\fR because \fBcSvn-ui\fR CGI Script reads this file
in RAW format and includes it as is.
.RE

.RS 4
The variables \fBanalytic-links\fR and \fBanalytic-scripts\fR should be declared on the global level of the \fB/etc/csvn-ui.rc\fR
configuration file and cannot be overriden in a repository declaration.
.RE

Donation variables:

.RS 4
The \fBcSvn-ui\fR 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 \fBdonate\fR variable to \fBdonate = 1\fR:
.RE

.TP 4
\fBdonate\fR
The integer variable used to enable or disable donation dialogue.
Example declaration:
.PP
.in +6n
.EX
\fIdonate = 1;\fR
.EE
.in

.TP 4
\fBdonate-css\fR
The name of file contains the stylesheet for donation modal dialogue.
Example declaration:
.PP
.in +6n
.EX
\fIdonate-css = '/donations/donate.css';\fR
.EE
.in

.TP 4
\fBdonate-html\fR
The name of file contains the HTML code of donation modal dialogue.
Example declaration:
.PP
.in +6n
.EX
\fIdonate-html = '/donations/donate.html';\fR
.EE
.in

.TP 4
\fBdonate-js\fR
The name of file contains the javascript code for donation modal dialogue automation.
Example declaration:
.PP
.in +6n
.EX
\fIdonate-js = '/donations/donate.js';\fR
.EE
.in

.RS 4
\fBcSvn-ui\fR CGI Script includes these files at end of <BODY> tag just before the closing </BODY> tag. Unlike the others,
the \fBdonate-html\fR 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 \fI${donate-header}\fR
and \fI${donate-purpose}\fR:
.RE

.TP 4
\fBdonate-header\fR
The title of the donation modal dialogue defined in the \fBdonate-html\fR file.
Example declaration:
.PP
.in +6n
.EX
\fIdonate-header = "Donations";\fR
.EE
.in

.TP 4
\fBdonate-purpose\fR
The donation purpose used as value of <input value="..."> tag property in payment form of systems such as \fIPayPal\fR or \fIYandex.Money\fR.
Also this value can be used as a header of modal dialogue content.
Example declaration:
.PP
.in +6n
.EX
\fIdonate-purpose = "Support for our projects";\fR
.EE
.in

.RS 4
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:
.RE

.PP
.in +6n
.EX
\fI
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";
    . . .
  }
}
\fR
.EE
.in

.RS 4
To show the modal dialogue in javascript code \fBdonate-js\fR the selector 'a.donate' should be used. For examle, like this:
.RE

.PP
.in +6n
.EX
\fI
var show = document.querySelector( "a.donate" );

/**************
  Open Dialog:
 */
show.onclick = function() {
  dialog.style.display = "block";
}
\fR
.EE
.in

.RS 4
Where the variable \fIdialog\fR points to modal dialogue defined in the \fBdonate-html\fR file.
.RE


.SH "REPOSITORY DECLARATIONS"
The \fB/etc/csvn-ui.rc\fR config file should contains at least one repository declaration to be shown by the \fBcSvn-ui\fR CGI Script.
When all expected variables declared in the global section the config file the repository declaration can be very simple:
.PP
.in +4n
.EX
\fI
repo 'tools' {
  owner = "John Smith";
  description = "John Smith's tools source code repository.";
}
\fR
.EE
.in

The list of repositories can be splitted in several sections. The section has a name and can contains repository declarations only.
.PP
.in +4n
.EX
\fI
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.";
  }
}
\fR
.EE
.in

Global variables are propagate into repo sections but their values overrides by correspond repo variables.


.SH "SEE ALSO"
.BR cscmd (8)