Unify the docs, samples and extensions

1 file changed, 139 insertions, 133 deletions

diff --git a/custom/cgitrc b/custom/cgitrc
index 18c973d..a594cb2 100644
--- a/custom/cgitrc
+++ b/custom/cgitrc
@@ -14,7 +14,7 @@
 # bundled about-render.lua about-filter in the filter section below. Source
 # syntax highlighting is optional and ships as a source-filter there too.
 #
-# One key=value pair per line. Lines starting with # are comments.
+# One key=value pair per line. Lines starting with # or ; are comments.
 
 # Maximum number of entries in the cgit output cache. A value of 0 disables
 # caching. Value is an integer. Default is 0.
@@ -24,7 +24,7 @@ cache-size=0
 # may use macros. Default is /var/cache/cgit. The directory must be owned by the
 # account the web server runs cgit as, with mode 0700, since the cache holds
 # every rendered page and the URLs visitors asked for.
-#cache-root=/var/cache/cgit
+cache-root=/var/cache/cgit
 
 # Minutes to cache the repository index page. Value is an integer number of
 # minutes. Default is 5.
@@ -38,12 +38,13 @@ cache-summary-ttl=5
 # integer number of minutes. Default is 15.
 cache-scan-ttl=15
 
-# Minutes to cache repo pages requested with a fixed SHA1. A negative value
-# keeps the page forever. Value is an integer number of minutes. Default is -1.
+# Minutes to cache repository pages requested with a fixed object id. A negative
+# value keeps the page forever. Value is an integer number of minutes. Default
+# is -1.
 cache-static-ttl=-1
 
-# Minutes to cache repo pages requested without a fixed SHA1. Value is an
-# integer number of minutes. Default is 5.
+# Minutes to cache repository pages requested without a fixed object id. Value
+# is an integer number of minutes. Default is 5.
 cache-dynamic-ttl=5
 
 # Minutes to cache the repository about page. Value is an integer number of
@@ -60,11 +61,11 @@ enable-cache-list=0
 
 # Heading text on the repository index page. Value is any text. Default is Git
 # repository browser.
-#root-title=Git repository browser
+root-title=Git repository browser
 
 # Subheading text below the index page heading. Value is any text. Default is a
 # fast webinterface for the git dscm.
-#root-desc=a fast webinterface for the git dscm
+root-desc=a fast webinterface for the git dscm
 
 # File included verbatim below the about link on the index page. Value is a
 # filesystem path. Default is none.
@@ -74,21 +75,22 @@ enable-cache-list=0
 # is one or more [ref]path entries. Default is none.
 #readme=:README.md
 
-# CSS document urls added to the head of every page. An empty value disables
-# it. Value is one or more urls. Default is /cgit.css.
-#css=/cgit.css
+# CSS document urls added to the head of every page. An empty value disables it.
+# Value is one or more urls. Default is /cgit.css.
+css=/cgit.css
 
 # JavaScript document urls included on every page. An empty value disables it.
 # Value is one or more urls. Default is /cgit.js.
-#js=/cgit.js
+js=/cgit.js
 
 # Shortcut icon url for all pages. Value is a url. Default is /favicon.ico.
-#favicon=/favicon.ico
+favicon=/favicon.ico
 
 # Image url used as the logo on all pages. Value is a url. Default is /cgit.png.
-#logo=/cgit.png
+logo=/cgit.png
 
-# Url loaded when clicking the logo. Value is a url. Default is the index url.
+# Url loaded when clicking the logo. Value is a url. Default is the repository
+# index url.
 #logo-link=/
 
 # File included verbatim at the top of all pages. Value is a filesystem path.
@@ -120,7 +122,7 @@ embedded=0
 #virtual-root=/
 
 # Link format string for submodules in directory listings. Value is a printf
-# format string taking path and sha1. Default is none.
+# format string taking path and object id. Default is none.
 #module-link=/%s/commit/?id=%s
 
 # Directory scanned for git repositories at parse time. Value is a filesystem
