cSvn CGI Script

cSvn CGI Script – is a web frontend for Subversion™ Repositories

115 Commits   0 Branches   5 Tags   |
Index: csvncgi/csvnrc.5
===================================================================
--- csvncgi/csvnrc.5	(revision 51)
+++ csvncgi/csvnrc.5	(revision 52)
@@ -387,7 +387,7 @@
 .EE
 .in
 
-The list of repositories can be splitted in several sections. The section has a name an can contains repository declarations only.
+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
Index: doc/csvnrc.5.md
===================================================================
--- doc/csvnrc.5.md	(revision 51)
+++ doc/csvnrc.5.md	(revision 52)
@@ -1,3 +1,412 @@
 
-# [csvnrc(5)](https://csvn.radix.pro/csvn/trunk/doc/csvnrc.5.md)
+# [csvnrc(5) Config File](https://csvn.radix.pro/csvn/trunk/doc/csvnrc.5.md)
 
+**/etc/csvnrc** – **cSvn CGI Script** config file describes the Subversion™
+repositories that should be displayed on the WEB-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/csvnrc** is a regular text file created by user to present Subversion repositories. This file
+reads by [**csvnd(8)**](https://csvn.radix.pro/csvn/trunk/doc/csvnd.8.md) daemon and converts to binary
+form for **cSvn** 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/csvnrc';
+>> ```
+
+
+### Reserved Variables
+
+There is a set of variable names used by **cSvn** 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** CGI Script.
+
+
+> **css**
+>> The full name of the CSS style sheet relative to the directory where cSvn 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** pages. Default value: *'/.csvn/pixmaps/csvn-banner-280x280.png'*. The path to the
+>> **logo** also should be set relative to the directory where **cSvn** 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** 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** 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** 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** 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** 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/csvnrc** 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** 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** 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 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** 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** 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**
+>> pages as a page keywords. Default value: *"cSvn repositories"*. Example declaration:
+
+>> ```dts
+>> keywords = "cSvn CGI Subversion Repositories scm SVN";
+>> ```
+
+
+> **copyright-notice**
+>> The **string** variable used in the HTML footer of all **cSvn** 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** pages as a *Copyright*.
+>> Default value: *"&#169; 2020 Andrey V.Kosteltsev. All Rights Reserved."*.
+>> Example declaration:
+
+>> ```dts
+>> copyright = "&#169; 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";
+>> ```
+
+
+### Repository Declaration
+
+The **/etc/csvnrc** config file should contains at least one repository declaration to be shown
+by the **cSvn** 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** 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' {
+    owner = "Andrey V.Kosteltsev";
+    title = "cSvn CGI Script";
+    description = "cSvn CGI Script &#8211; is a web frontend for Subversion&#8482; Repositories";
+    home-page = "https://radix.pro/";
+  }
+}
+
+```
+
+
+## See Also
+
+> [**README**](https://csvn.radix.pro/csvn/trunk/README.md),
+> [**csvnd(8)**](https://csvn.radix.pro/csvn/trunk/doc/csvnd.8.md)
+