cvsweb: Write a manual page for the configuration file almost completely

cvsweb: Write a manual page for the configuration file almost completely

[schwarze]

Log Message:
-----------
Write a manual page for the configuration file almost completely
from scratch.  Since i copied a handful of sentences from the old
file cvsweb.conf, the Copyright notices of Ville Skytta, Akinori MUSHA,
and Henner Zeller remain.  I carefully checked who wrote and committed
those sentences during which years using CVS history.

Added Files:
-----------
    cvsweb:
        cvsweb.conf.5

Revision Data
-------------
--- /dev/null
+++ cvsweb.conf.5
@@ -0,0 +1,359 @@
+.\" $OpenBSD$
+.\" 
+.\" Copyright (c) 2019 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2002 Ville Skytta
+.\" Copyright (c) 2000 Akinori MUSHA
+.\" Copyright (c) 2000 Henner Zeller
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.Dd $Mdocdate: November 29 2019 $
+.Dt CVSWEB.CONF 5
+.Os
+.Sh NAME
+.Nm cvsweb.conf
+.Nd CVSweb configuration file
+.Sh DESCRIPTION
+The
+.Xr cvsweb 8
+configuration file is a
+.Xr perl 1
+script executed via the Perl
+.Fn do
+function near the beginning of the main program.
+It can contain arbitrary Perl code, but it is only intended to
+override or change the global variables documented below, which are
+listed with their default value and their type.
+.Bl -tag -width Ds
+.It Va $address No = 'CVSweb' ; # string optionally including HTML markup
+The address shown in the footer.
+This will be put into an
+.Pf < Ic address Ns >
+element.
+.It Va $allow_annotate No = 1 ; # boolean
+Enable using the
+.Xr cvs 1
+.Cm annotate
+command.
+.It Va $allow_compress No = 0 ; # boolean
+Enable
+.Dq Content-Encoding: gzip
+if the browser supports it.
+.It Va $allow_dir_extra No = 1 ; # boolean
+Enable generation of hyperlinks to manual pages in directory views.
+.It Va $allow_log_extra No = 1 ; # boolean
+Enable generation of hyperlinks to manual pages in logs.
+.It Va $allow_mailtos No = 1 ; # boolean
+Enable generation of mailto: links.
+.It Va $allow_markup No = 1 ; # boolean
+Enable display of files in HTML form.
+.It Va $allow_source_extra No = 1 ; # boolean
+Enable generation of hyperlinks to manual pages in source code and diffs.
+.It Va $allow_tar No = 0 ; # boolean
+Enable downloading of tarballs using the
+.Cm tarball
+query keyword and generate hyperlinks facilitating such downloads.
+.It Va @annotate_options No = XXX ; # array of strings
+Global options passed to the
+.Xr cvs 1
+program when invoking the
+.Cm annotate
+command.
+Despite the name, these are
+.Em not
+options to
+.Cm annotate ,
+but to
+.Xr cvs 1
+itself.
+The default is the same as for the configuration variable
+.Va @cvs_options ,
+but changing either of them in the configuration file leaves the
+other variable unchanged.
+.It Va %CMD No # hash of strings
+Absolute paths inside the webserver
+.Xr chroot 2
+to the following commands:
+.Bd -literal -compact -offset indent
+$CMD{cvs}     = '/usr/bin/cvs';
+$CMD{rcsdiff} = '/usr/bin/rcsdiff';
+$CMD{rlog}    = '/usr/bin/rlog';
+$CMD{tar}     = '/bin/tar';
+.Ed
+.It Va $cssurl No = '/css/cvsweb.css' ; # string
+The URI of the cascading style sheet file.
+.It Va @cvs_options No = XXX ; # array of strings
+Global options passed to the
+.Xr cvs 1
+program when invoking a command other than
+.Cm annotate .
+In most cases,
+.Xr cvsweb 8
+passes additional global options which cannot be suppressed.
+Also, the options passed to the individual CVS commands (as opposed
+to the global options) are generally not configurable.
+.It Va @CVSrepositories No = ('local', ['Local Repository', '/cvs']);
+The list of repositories to serve in an extremely idiosyncratic format.
+For each repository, the list requires two entries.
+The first entry is a short string to identify the repository using the
+.Cm cvsroot
+query variable.
+The second entry is an array reference containing two more strings.
+The first one is the name of the CVS repository displayed in the user
+interface, for example in navigation lines
+and in dropdown selection lists.
+The last on is the absolute path to the repository directory
+inside the webserver
+.Xr chroot 2 .
+Each repository is required to contain a
+.Pa CVSROOT
+subdirectory with the usual content.
+If possible, put all the modules you want to serve into the same
+repository because that results in a simpler user interface on the web.
+.It Va $DEBUG No = 0; # boolean
+Let standard error output reach the web server error log.
+By default, it is discarded.
+.It Va $defaulttitle No = 'CVS Repository'; # string
+The title of the main page.
+This will be HTML escaped and put into the
+.Pf < Ic title Ns >
+and
+.Pf < Ic h1 Ns >
+elements.
+.It Va %DEFAULTVALUE
+A hash of defaults that can be overridden in individual CGI requests
+by using query variables.
+The keys are the names of the query variables listed below,
+the values their respective default values.
+.It Va $DEFAULTVALUE{f} No =  ' Ns Cm u Ns '; # one of the letters given below
+Diff format:
+.Bl -tag -width Ds -compact
+.It Cm c
+context diff
+.It Cm u
+unified diff (the default)
+.It Cm h
+side-by-side colored diff
+.El
+.It Va $DEFAULTVALUE{hideattic} No = 1 ; # boolean
+By default, show deleted files in a separate
+.Pa Attic
+directory listing.
+If set to 0, include them in the main directory listing.
+Despite the name, completely hiding them is not possible.
+.It Va $DEFAULTVALUE{hidecvsroot} No = 0 ; # boolean
+Do not include the top-level
+.Pa CVSROOT
+directory in the top-level directory listing.
+By default, it is shown like any other directory.
+.It Va $DEFAULTVALUE{hidenonreadable} No = 1 ; # boolean
+By default, files and directories that cannot be read do not appear
+in directory listings.
+If set to 0, show them like any other files and directories.
+.It Va $DEFAULTVALUE{ignorecase} No = 0 ; # boolean
+Ignore case when alphabetically sorting strings.
+By default, all upper case letters precede all lower case letters.
+.It Va $DEFAULTVALUE{ln} No = 0 ; # boolean
+Show line numbers in HTML output of files, with HTML
+.Cd id
+attributes of the form
+.Qq l%d
+to support deep linking to specific lines.
+.It Va $DEFAULTVALUE{logsort} No = ' Ns Cm date Ns ';\
+ # one of the keywords given below
+Sort order for CVS logs:
+.Bl -tag -width Ds -compact
+.It Cm cvs
+Do not sort; list revisions as
+.Xr rlog 1
+shows them.
+.It Cm date
+Sort revisions by date, most recent first.
+.It Cm rev
+Sort by revision number, highest first.
+.El
+.It Va $DEFAULTVALUE{sortby} No = ' Ns Cm file Ns ';\
+ # one of the keywords given below
+File sort order in directory listings:
+.Bl -tag -width Ds -compact
+.It Cm author
+by the login name of the most recent committer, alphabetically
+.It Cm date
+by the latest commit date, most recent first
+.It Cm file
+by the filename, alphabetically (the default)
+.It Cm log
+by the log message, alphabetically
+.It Cm rev
+by the highest revision number, highest first
+.El
+.It Va $edit_option_form No = 1 ; # boolean
+In the directory view, show a form for setting options.
+.It Va $file_list_len No = 0 ; # non-negative integer
+The maximum number of filenames to pass to
+.Xr rlog 1
+in one command.
+By default, the number of filenames in a single call is not limited.
+.\" Two sentences written by Ville Skytta in 2002:
+If you see "Failed to spawn rlog" errors with directories containing
+lots of files, experiment by setting this to different values and see if
+the error still occurs.
+A good value to start from is 200.
+.It Va @ForbiddenFiles No # array of compiled regular expressions
+Matching files and directories are not displayed.
+Path names are considered relative to the respective cvsroot,
+and without the
+.Pa ,v
+suffix, if any.
+By default, the array contains the following two entries:
+.Bd -literal -offset indent
+qr|^CVSROOT/+passwd$|o
+qr|/\e.cvspass$|o
+.Ed
+.It Va $hr_breakable No = 1 ; # boolean
+In side-by-side colored diffs and in
+.Cm annotate
+output, allow line breaking.
+Otherwise, horizontal scrolling may be needed
+to see all parts of long lines.
+.It Va $hr_ignkeysubst No = 1 ; # boolean
+Do not display changes resulting only from keyword substitution, using the
+.Xr rcsdiff 1
+.Fl kk
+option.
+.It Va $hr_ignwhite No = 0 ; # boolean
+Ignore whitespace in side-by-side colored diffs, using the
+.Xr diff 1
+.Fl w
+option.
+.It Va $iconsdir No = '/icons' ; # string
+Absolute path inside the webserver
+.Xr chroot 2
+to the directory containing the icons for the web UI.
+.It Va $logo No = Cm undef ; No # string including HTML markup
+Optional HTML code to include at the very beginning of the
+.Pf < Ic body Ns >
+element.
+For example, it can include an
+.Pf < Ic img Ns >
+element.
+.It Va $mancgi No = 'https://man.openbsd.org/%s.%s'; # URI template string
+String to construct URIs of online manual pages from.
+The first occurrence of the substring
+.Sq %s
+will be replaced by the name of the manual page to link to,
+the second by the manual section.
+For example:
+.Bd -literal
+https://www.freebsd.org/cgi/man.cgi?query=%s&sektion=%s
+https://netbsd.gw.com/cgi-bin/man-cgi?%s+%s
+.Ed
+.It Va $mime_types No = '/conf/mime.types' ; # string
+Absolute paths inside the webserver
+.Xr chroot 2
+to the traditional
+.Pa mime.types
+file.
+That file is used as a fallback when neither
+.Va %MTYPES
+nor
+.Xr MIME::Types 3p
+yields a match.
+.It Va %MTYPES No # hash of strings
+The keys are file name extensions,
+the values the corresponding MIME types.
+This hash is used before any other lookup method,
+providing fast lookup and allowing to override other sources.
+If it contains a key
+.Qq * ,
+the associated MIME type is used when no match is found from any source.
+.It Va $preformat_in_markup No = 0 ; # boolean
+When displaying file contents, mark up URIs and manual page references
+with HTML
+.Pf < Ic a Ns >
+elements.
+.It Va @rcsdiff_options No = qw(-q) ; # array of strings
+Command line options passed to the
+.Xr rcsdiff 1
+program.
+.It Va $shortLogLen No = 80 ; # positive integer
+The length to which the last log entry is truncated in the directory view.
+.It Va $show_author No = 1 ; # boolean
+In the directory view, show the committer of the latest change.
+.It Va $show_log_in_markup No = 1 ; # boolean
+Prepend the corresponding commit log entry
+when displaying file content in HTML format.
+.It Va $show_subdir_lastmod No = 0 ; # boolean
+.\" Paragraph written by Henner Zeller in 2000
+.\" and possibly edited by Akinori MUSHA in 2000:
+For subdirectories, try to show the last changelog message.
+The current implementation makes many assumptions
+and may show the incorrect file at some times.
+The main assumption is that the last modified file
+has the newest filedate.
+But some CVS operations touch the file even when a new version isn't
+checked in, and TAG based browsing essentially puts this out of
+order unless the last checkin was on the same tag as you are viewing.
+Enable this if you like the feature, but don't rely on correct results.
+.It Va $tabstop No = 8 ; # positive integer
+Tab width used for expanding tabs to spaces in HTML output.
+If an editor directive controlling the tab width is found near the
+beginning of a file, this variable is ignored for that file.
+.It Va @tar_options No = qw() # array of strings
+Command line options passed to
+.Xr tar 1
+when creating an archive for download.
+In addition to the configured options,
+.Fl c
+and
+.Fl f
+are always used.
+.It Va $use_descriptions No = 0 ; # boolean
+Use optional files
+.Pa CVSROOT/descriptions
+containing descriptions of directories.
+The first word on each line is the name of the directory
+relative to the cvsroot, terminated by whitespace.
+The rest of the line is a description, optionally containing HTML markup.
+.It Va $use_moddate No = 1 ; # boolean
+Always calculate times that correspond to the content for the HTTP
+Last-Modified header, even if this requires running an additional
+.Xr rlog 1
+command for a file being checked out.
+Disabling this can slightly reduce server load, avoiding the additional
+.Xr rlog 1
+command when possible.
+.El
+.Sh FILES
+This configuration file is located at
+.Pa /conf/cvsweb/cvsweb.conf
+inside the web server
+.Xr chroot 2 .
+The only way to read it from a different place is by editing the
+.Va $config
+variable in the
+.Xr cvsweb 8
+program itself, which is not recommended.
+.Sh SEE ALSO
+.Xr cvs 1 ,
+.Xr cvsweb 8
--
 To unsubscribe send an email to source+unsubscribe@mandoc.bsd.lv