@@ -135,34 +137,34 @@ scan-hidden-path=0
 # scan-path. Value is an integer that may be negative. Default is 0.
 section-from-path=0
 
-# Strip the .git suffix from scanned repo url and name. Must precede scan-path.
-# Values are 0 or 1. Default is 0.
+# Strip the .git suffix from a scanned repository's url and name. Must precede
+# scan-path. Values are 0 or 1. Default is 0.
 remove-suffix=0
 
 # File listing subdirs of scan-path to load. Must precede scan-path. Value is a
 # filesystem path that may use macros. Default is none.
 #project-list=/var/lib/git/projects.list
 
-# Serve a repo only if this file exists inside it. Emulates gitweb EXPORT_OK.
-# The reverse needs no setting, a repo containing a file named "noweb" is always
-# skipped by the scan. Must precede scan-path. Value is a filename. Default is
-# none.
+# Serve a repository only if this file exists inside it. Emulates gitweb
+# EXPORT_OK. The reverse needs no setting, a repository containing a file named
+# "noweb" is always skipped by the scan. Must precede scan-path. Value is a
+# filename. Default is none.
 #strict-export=git-daemon-export-ok
 
-# Section heading that subsequently-defined repos inherit. Value is any section
-# heading text. Default is none.
+# Section heading that subsequently defined repositories inherit. Value is any
+# section heading text. Default is none.
 #section=main
 
-# Sort sections and repos within them by name rather than file order. Values are
-# 0 or 1. Default is 0.
+# Sort sections and the repositories within them by name rather than file order.
+# Values are 0 or 1. Default is 0.
 section-sort=0
 
 # How repositories within a section are sorted. Values are name or age. Default
 # is name.
 repository-sort=name
 
-# Let scanned repos set cgit settings via git config using gitweb.* or cgit.*
-# keys. Values are 0 or 1. Default is 0.
+# Let a scanned repository set cgit settings through its git config, using
+# gitweb.* or cgit.* keys. Values are 0 or 1. Default is 0.
 enable-git-config=0
 
 # Include another config file before continuing to parse this one. Value is a
@@ -177,7 +179,7 @@ enable-blame=0
 # Default is 0.
 enable-commit-graph=0
 
-# Allow following a file across renames in the log view. Values are 0 or 1.
+# Allow following a file across renames in the log page. Values are 0 or 1.
 # Default is 0.
 enable-follow-links=0
 
@@ -185,12 +187,12 @@ enable-follow-links=0
 # module-link template covers. Values are 0 or 1. Default is 0.
 enable-gitmodules-links=0
 
-# Generate extra summary, commit and tree links per repo on the index. Values
-# are 0 or 1. Default is 0.
+# Generate extra summary, commit and tree links per repository on the index.
+# Values are 0 or 1. Default is 0.
 enable-index-links=0
 
-# Show the owner of each repo on the index page. Values are 0 or 1. Default is
-# 1.
+# Show the owner of each repository on the index page. Values are 0 or 1.
+# Default is 1.
 enable-index-owner=1
 
 # Show the number of modified files per commit in the log. Values are 0 or 1.
@@ -202,43 +204,43 @@ enable-log-filecount=0
 enable-log-linecount=0
 
 # Apply the .mailmap at HEAD to every author, committer and tagger shown, so a
-# person who changed name or address appears under one identity. Values are 0
-# or 1. Default is 1.
+# person who changed name or address appears under one identity. Values are 0 or
+# 1. Default is 1.
 enable-mailmap=1
 
 # Show ages in the log, refs and index columns as an elapsed time such as "3
 # days" rather than a calendar date. Values are 0 or 1. Default is 1.
 enable-relative-dates=1
 
-# Display remote branches in summary and refs views. Values are 0 or 1. Default
-# is 0.
+# Display remote branches in the summary and refs pages. Values are 0 or 1.
+# Default is 0.
 enable-remote-branches=0
 
 # Use the parent commit subject as link text for parent links. Values are 0 or
 # 1. Default is 0.
 enable-subject-links=0
 
