Index: cgit-ui.rc.5
===================================================================
--- cgit-ui.rc.5 (nonexistent)
+++ cgit-ui.rc.5 (revision 5)
@@ -0,0 +1,627 @@
+.\"
+.TH "CGIT-UI.RC" 5 "2022-02-19" "cGit-ui CGI script" "cgit-ui.rc"
+
+.SH "NAME"
+\fB/etc/cgit-ui.rc\fR \- cGit-ui CGI script config file
+
+.SH "DESCRIPTION"
+\fB/etc/cgit-ui.rc\fR file describes Git repositories which should be shown by \fBcGit-ui\fR CGI script.
+
+.SH "FILE FORMAT"
+\fB/etc/cgit-ui.rc\fR is regular text file created by user to present Git repositories. This file reads by \fBcscmd\fR daemon
+and converts to binary form for \fBcGit-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
+/**************************
+ Kernel Git repositories:
+ */
+home-page = "https://www.kernel.org/";
+
+repo 'git.git' {
+ owner = "Junio C. Hamano";
+ title = "The core git plumbing";
+ description = "Git – fast, scalable, distributed revision control system.";
+ git-root = '/pub/scm/git';
+ clone-prefix-readonly = 'git://git.kernel.org/pub/scm/git';
+ home-page = "https://git-scm.com/";
+}
+
+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 = "Git-scm";\fR
+.EE
+.in
+
+.PP
+\fBpath\fR \- path constants. Example declaration:
+.PP
+.in +4n
+.EX
+\fIpath = '/etc/cgit-ui.rc';\fR
+.EE
+.in
+
+.SH "RESERVED VARIABLES"
+There is a set of variable names used by \fBcGit-ui\fR CGI Script.
+
+.TP 4
+\fBgit-root\fR
+The name of directory where Git repositories is placed on the filesystem. For example:
+.PP
+.in +6n
+.EX
+\fIgit-root = '/pub/scm/git';\fR
+.EE
+.in
+
+.TP 4
+\fBrepo-root\fR
+The name of directory where some repository is placed related to \fBgit-root\fR directory. For example:
+.PP
+.in +6n
+.EX
+\fIrepo-root = 'dm644x';\fR
+.EE
+.in
+
+.TP 4
+\fBclone-prefix-readonly\fR
+The clone 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
+\fIclone-prefix-readonly = 'git://example.com';\fR
+.EE
+.in
+
+.TP 4
+\fBclone-prefix\fR
+The clone 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
+\fIclone-prefix = 'git://git@example.com:pub';\fR
+.EE
+.in
+
+.RS 4
+This means the access on behalf \fIgit\fR system user.
+.RE
+
+.TP 4
+\fBtrunk\fR
+The name of the main branch of particular repository. Default value is \fImaster\fR.
+.RS 4
+Example declarations of main branch name:
+.RE
+.PP
+.in +6n
+.EX
+\fItrunk = 'master';\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 \fBcGit-ui\fR CGI Script.
+.RE
+
+.TP 4
+\fBcss\fR
+.RS 4
+The full name of the CSS style sheet relative to the directory where \fBcGit-ui\fR CGI Sctipt is installed.
+Example declaration:
+.RE
+.PP
+.in +6n
+.EX
+\fIcss = '/.cgit/css/cgit.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 \fBcGit-ui\fR pages.
+Default value: \fI'/.cgit/pixmaps/cgit-banner-280x280.png'\fR. The path to the \fBlogo\fR also should be set
+relative to the directory where \fBcGit-ui\fR CGI Script is installed. Example declaration:
+.PP
+.in +6n
+.EX
+\fIlogo = '/.cgit/pixmaps/cgit-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 \fBcGit-ui\fR pages.
+Default value: \fI'/.cgit/pixmaps/logo/git-logo-white-256x256.svg'\fR. The path to the \fBmain-menu-logo\fR also should be set
+relative to the directory where \fBcGit-ui\fR CGI Script is installed. Example declaration:
+.PP
+.in +6n
+.EX
+\fImain-menu-logo = '/.cgit/pixmaps/logo/git-logo-white-256x256.svg';\fR
+.EE
+.in
+
+.TP 4
+\fBfavicon-path\fR
+The directory name of the 'favicon.ico' file without leadind dir-separator.
+Default value: \fI'/.cgit/pixmaps/favicon'\fR. Example declaration:
+.PP
+.in +6n
+.EX
+\fIfavicon-path = '/.cgit/pixmaps/favicon';\fR
+.EE
+.in
+
+.RS 4
+This directory name used for finding additional images declared in the HTML \fBheader\fR of all \fBcGit-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'_cgit.css'\fR. Example declaration:
+.PP
+.in +6n
+.EX
+\fIsyntax-highlight-css = '_cgit.css';\fR
+.EE
+.in
+
+.RS 4
+\fBcGit-ui\fR CGI Script uses highlight.js
+.UR https://\:highlightjs.org\:/
+.UE
+installed into \fI'/.cgit/.engines/highlight/${hljs-version}/{css,js}'\fR directories
+where the default \fI'_cgit.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'/.cgit/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'/.cgit/html/footer.html'\fR. Examle of the \fBheader\fR and the \fBfooter\fR declarations:
+.PP
+.in +6n
+.EX
+\fIheader = '/.cgit/html/header.html';\fR
+\fIfooter = '/.cgit/html/footer.html';\fR
+.EE
+.in
+
+.RS 4
+The \fBheader\fR and the \fBfooter\fR files used as template where \fBcGit-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/cgit-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 \fBcGit-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 \fBcGit-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 \fBcGit-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 \fBcGit-ui\fR pages as a page title. Default value: \fI"Git Repositories"\fR.
+Example declaration:
+.PP
+.in +6n
+.EX
+\fItitle = "Example.org Git Repositories";\fR
+.EE
+.in
+
+.TP 4
+\fBdescription\fR
+The \fBstring\fR variable used in the HTML header of all \fBcGit-ui\fR pages as a page description.
+Default value: \fI"Git repositories hosted at Solar System, Earth"\fR.
+Example declaration:
+.PP
+.in +6n
+.EX
+\fIdescription = "Git 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 defined by following way:
+.RE
+.PP
+.in +6n
+.EX
+\fIdescription = "Git 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 \fBcGit-ui\fR pages as a page keywords.
+Default value: \fI"cGit repositories"\fR.
+Example declaration:
+.PP
+.in +6n
+.EX
+\fIkeywords = "cGit UI CGI Git Repositories scm";\fR
+.EE
+.in
+
+.TP 4
+\fBcopyright-notice\fR
+The \fBstring\fR variable used in the HTML footer of all \fBcGit-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 \fBcGit-ui\fR pages as a Copyright.
+Default value: \fI"© 2022 Andrey V.Kosteltsev. All Rights Reserved."\fR.
+Example declaration:
+.PP
+.in +6n
+.EX
+\fIcopyright = "© 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. \fBcGit-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 \fBcGit-ui\fR CGI Script is installed. For example, if \fBcGit-ui\fR CGI Script installed
+into \fI/srv/www/htdocs/cgit\fR directory and file name declared as \fI/analytics/links\fR then \fBcGit-ui\fR CGI Script will try to read the
+file \fI/srv/www/htdocs/cgit/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. \fBcGit-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 \fBcGit-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/cgit-ui.rc\fR
+configuration file and cannot be overriden in a repository declaration.
+.RE
+
+Donation variables:
+
+.RS 4
+The \fBcGit-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
+\fBcGit-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/cgit-ui.rc\fR config file should contains at least one repository declaration to be shown by the \fBcGit-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)
+
cGit-UI for Git Repositories
cGit-UI – is a web interface for Git Repositories. cGit CGI script is writen in C and therefore it's fast enough
12 Commits
0 Branches
1 Tag