-# Split the trailer block, the Signed-off-by lines and their kin, off the end
-# of a commit message and show it as a table on the commit page. Values are 0
-# or 1. Default is 0.
+# Split the trailer block, the Signed-off-by lines and their kin, off the end of
+# a commit message and show it as a table on the commit page. Values are 0 or 1.
+# Default is 0.
 enable-trailers=0
 
 # Allow /plain to serve HTML mimetypes instead of downgrading to text/plain.
 # Values are 0 or 1. Default is 0.
 enable-html-serving=0
 
-# Generate line-number links for plaintext blobs in the tree view. Values are 0
+# Generate line-number links for plaintext blobs in the tree page. Values are 0
 # or 1. Default is 1.
 enable-tree-linenumbers=1
 
-# List directories first, then files, in the tree view. Values are 0 or 1.
+# List directories first, then files, in the tree page. Values are 0 or 1.
 # Default is 0.
 enable-tree-group-dirs=0
 
 # Enable the statistics page, which counts commits per author, and set the
 # coarsest period it offers. Each value also offers the finer periods before it.
-# Leaving this unset disables statistics. Values are week, month, quarter or
-# year. Default is unset.
+# Leaving it out disables statistics. Values are week, month, quarter or year.
+# Default is none.
 #max-stats=year
 
 # Default set of snapshot archive formats to offer. Value is a space-separated
@@ -249,7 +251,7 @@ enable-tree-group-dirs=0
 # Act as a dumb HTTP endpoint for git clones. Values are 0 or 1. Default is 1.
 enable-http-clone=1
 
-# Prefixes combined with the repo url to build clone urls. Used only when
+# Prefixes combined with the repository url to build clone urls. Used only when
 # repo.clone-url is unset. Value is space-separated url prefixes. Default is
 # none.
 #clone-prefix=https://example.com/git git://example.com
@@ -292,7 +294,7 @@ trust-scan-config=0
 # Value is a command optionally prefixed with exec or lua. Default is none.
 #trailer-filter=lua:/usr/local/lib/cgit/filters/link-trailers.lua
 
-# Filter command used to format plaintext blobs in the tree view. The shipped
+# Filter command used to format plaintext blobs in the tree page. The shipped
 # filter uses the Scintillua lexers and needs lpeg, and missing either means
 # plain uncolored text, not an error. Value is a command optionally prefixed
 # with exec or lua. Default is none.
@@ -307,27 +309,27 @@ trust-scan-config=0
 # Number of items to display in atom feeds. Value is an integer. Default is 10.
 max-atom-items=10
 
-# Max commit message characters shown in the log view. Value is an integer.
+# Max commit message characters shown in the log page. Value is an integer.
 # Default is 80.
 max-message-length=80
 
-# Max repo description characters shown on the index page. Value is an integer.
-# Default is 80.
+# Max repository description characters shown on the index page. Value is an
+# integer. Default is 80.
 max-repodesc-length=80
 
 # Max blob size in KBytes read into memory for html, plain and blob output. A
 # value of 0 disables the limit. Value is an integer. Default is 10240.
 max-blob-size=10240
 
-# Number of repos listed per page on the index. Zero or a negative value shows
-# all repos. Value is an integer. Default is 50.
+# Number of repositories listed per page on the index. Zero or a negative value
+# shows them all. Value is an integer. Default is 50.
 max-repo-count=50
 
-# Number of log entries listed per page in the log view. Value is an integer.
+# Number of log entries listed per page in the log page. Value is an integer.
 # Default is 50.
 max-commit-count=50
 
-# Maximum number of commits the patch view emits as a series for an explicit
+# Maximum number of commits the patch page emits as a series for an explicit
 # revision range. A single commit is unaffected. A value of 0 removes the limit.
 # Value is an integer. Default is 50.
 max-patch-count=50
@@ -338,7 +340,7 @@ max-patch-count=50
 max-diff-files=200
 
 # A file whose diff spans more lines than this is replaced by a link to its own
-# diff page in whole-commit views. A value of 0 always renders it inline. Value
+# diff page in whole-commit pages. A value of 0 always renders it inline. Value
 # is an integer. Default is 1000.
 max-diff-lines=1000
 
@@ -351,15 +353,15 @@ max-ref-count=200
 # compile-time value. Value is an integer. Default is -1.
 rename-limit=-1
 
-# Number of log entries shown in the summary view. Value is an integer. Default
+# Number of log entries shown in the summary page. Value is an integer. Default
 # is 10.
 summary-log=10
 
-# Number of branches shown in the summary view. Value is an integer. Default is
+# Number of branches shown in the summary page. Value is an integer. Default is
 # 10.
 summary-branches=10
 
-# Number of tags shown in the summary view. Value is an integer. Default is 10.
+# Number of tags shown in the summary page. Value is an integer. Default is 10.
 summary-tags=10
 
 # Show side-by-side diffs instead of unidiffs by default. Values are 0 or 1.
@@ -375,14 +377,15 @@ local-time=0
 # carry a -local suffix, plus format:<strftime>. Default is short.
 date-format=short
 
-# Ordering of commits in the log view. Leaving this unset uses the git log
-# default. Values are date or topo. Default is unset.
+# Ordering of commits in the log page. Leaving it out uses the git log default.
+# Values are date or topo. Default is none.
 #commit-sort=date
 
 # Ordering of the branch ref list. Values are name or age. Default is name.
 branch-sort=name
 
-# Sort items in the repo list case-sensitively. Values are 0 or 1. Default is 1.
+# Sort items in the repository list case-sensitively. Values are 0 or 1.
+# Default is 1.
 case-sensitive-sort=1
 
 # Show full author email addresses beside names. Values are 0 or 1. Default is
@@ -390,8 +393,8 @@ case-sensitive-sort=1
 enable-plain-email=1
 
 # File giving the timestamp of the youngest commit. Value is a path relative to
-# the repo. Default is info/web/last-modified.
-#age-file=info/web/last-modified
+# the repository. Default is info/web/last-modified.
+age-file=info/web/last-modified
 
 # Fallback mimetype lookup file for plain output. Value is a filesystem path.
 # Default is none.
@@ -407,152 +410,155 @@ enable-plain-email=1
 #mimetype.svg=image/svg+xml
 
 # Each repository is introduced by a repo.url line. All following repo.*
-# settings apply to that repo until the next repo.url line. When repos are
-# discovered via scan-path the repo. prefix is dropped inside each repo cgitrc
-# and repo.url and repo.path are not allowed there.
+# settings apply to that repository until the next repo.url line. When
+# repositories are discovered via scan-path the repo. prefix is dropped inside
+# each repository's cgitrc, and repo.url and repo.path are not allowed there.
 
-# Relative url for a repo. Must be the first setting of each repo block. Value
-# is a relative url path. Default is none.
+# Relative url for a repository. Must be the first setting of each repository
+# block. Value is a relative url path. Default is none.
 #repo.url=example
 
-# Absolute path to the repository. For a non-bare repo this is the .git dir.
-# Value is an absolute filesystem path. Default is none.
+# Absolute path to the repository. For a non-bare repository this is the .git
+# directory. Value is an absolute filesystem path. Default is none.
 #repo.path=/var/lib/git/example.git
 
-# Display name of the repository. Value is any text. Default is the repo url.
+# Display name of the repository. Value is any text. Default is the repository
+# url.
 #repo.name=example
 
-# Repository description. Value is any text. Default is none.
+# Repository description. Value is any text. Default is "[no description]".
 #repo.desc=An example repository
 
 # Repository owner identifier. Value is any text. Default is none.
 #repo.owner=Jane Doe
 
-# Urls used to clone this repo. Value is space-separated urls that may use
+# Urls used to clone this repository. Value is space-separated urls that may use
 # macros. Default is none.
 #repo.clone-url=https://example.com/example.git git://example.com/example.git
 
-# Default branch for the repo. Falls back to the first sorted branch. Value is a
-# branch name. Default is the HEAD branch, or master.
+# Default branch for the repository. Falls back to the first sorted branch.
+# Value is a branch name. Default is the HEAD branch, or master.
 #repo.defbranch=master
 
-# Override the current section name for this repo. Value is a section name.
-# Default is none.
+# Override the current section name for this repository. Value is a section
+# name. Default is none.
 #repo.section=main
 
-# Prefix for snapshot filenames instead of the repo basename. Value is a prefix
-# string. Default is none.
+# Prefix for snapshot filenames instead of the repository basename. Value is a
+# prefix string. Default is none.
 #repo.snapshot-prefix=example
 
-# Extra content added verbatim to the head of each page for this repo. Value is
-# an HTML fragment. Default is none.
+# Extra content added verbatim to the head of each page for this repository.
+# Value is an HTML fragment. Default is none.
 #repo.head-content=<meta name="example" content="value">
 
-# File included verbatim as the repo About page. A colon-prefixed value uses the
-# head or defbranch. Value is a [ref]path entry. Default is the global readme
-# value.
+# File included verbatim as the repository About page. A colon-prefixed value
+# uses the head or defbranch. Value is a [ref]path entry. Default is the global
+# readme value.
 #repo.readme=:README.md
 
-# Per-repo logo image url. Value is a url. Default is the global logo value.
+# Per-repository logo image url. Value is a url. Default is the global logo
+# value.
 #repo.logo=/cgit.png
 
-# Per-repo logo link target url. Value is a url. Default is the global logo-link
-# value.
+# Per-repository logo link target url. Value is a url. Default is the global
+# logo-link value.
 #repo.logo-link=/
 
-# Per-repo submodule link format string. Value is a printf format string taking
-# path and sha1. Default is the global module-link value.
+# Per-repository submodule link format string. Value is a printf format string
+# taking path and object id. Default is the global module-link value.
 #repo.module-link=/%s/commit/?id=%s
 
 # Submodule link format for a specific submodule path. Value is a printf format
-# string taking sha1. Default is none.
+# string taking an object id. Default is none.
 #repo.module-link.path/to/sub=https://example.com/sub/commit/?id=%s
 
-# Snapshot formats offered for this repo, restricted by the global mask. A value
-# of 0 disables snapshots. Value is snapshot formats. Default is the global
-# snapshots value.
+# Snapshot formats offered for this repository, restricted by the global mask.
+# A value of 0 disables snapshots. Value is snapshot formats. Default is the
+# global snapshots value.
 #repo.snapshots=tar.gz zip
 
-# Hide the repo from the index but still allow direct access. Values are 0 or 1.
-# Default is 0.
+# Hide the repository from the index but still allow direct access. Values are
+# 0 or 1. Default is 0.
 #repo.hide=0
 
-# Ignore the repo entirely so it is not indexed and not directly accessible.
-# Values are 0 or 1. Default is 0.
+# Ignore the repository entirely so it is not indexed and not directly
+# accessible. Values are 0 or 1. Default is 0.
 #repo.ignore=0
 
-# Per-repo override of enable-blame. Values are 0 or 1. Default is the global
-# enable-blame value.
+# Per-repository override of enable-blame. Values are 0 or 1. Default is the
+# global enable-blame value.
 #repo.enable-blame=0
 
-# Per-repo override of enable-commit-graph. Values are 0 or 1. Default is the
-# global enable-commit-graph value.
+# Per-repository override of enable-commit-graph. Values are 0 or 1. Default is
+# the global enable-commit-graph value.
 #repo.enable-commit-graph=0
 
-# Per-repo override of enable-follow-links. Values are 0 or 1. Default is the
-# global enable-follow-links value.
+# Per-repository override of enable-follow-links. Values are 0 or 1. Default is
+# the global enable-follow-links value.
 #repo.enable-follow-links=0
 
-# Per-repo override of enable-gitmodules-links. Values are 0 or 1. Default is
-# the global enable-gitmodules-links value.
+# Per-repository override of enable-gitmodules-links. Values are 0 or 1.
+# Default is the global enable-gitmodules-links value.
 #repo.enable-gitmodules-links=0
 
-# Per-repo override of enable-log-filecount. Values are 0 or 1. Default is the
-# global enable-log-filecount value.
+# Per-repository override of enable-log-filecount. Values are 0 or 1. Default is
+# the global enable-log-filecount value.
 #repo.enable-log-filecount=0
 
-# Per-repo override of enable-log-linecount. Values are 0 or 1. Default is the
-# global enable-log-linecount value.
+# Per-repository override of enable-log-linecount. Values are 0 or 1. Default is
+# the global enable-log-linecount value.
 #repo.enable-log-linecount=0
 
-# Per-repo override of enable-mailmap. Values are 0 or 1. Default is the global
-# enable-mailmap value.
+# Per-repository override of enable-mailmap. Values are 0 or 1. Default is the
+# global enable-mailmap value.
 #repo.enable-mailmap=1
 
-# Per-repo override of enable-remote-branches. Values are 0 or 1. Default is the
-# global enable-remote-branches value.
+# Per-repository override of enable-remote-branches. Values are 0 or 1. Default
+# is the global enable-remote-branches value.
 #repo.enable-remote-branches=0
 
-# Per-repo override of enable-subject-links. Values are 0 or 1. Default is the
-# global enable-subject-links value.
+# Per-repository override of enable-subject-links. Values are 0 or 1. Default is
+# the global enable-subject-links value.
 #repo.enable-subject-links=0
 
-# Per-repo override of enable-trailers. Values are 0 or 1. Default is the
+# Per-repository override of enable-trailers. Values are 0 or 1. Default is the
 # global enable-trailers value.
 #repo.enable-trailers=0
 
-# Per-repo override of enable-html-serving. Values are 0 or 1. Default is the
-# global enable-html-serving value.
+# Per-repository override of enable-html-serving. Values are 0 or 1. Default is
+# the global enable-html-serving value.
 #repo.enable-html-serving=0
 
-# Per-repo branch ref list ordering. Values are name or age. Default is name.
+# Per-repository branch ref list ordering. Values are name or age. Default is
+# name.
 #repo.branch-sort=name
 
-# Per-repo commit log ordering. Leaving this unset uses the git log default.
-# Values are date or topo. Default is unset.
+# Per-repository commit log ordering. Leaving it out uses the git log default.
+# Values are date or topo. Default is none.
 #repo.commit-sort=date
 
-# Per-repo maximum statistics period. A value of 0 disables the statistics page
-# for this repo. Values are week, month, quarter, year or 0. Default is the
-# global max-stats value.
+# Per-repository maximum statistics period. A value of 0 disables the statistics
+# page for this repository. Values are week, month, quarter, year or 0. Default
+# is the global max-stats value.
 #repo.max-stats=week
 
-# Per-repo override of the about-filter. Value is a command. Default is the
-# global about-filter value.
+# Per-repository override of the about-filter. Value is a command. Default is
+# the global about-filter value.
 #repo.about-filter=exec:/path/to/your-command
 
-# Per-repo override of the commit-filter. Value is a command. Default is the
-# global commit-filter value.
+# Per-repository override of the commit-filter. Value is a command. Default is
+# the global commit-filter value.
 #repo.commit-filter=lua:/usr/local/lib/cgit/filters/link-commits.lua
 
-# Per-repo override of the source-filter. Value is a command. Default is the
-# global source-filter value.
+# Per-repository override of the source-filter. Value is a command. Default is
+# the global source-filter value.
 #repo.source-filter=exec:/path/to/your-command
 
-# Per-repo override of the email-filter. Value is a command. Default is the
-# global email-filter value.
+# Per-repository override of the email-filter. Value is a command. Default is
+# the global email-filter value.
 #repo.email-filter=lua:/usr/local/lib/cgit/filters/email-gravatar.lua
 
-# Per-repo override of the trailer-filter. Value is a command. Default is the
-# global trailer-filter value.
+# Per-repository override of the trailer-filter. Value is a command. Default is
+# the global trailer-filter value.
 #repo.trailer-filter=lua:/usr/local/lib/cgit/filters/link-trailers.lua