[RFC/PATCHv3 0/5] Improving gitweb documentation, creating manpages

[RFC/PATCHv3 0/5] Improving gitweb documentation, creating manpages

[Jakub Narebski]

This is yet a work in progress.

0. The first three patches are improvements to gitweb's INSTALL and
README files, before moving or copying most of the contents to
gitweb.txt and gitweb.conf.txt i.e. newly introduced gitweb's
manpages.

The first two were sent to git mailing list as

  [PATCH 0/2] Improving gitweb documentation
  http://thread.gmane.org/gmane.comp.version-control.git/174954

Third one was sent as reply in thread mentioned above

  [PATCH 3/2] gitweb: Move "Requirements" up in gitweb/INSTALL
  http://thread.gmane.org/gmane.comp.version-control.git/174954/focus=175016

1. The man page for /etc/gitweb.conf is modified, extended and
improved version of patch by Drew Northup from

  "[PATCH/WIP] Starting work on a man page for /etc/gitweb.conf"
  http://thread.gmane.org/gmane.comp.version-control.git/173422

Drew version was mostly pulled directly from the README and INSTALL
files of gitweb.  I have tried to incorporate comments in mentioned
thread, and to group config variables by category.

This version now moves, rather than copies, contents from
gitweb/README file.

2. The man page for gitweb is slightly extended version of patch I
have sent to git mailing list as

  "[RFC/PATCH] gitweb: Starting work on a man page for gitweb (WIP)"
  http://thread.gmane.org/gmane.comp.version-control.git/173422/focus=173625

This version now moves, rather than copies, contents from
gitweb/README and gitweb/INSTALL files.

......................................................................

The part that is left is turn references to chapters/sections into
hyperlinks, fix and unify AsciiDoc formatting (it is quite
inconsistent now), checking for leftover unintended duplication,
cleaning up gitweb/README.

NOTE also that I have only tested that both generated manpages _looks_
(halfway) reasonable.  I didn't check HTML output.


Those commits also available in 'gitweb/doc' branch in both of my
repositories:

  git://repo.or.cz/git/jnareb-git.git
  git://github.com/jnareb/git.git


Shortlog:
~~~~~~~~~
Drew Northup (1):
  gitweb: Starting work on a man page for /etc/gitweb.conf (WIP)

The one that started this.  Drew, could you comment on this thread?
Thanks in advance.

Jakub Narebski (4):
  gitweb: Move information about installation from README to INSTALL
  gitweb: Describe CSSMIN and JSMIN in gitweb/INSTALL
  gitweb: Move "Requirements" up in gitweb/INSTALL
  gitweb: Starting work on a man page for gitweb (WIP)

My contributions.

Table of contents:
~~~~~~~~~~~~~~~~~~
 [PATCHv3 1/5] gitweb: Move information about installation from
 [PATCHv3 2/5] gitweb: Describe CSSMIN and JSMIN in gitweb/INSTALL
 [PATCHv3 3/5] gitweb: Move "Requirements" up in gitweb/INSTALL
 [RFC/PATCHv3 4/5] gitweb: Starting work on a man page for /etc/gitweb.conf (WIP)
 [RFC/PATCHv3 5/5] gitweb: Starting work on a man page for gitweb (WIP)

Diffstat:
~~~~~~~~~
 Documentation/Makefile        |    9 +-
 Documentation/gitweb.conf.txt |  724 +++++++++++++++++++++++++++++++++++++++++
 Documentation/gitweb.txt      |  702 +++++++++++++++++++++++++++++++++++++++
 gitweb/INSTALL                |  246 ++++++++------
 gitweb/Makefile               |    7 +-
 gitweb/README                 |  519 +----------------------------
 6 files changed, 1599 insertions(+), 608 deletions(-)
 create mode 100644 Documentation/gitweb.conf.txt
 create mode 100644 Documentation/gitweb.txt

Dirstat:
~~~~~~~~
  62.4% Documentation/
  37.5% gitweb/
-- 
1.7.5

[PATCHv3 1/5] gitweb: Move information about installation from README to INSTALL

[Jakub Narebski]

Almost straightformard moving of "How to configure gitweb for your
local system" section from gitweb/README to gitweb/INSTALL, as it is
about build time configuration.  Updated references to it.

Signed-off-by: Jakub Narebski <jnareb@gmail.com>
---
No differences from previous version.

 gitweb/INSTALL |  115 +++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 gitweb/README  |  114 -------------------------------------------------------
 2 files changed, 113 insertions(+), 116 deletions(-)

diff --git a/gitweb/INSTALL b/gitweb/INSTALL
index 4964a67..32a52b7 100644
--- a/gitweb/INSTALL
+++ b/gitweb/INSTALL
@@ -28,8 +28,7 @@ scripts).
 Build time configuration
 ------------------------
 
-See also "How to configure gitweb for your local system" in README
-file for gitweb (in gitweb/README).
+See also "How to configure gitweb for your local system" section below.
 
 - There are many configuration variables which affect building of
   gitweb.cgi; see "default configuration for gitweb" section in main
@@ -73,6 +72,118 @@ file for gitweb (in gitweb/README).
   substitute gitweb.min.js and gitweb.min.css for all uses of gitweb.js and
   gitweb.css in the help files.
 
+
+How to configure gitweb for your local system
+---------------------------------------------
+
+You can specify the following configuration variables when building GIT:
+
+ * GIT_BINDIR
+   Points where to find the git executable.  You should set it up to
+   the place where the git binary was installed (usually /usr/bin) if you
+   don't install git from sources together with gitweb.  [Default: $(bindir)]
+ * GITWEB_SITENAME
+   Shown in the title of all generated pages, defaults to the server name
+   (SERVER_NAME CGI environment variable) if not set. [No default]
+ * GITWEB_PROJECTROOT
+   The root directory for all projects shown by gitweb. Must be set
+   correctly for gitweb to find repositories to display.  See also
+   "Gitweb repositories" in the INSTALL file for gitweb.  [Default: /pub/git]
+ * GITWEB_PROJECT_MAXDEPTH
+   The filesystem traversing limit for getting the project list; the number
+   is taken as depth relative to the projectroot.  It is used when
+   GITWEB_LIST is a directory (or is not set; then project root is used).
+   This is meant to speed up project listing on large work trees by limiting
+   search depth.  [Default: 2007]
+ * GITWEB_LIST
+   Points to a directory to scan for projects (defaults to project root
+   if not set / if empty) or to a file with explicit listing of projects
+   (together with projects' ownership). See "Generating projects list
+   using gitweb" in INSTALL file for gitweb to find out how to generate
+   such file from scan of a directory. [No default, which means use root
+   directory for projects]
+ * GITWEB_EXPORT_OK
+   Show repository only if this file exists (in repository).  Only
+   effective if this variable evaluates to true.  [No default / Not set]
+ * GITWEB_STRICT_EXPORT
+   Only allow viewing of repositories also shown on the overview page.
+   This for example makes GITWEB_EXPORT_OK to decide if repository is
+   available and not only if it is shown.  If GITWEB_LIST points to
+   file with list of project, only those repositories listed would be
+   available for gitweb.  [No default]
+ * GITWEB_HOMETEXT
+   Points to an .html file which is included on the gitweb project
+   overview page ('projects_list' view), if it exists.  Relative to
+   gitweb.cgi script.  [Default: indextext.html]
+ * GITWEB_SITE_HEADER
+   Filename of html text to include at top of each page.  Relative to
+   gitweb.cgi script.  [No default]
+ * GITWEB_SITE_FOOTER
+   Filename of html text to include at bottom of each page.  Relative to
+   gitweb.cgi script.  [No default]
+ * GITWEB_HOME_LINK_STR
+   String of the home link on top of all pages, leading to $home_link
+   (usually main gitweb page, which means projects list).  Used as first
+   part of gitweb view "breadcrumb trail": <home> / <project> / <view>.
+   [Default: projects]
+ * GITWEB_SITENAME
+   Name of your site or organization to appear in page titles.  Set it
+   to something descriptive for clearer bookmarks etc.  If not set
+   (if empty) gitweb uses "$SERVER_NAME Git", or "Untitled Git" if
+   SERVER_NAME CGI environment variable is not set (e.g. if running
+   gitweb as standalone script).  [No default]
+ * GITWEB_BASE_URL
+   Git base URLs used for URL to where fetch project from, i.e. full
+   URL is "$git_base_url/$project".  Shown on projects summary page.
+   Repository URL for project can be also configured per repository; this
+   takes precedence over URLs composed from base URL and a project name.
+   Note that you can setup multiple base URLs (for example one for
+   git:// protocol access, another for http:// access) from the gitweb
+   config file.  [No default]
+ * GITWEB_CSS
+   Points to the location where you put gitweb.css on your web server
+   (or to be more generic, the URI of gitweb stylesheet).  Relative to the
+   base URI of gitweb.  Note that you can setup multiple stylesheets from
+   the gitweb config file.  [Default: static/gitweb.css (or
+   static/gitweb.min.css if the CSSMIN variable is defined / CSS minifier
+   is used)]
+ * GITWEB_LOGO
+   Points to the location where you put git-logo.png on your web server
+   (or to be more generic URI of logo, 72x27 size, displayed in top right
+   corner of each gitweb page, and used as logo for Atom feed).  Relative
+   to base URI of gitweb.  [Default: static/git-logo.png]
+ * GITWEB_FAVICON
+   Points to the location where you put git-favicon.png on your web server
+   (or to be more generic URI of favicon, assumed to be image/png type;
+   web browsers that support favicons (website icons) may display them
+   in the browser's URL bar and next to site name in bookmarks).  Relative
+   to base URI of gitweb.  [Default: static/git-favicon.png]
+ * GITWEB_JS
+   Points to the location where you put gitweb.js on your web server
+   (or to be more generic URI of JavaScript code used by gitweb).
+   Relative to base URI of gitweb.  [Default: static/gitweb.js (or
+   static/gitweb.min.js if JSMIN build variable is defined / JavaScript
+   minifier is used)]
+ * GITWEB_CONFIG
+   This Perl file will be loaded using 'do' and can be used to override any
+   of the options above as well as some other options -- see the "Runtime
+   gitweb configuration" section below, and top of 'gitweb.cgi' for their
+   full list and description.  If the environment variable GITWEB_CONFIG
+   is set when gitweb.cgi is executed, then the file specified in the
+   environment variable will be loaded instead of the file specified
+   when gitweb.cgi was created.  [Default: gitweb_config.perl]
+ * GITWEB_CONFIG_SYSTEM
+   This Perl file will be loaded using 'do' as a fallback if GITWEB_CONFIG
+   does not exist.  If the environment variable GITWEB_CONFIG_SYSTEM is set
+   when gitweb.cgi is executed, then the file specified in the environment
+   variable will be loaded instead of the file specified when gitweb.cgi was
+   created.  [Default: /etc/gitweb.conf]
+ * HIGHLIGHT_BIN
+   Path to the highlight executable to use (must be the one from
+   http://www.andre-simon.de due to assumptions about parameters and output).
+   Useful if highlight is not installed on your webserver's PATH.
+   [Default: highlight]
+
 Build example
 ~~~~~~~~~~~~~
 
diff --git a/gitweb/README b/gitweb/README
index a3a697b..a4cfcb4 100644
--- a/gitweb/README
+++ b/gitweb/README
@@ -7,120 +7,6 @@ The one working on:
 From the git version 1.4.0 gitweb is bundled with git.
 
 
-How to configure gitweb for your local system
----------------------------------------------
-
-See also the "Build time configuration" section in the INSTALL
-file for gitweb (in gitweb/INSTALL).
-
-You can specify the following configuration variables when building GIT:
- * GIT_BINDIR
-   Points where to find the git executable.  You should set it up to
-   the place where the git binary was installed (usually /usr/bin) if you
-   don't install git from sources together with gitweb.  [Default: $(bindir)]
- * GITWEB_SITENAME
-   Shown in the title of all generated pages, defaults to the server name
-   (SERVER_NAME CGI environment variable) if not set. [No default]
- * GITWEB_PROJECTROOT
-   The root directory for all projects shown by gitweb. Must be set
-   correctly for gitweb to find repositories to display.  See also
-   "Gitweb repositories" in the INSTALL file for gitweb.  [Default: /pub/git]
- * GITWEB_PROJECT_MAXDEPTH
-   The filesystem traversing limit for getting the project list; the number
-   is taken as depth relative to the projectroot.  It is used when
-   GITWEB_LIST is a directory (or is not set; then project root is used).
-   This is meant to speed up project listing on large work trees by limiting
-   search depth.  [Default: 2007]
- * GITWEB_LIST
-   Points to a directory to scan for projects (defaults to project root
-   if not set / if empty) or to a file with explicit listing of projects
-   (together with projects' ownership). See "Generating projects list
-   using gitweb" in INSTALL file for gitweb to find out how to generate
-   such file from scan of a directory. [No default, which means use root
-   directory for projects]
- * GITWEB_EXPORT_OK
-   Show repository only if this file exists (in repository).  Only
-   effective if this variable evaluates to true.  [No default / Not set]
- * GITWEB_STRICT_EXPORT
-   Only allow viewing of repositories also shown on the overview page.
-   This for example makes GITWEB_EXPORT_OK to decide if repository is
-   available and not only if it is shown.  If GITWEB_LIST points to
-   file with list of project, only those repositories listed would be
-   available for gitweb.  [No default]
- * GITWEB_HOMETEXT
-   Points to an .html file which is included on the gitweb project
-   overview page ('projects_list' view), if it exists.  Relative to
-   gitweb.cgi script.  [Default: indextext.html]
- * GITWEB_SITE_HEADER
-   Filename of html text to include at top of each page.  Relative to
-   gitweb.cgi script.  [No default]
- * GITWEB_SITE_FOOTER
-   Filename of html text to include at bottom of each page.  Relative to
-   gitweb.cgi script.  [No default]
- * GITWEB_HOME_LINK_STR
-   String of the home link on top of all pages, leading to $home_link
-   (usually main gitweb page, which means projects list).  Used as first
-   part of gitweb view "breadcrumb trail": <home> / <project> / <view>.
-   [Default: projects]
- * GITWEB_SITENAME
-   Name of your site or organization to appear in page titles.  Set it
-   to something descriptive for clearer bookmarks etc.  If not set
-   (if empty) gitweb uses "$SERVER_NAME Git", or "Untitled Git" if
-   SERVER_NAME CGI environment variable is not set (e.g. if running
-   gitweb as standalone script).  [No default]
- * GITWEB_BASE_URL
-   Git base URLs used for URL to where fetch project from, i.e. full
-   URL is "$git_base_url/$project".  Shown on projects summary page.
-   Repository URL for project can be also configured per repository; this
-   takes precedence over URLs composed from base URL and a project name.
-   Note that you can setup multiple base URLs (for example one for
-   git:// protocol access, another for http:// access) from the gitweb
-   config file.  [No default]
- * GITWEB_CSS
-   Points to the location where you put gitweb.css on your web server
-   (or to be more generic, the URI of gitweb stylesheet).  Relative to the
-   base URI of gitweb.  Note that you can setup multiple stylesheets from
-   the gitweb config file.  [Default: static/gitweb.css (or
-   static/gitweb.min.css if the CSSMIN variable is defined / CSS minifier
-   is used)]
- * GITWEB_LOGO
-   Points to the location where you put git-logo.png on your web server
-   (or to be more generic URI of logo, 72x27 size, displayed in top right
-   corner of each gitweb page, and used as logo for Atom feed).  Relative
-   to base URI of gitweb.  [Default: static/git-logo.png]
- * GITWEB_FAVICON
-   Points to the location where you put git-favicon.png on your web server
-   (or to be more generic URI of favicon, assumed to be image/png type;
-   web browsers that support favicons (website icons) may display them
-   in the browser's URL bar and next to site name in bookmarks).  Relative
-   to base URI of gitweb.  [Default: static/git-favicon.png]
- * GITWEB_JS
-   Points to the location where you put gitweb.js on your web server
-   (or to be more generic URI of JavaScript code used by gitweb).
-   Relative to base URI of gitweb.  [Default: static/gitweb.js (or
-   static/gitweb.min.js if JSMIN build variable is defined / JavaScript
-   minifier is used)]
- * GITWEB_CONFIG
-   This Perl file will be loaded using 'do' and can be used to override any
-   of the options above as well as some other options -- see the "Runtime
-   gitweb configuration" section below, and top of 'gitweb.cgi' for their
-   full list and description.  If the environment variable GITWEB_CONFIG
-   is set when gitweb.cgi is executed, then the file specified in the
-   environment variable will be loaded instead of the file specified
-   when gitweb.cgi was created.  [Default: gitweb_config.perl]
- * GITWEB_CONFIG_SYSTEM
-   This Perl file will be loaded using 'do' as a fallback if GITWEB_CONFIG
-   does not exist.  If the environment variable GITWEB_CONFIG_SYSTEM is set
-   when gitweb.cgi is executed, then the file specified in the environment
-   variable will be loaded instead of the file specified when gitweb.cgi was
-   created.  [Default: /etc/gitweb.conf]
- * HIGHLIGHT_BIN
-   Path to the highlight executable to use (must be the one from
-   http://www.andre-simon.de due to assumptions about parameters and output).
-   Useful if highlight is not installed on your webserver's PATH.
-   [Default: highlight]
-
-
 Runtime gitweb configuration
 ----------------------------
 
-- 
1.7.5

[PATCHv3 2/5] gitweb: Describe CSSMIN and JSMIN in gitweb/INSTALL

[Jakub Narebski]

The build-time configuration variables JSMIN and CSSMIN were mentioned
only in Makefile; add their description to gitweb/INSTALL.

This required moving description of GITWEB_JS up, near GITWEB_CSS and
just introduced CSMIN and JSMIN.

Signed-off-by: Jakub Narebski <jnareb@gmail.com>
---
No differences from previous version.

 gitweb/INSTALL |   19 +++++++++++++------
 1 files changed, 13 insertions(+), 6 deletions(-)

diff --git a/gitweb/INSTALL b/gitweb/INSTALL
index 32a52b7..2346aad 100644
--- a/gitweb/INSTALL
+++ b/gitweb/INSTALL
@@ -147,6 +147,19 @@ You can specify the following configuration variables when building GIT:
    the gitweb config file.  [Default: static/gitweb.css (or
    static/gitweb.min.css if the CSSMIN variable is defined / CSS minifier
    is used)]
+ * GITWEB_JS
+   Points to the location where you put gitweb.js on your web server
+   (or to be more generic URI of JavaScript code used by gitweb).
+   Relative to base URI of gitweb.  [Default: static/gitweb.js (or
+   static/gitweb.min.js if JSMIN build variable is defined / JavaScript
+   minifier is used)]
+ * CSSMIN, JSMIN
+   Invocation of a CSS minifier or a JavaScript minifier, respectively,
+   working as a filter (source on standard input, minified result on
+   standard output).  If set, it is used to generate a minified version of
+   'static/gitweb.css' or 'static/gitweb.js', respectively.  *Note* that
+   minified files would have *.min.css and *.min.js extension, which is
+   important if you also set GITWEB_CSS and/or GITWEB_JS.  [No default]
  * GITWEB_LOGO
    Points to the location where you put git-logo.png on your web server
    (or to be more generic URI of logo, 72x27 size, displayed in top right
@@ -158,12 +171,6 @@ You can specify the following configuration variables when building GIT:
    web browsers that support favicons (website icons) may display them
    in the browser's URL bar and next to site name in bookmarks).  Relative
    to base URI of gitweb.  [Default: static/git-favicon.png]
- * GITWEB_JS
-   Points to the location where you put gitweb.js on your web server
-   (or to be more generic URI of JavaScript code used by gitweb).
-   Relative to base URI of gitweb.  [Default: static/gitweb.js (or
-   static/gitweb.min.js if JSMIN build variable is defined / JavaScript
-   minifier is used)]
  * GITWEB_CONFIG
    This Perl file will be loaded using 'do' and can be used to override any
    of the options above as well as some other options -- see the "Runtime
-- 
1.7.5

[PATCHv3 3/5] gitweb: Move "Requirements" up in gitweb/INSTALL

[Jakub Narebski]

This way you can examine prerequisites at first glance, before
detailed instructions on installing gitweb.  Straightforward code
movement.

Signed-off-by: Jakub Narebski <jnareb@gmail.com>
---
No differences from previous version.

 gitweb/INSTALL |   30 +++++++++++++++---------------
 1 files changed, 15 insertions(+), 15 deletions(-)

diff --git a/gitweb/INSTALL b/gitweb/INSTALL
index 2346aad..c5236fe 100644
--- a/gitweb/INSTALL
+++ b/gitweb/INSTALL
@@ -25,6 +25,21 @@ The above example assumes that your web server is configured to run
 scripts).
 
 
+Requirements
+------------
+
+ - Core git tools
+ - Perl
+ - Perl modules: CGI, Encode, Fcntl, File::Find, File::Basename.
+ - web server
+
+The following optional Perl modules are required for extra features
+ - Digest::MD5 - for gravatar support
+ - CGI::Fast and FCGI - for running gitweb as FastCGI script
+ - HTML::TagCloud - for fancy tag cloud in project list view
+ - HTTP::Date or Time::ParseDate - to support If-Modified-Since for feeds
+
+
 Build time configuration
 ------------------------
 
@@ -347,21 +362,6 @@ $projects_list variable in gitweb config):
 	perl -- /var/www/cgi-bin/gitweb.cgi
 
 
-Requirements
-------------
-
- - Core git tools
- - Perl
- - Perl modules: CGI, Encode, Fcntl, File::Find, File::Basename.
- - web server
-
-The following optional Perl modules are required for extra features
- - Digest::MD5 - for gravatar support
- - CGI::Fast and FCGI - for running gitweb as FastCGI script
- - HTML::TagCloud - for fancy tag cloud in project list view
- - HTTP::Date or Time::ParseDate - to support If-Modified-Since for feeds
-
-
 Example web server configuration
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- 
1.7.5

[RFC/PATCHv3 4/5] gitweb: Starting work on a man page for /etc/gitweb.conf (WIP)

[Jakub Narebski]

From: Drew Northup <drew.northup@maine.edu>

This is a work in progress. Much of what is in it has been pulled
directly from the README and INSTALL files of gitweb. Some effort has
been made to de-duplicate any of this.

To build gitweb documentation you can use

  make -C gitweb doc

or

  cd gitweb; make doc

TODO:
  * Clean up README and INSTALL files
  * Remove or rephrase redundant portions of original documentation
  * A lot more...

Signed-off-by: Drew Northup <drew.northup@maine.edu>
Signed-off-by: Jakub Narebski <jnareb@gmail.com>
---
Differences from previous version (v2):

* Much simpler "doc" target in gitweb/Makefile.  Now instead of
  duplicating internal knowledge how Documentation/Makefile works we
  simply delegate task to "gitweb-doc" target (a la "full-svn-test"
  in t/Makefile) in Documentation/Makefile.

  The "gitweb-doc" target is implemented in 2 lines, compared to
  previous version which needed 7 lines in gitweb's Makefile.

  Thanks Junio for this bit of sanity.

* Added documentation: $project_maxdepth, %highlight_ext etc., new
  after rebase $project_list_group_categories etc.

* New chapter "Configuring gitweb features" about %feature hash. 

* Link to non-existent yet linkgit:gitweb[1] (introduced in next commit).

* Removed duplicated contents from gitweb/README

- By accident moved change to git.spec.in to next commit.  But perhaps
  it is better here, or even better in a separate commit on top of
  series.

 Documentation/Makefile        |    7 +-
 Documentation/gitweb.conf.txt |  716 +++++++++++++++++++++++++++++++++++++++++
 gitweb/Makefile               |    7 +-
 gitweb/README                 |  133 +--------
 4 files changed, 728 insertions(+), 135 deletions(-)
 create mode 100644 Documentation/gitweb.conf.txt

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 36989b7..68d0ebb 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -3,7 +3,7 @@ MAN1_TXT= \
 		$(wildcard git-*.txt)) \
 	gitk.txt git.txt
 MAN5_TXT=gitattributes.txt gitignore.txt gitmodules.txt githooks.txt \
-	gitrepository-layout.txt
+	gitrepository-layout.txt gitweb.conf.txt
 MAN7_TXT=gitcli.txt gittutorial.txt gittutorial-2.txt \
 	gitcvs-migration.txt gitcore-tutorial.txt gitglossary.txt \
 	gitdiffcore.txt gitrevisions.txt gitworkflows.txt
@@ -170,6 +170,9 @@ info: git.info gitman.info
 
 pdf: user-manual.pdf
 
+GITWEB_DOC = $(filter gitweb.%,$(DOC_HTML) $(DOC_MAN1) $(DOC_MAN5) $(DOC_MAN7))
+gitweb-doc: $(GITWEB_DOC)
+
 install: install-man
 
 install-man: man
@@ -334,4 +337,4 @@ quick-install-man:
 quick-install-html:
 	'$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(HTML_REF) $(DESTDIR)$(htmldir)
 
-.PHONY: FORCE
+.PHONY: FORCE gitweb-doc
diff --git a/Documentation/gitweb.conf.txt b/Documentation/gitweb.conf.txt
new file mode 100644
index 0000000..2bfe2e5
--- /dev/null
+++ b/Documentation/gitweb.conf.txt
@@ -0,0 +1,716 @@
+gitweb.conf(5)
+==============
+
+NAME
+----
+gitweb.conf - Gitweb configuration file
+
+SYNOPSIS
+--------
+[verse]
+'/etc/gitweb.conf'
+'$GITWEBDIR/gitweb_config.perl'
+
+DESCRIPTION
+-----------
+The gitweb CGI script for viewing Git repositories over the web uses a
+perl script fragment as its configuration file.  You can set variables
+using "`our $variable = value`"; text from a "#" character until the
+end of a line is ignored.  See *perlsyn*(1) for details.
+
+An example:
+
+    # gitweb configuration file for http://git.example.org
+    #
+    our $projectroot = "/srv/git"; # FHS recommendation
+    our $site_name = 'Example.org >> Repos';
+
+
+The configuration file is used to override the default settings that
+were built into gitweb at the time 'gitweb.cgi' script was generated.
+
+While one could just alter the configuration settings in the gitweb
+CGI itself, those changes would be lost upon upgrade.  Configuration
+settings might also be placed into a file in the same directory as the
+CGI script with the default name 'gitweb_config.perl' -- allowing
+one to have multiple gitweb instances with different configurations by
+the use of symlinks.
+
+
+DISCUSSION
+----------
+The location of system-wide gitweb configuration file is defined at compile
+time using the configuration value `GITWEB_CONFIG_SYSTEM` and defaults to
+'/etc/gitweb.conf'.  The name of the per-instance configuration file is
+defined in gitweb by `GITWEB_CONFIG`, and defaults to 'gitweb_config.perl'
+(relative path means located in the same directory gitweb is installed).
+System-wide configuration file is a fallback for when per-instance
+configuration file does not exist.
+
+You can override location of both system-wide and per-instance configuration
+file by setting respectively environmental variables `GITWEB_CONFIG_SYSTEM`
+and `GITWEB_CONFIG` to non-empty value.
+
+Values defined in configuration files override built-in values found in the
+gitweb CGI.
+
+*NOTE:* If per-instance configuration file ('gitweb_config.perl') exists,
+then system-wide configuration file ('/etc/gitweb.conf') is _not used at
+all_!!!
+
+The syntax of the configuration files is that of Perl, as these files are
+indeed handled as fragments of Perl code (the language that gitweb itself is
+written in). Variables may be set using "`our $variable = value`"; text from
+"#" character until the end of a line is ignored. See the *perlsyn*(1) man
+page for more information.
+
+Actually using `our` qualifier in `our $variable = <value>;` is a safety
+check: if newer gitweb does no longer use given variable, by using `our` we
+won't get syntax errors.
+
+The default configuration with no configuration file at all may work
+perfectly well for some installations.  Still, a configuration file is
+useful for customizing or tweaking the behavior of gitweb in many ways, and
+some optional features will not be present unless explicitly enabled using
+the configurable `%features` variable (see also "Configuring gitweb
+features" section below).
+
+
+CONFIGURATION VARIABLES
+-----------------------
+Some of configuration variables have their default values (embedded in CGI
+file) set during building gitweb -- if that is the case, it is put in their
+description.  See gitweb's 'INSTALL' file for instructions on building and
+installing gitweb.
+
+Location of repositories
+~~~~~~~~~~~~~~~~~~~~~~~~
+Configuration variables described below control finding git repositories by
+gitweb, and control display and access to repositories.
+
+$projectroot::
+	Absolute filesystem path which will be prepended to project path;
+	the path to repository is `$projectroot/$project`.  Set to
+	`$GITWEB_PROJECTROOT` during installation.  This variable has to be
+	set correctly for gitweb to find repositories.
++
+For example if `$projectroot` is set to "/srv/git" by putting the following
+in gitweb config file:
+----------------------------------------------------------------------------
+our $projectroot = "/srv/git";
+----------------------------------------------------------------------------
+then
+------------------------------------------------
+http://git.example.com/gitweb.cgi?p=foo/bar.git
+------------------------------------------------
+or its path_info based equivalent
+------------------------------------------------
+http://git.example.com/gitweb.cgi/foo/bar.git
+------------------------------------------------
+will map to path '/srv/git/foo/bar.git' on filesystem.
+
+$project_maxdepth::
+	Filesystem traversing depth limit for recursively scanning for git
+	repositories, used if `$projects_list` (below) is unset.  The default
+	value of this variable is determined by build-time configuration
+	variable `GITWEB_PROJECT_MAXDEPTH`, which defaults to 2007.
+
+$projects_list::
+	Plain text file listing projects or name of directory
+	to be scanned for projects.
+
+	Project list files should list one project per line, with each line
+	having the following format
+-----------------------------------------------------------------------------
+<URI-encoded filesystem path to repository> SP <URI-encoded repository owner>
+-----------------------------------------------------------------------------
+
+The default value of this variable is determined by the `GITWEB_LIST`
+makefile variable at installation time.  If this variable is empty, gitweb
+will fall back to scanning the `$projectroot` directory for repositories.
+
+$export_ok::
+	Show repository only if this file exists (in repository).  Only
+	effective if this variable evaluates to true.  Can be set during
+	building gitweb via `GITWEB_EXPORT_OK`.  [No default / Not set]
+$export_auth_hook::
+	Show repository only if this subroutine returns true, when given as
+	the only parameter the full path to the project.  Example:
+----------------------------------------------------------------------------
+our $export_auth_hook = sub { return -e "$_[0]/git-daemon-export-ok"; };
+----------------------------------------------------------------------------
+though the above might be done by using `$export_ok` instead
+----------------------------------------------------------------------------
+our $export_ok = "git-daemon-export-ok";
+----------------------------------------------------------------------------
+
+$strict_export::
+	Only allow viewing of repositories also shown on the overview page.
+	This for example makes `$gitweb_export_ok` file decide if repository is
+	available and not only if it is shown.  If `$gitweb_list` points to
+	file with list of project, only those repositories listed would be
+	available for gitweb.  Can be set during building gitweb via
+	`GITWEB_STRICT_EXPORT`.  [No default / Not set]
+
+Finding files
+~~~~~~~~~~~~~
+Those configuration variables tell gitweb where to find files.  Values of
+those variables are paths on filesystem.  Of those only `$GIT` is required
+to be (correctly) set for gitweb to be able to work; all the rest are
+required only for extra configuration or extra features.
+
+$GIT::
+	Core git executable to use.  By default set to `$GIT_BINDIR/git`, which
+	in turn is by default set to `$(bindir)/git`.  If you use git from binary
+	package, set this to "/usr/bin/git".  This can just be "git" if your
+	webserver has a sensible PATH.  If you have multiple git versions installed
+	it can be used to choose which one to use.
+$mimetypes_file::
+	File to use for (filename extension based) guessing of MIME types before
+	trying '/etc/mime.types'.  Path, if relative, is taken currently as
+	relative to the current git repository.  [Unset by default]
+$highlight_bin::
+	Path to the highlight executable to use (must be the one from
+	http://www.andre-simon.de due to assumptions about parameters and output).
+	Useful if 'highlight' is not installed on your webserver's PATH.
+
+	*Note* that if you want to add support for new syntax (supported by
+	"highlight" but not used by gitweb), you need to modify `%highlight_ext`
+	or `%highlight_basename`, depending on whether you detect type of file
+	based on extension (for example "*.sh") or on its basename (for example
+	"Makefile").  Keys of those hashes are extension or basename,
+	respectively, and value for given key is name of syntax to be passed via
+	`--syntax <syntax>` to highlighter.
+
+	[Default: 'highlight']
+
+Links and their targets
+~~~~~~~~~~~~~~~~~~~~~~~
+Configuration variables described below configure some of gitweb links:
+their target and their look (text or image), and where to find page
+prerequisites (stylesheet, favicon, images, scripts).  Usually they are left
+at their default values, with the possible exception of `@stylesheets`
+variable.
+
+@stylesheets::
+	List of URIs of stylesheets (relative to base URI of a page). You
+	might specify more than one stylesheet, for example use gitweb.css
+	as base, with site specific modifications in separate stylesheet
+	to make it easier to upgrade gitweb. You can add a `site` stylesheet
+	for example by putting
+----------------------------------------------------------------------------
+push @stylesheets, "gitweb-site.css";
+----------------------------------------------------------------------------
+in the gitweb config file.  Those values that are relative paths, are
+relative to base URI of gitweb.
+
+This list should contain URI of gitweb's stylesheet.  The URI of gitweb
+stylesheet is set during build time via `GITWEB_CSS` variable.  It's default
+value is 'static/gitweb.css' (or 'static/gitweb.min.css' if the `CSSMIN`
+variable is defined, i.e. if CSS minifier is used during build.
+
+*Note*: there is also legacy `$stylesheet` configuration variable, which was
+used by older gitweb.
+
+$logo::
+	Points to the location where you put 'git-logo.png' on your web
+	server, or to be more generic URI of logo, 72x27 size).  This image
+	is displayed in top right corner of each gitweb page, and used as
+	logo for Atom feed.  Relative to base URI of gitweb (as a path).
+	Can be adjusted during building gitweb using `GITWEB_LOGO` variable
++
+	[Default: 'static/git-logo.png']
+
+$favicon::
+	Points to the location where you put 'git-favicon.png' on your web
+	server, or to be more generic URI of favicon, assumed to be
+	"image/png" type; web browsers that support favicons (website icons)
+	may display them in the browser's URL bar and next to site name in
+	bookmarks.  Relative to base URI of gitweb.  Can be adjusted during
+	build time using `GITWEB_FAVICON` variable.
++
+	[Default: 'static/git-favicon.png']
+
+$javascript::
+	Points to the location where you put 'gitweb.js' on your web server,
+	or to be more generic URI of JavaScript code used by gitweb.
+	Relative to base URI of gitweb.  Set during build time using
+	`GITWEB_JS` build-time configuration variable.
++
+Default value is either 'static/gitweb.js', or 'static/gitweb.min.js' if
+`JSMIN` build variable is defined, i.e. if JavaScript minifier is used
+during build.  *Note* that this single file is build (composed) of
+individual JavaScript "modules".
+
+$home_link::
+	Target of the home link on top of all pages (the first part of view
+	"breadcrumbs").  By default set to absolute URI of a page ($my_uri).
+$home_link_str::
+	Description of the home link on top of all pages, leading to $home_link
+	(usually main gitweb page, which means projects list).  Used as first
+	part of gitweb view "breadcrumb trail": `<home> / <project> / <view>`.
+	Can be set during build time using `GITWEB_HOME_LINK_STR` variable.
+	[Default: "projects"]
+$logo_url::
+$logo_label::
+	URI and label (title) of GIT logo link (or your site logo, if you choose
+	to use different logo image). By default they point to git homepage;
+	in the past they pointed to git documentation at www.kernel.org.
+
+Changing gitweb look
+~~~~~~~~~~~~~~~~~~~~
+You can adjust how pages generated by gitweb look using variables described
+below.  You can change site name, add common headers and footers for all
+pages, and add description of gitweb installation on its main page (which is
+projects list page), etc.
+
+$site_name::
+	Name of your site or organization to appear in page titles.  Set it
+	to something descriptive for clearer bookmarks etc.  If not set (if
+	empty) then gitweb uses value of `SERVER_NAME` CGI environment
+	variable setting prefix of each page title to "$SERVER_NAME Git", or
+	"Untitled Git" if this variable is not set (e.g. if running gitweb
+	as standalone script).
++
+Can be set using `GITWEB_SITENAME` during building.  [No default]
+
+$site_header::
+	Filename of html text to include at top of each page.  Relative to
+	'gitweb.cgi' script.  Can be set using `GITWEB_SITE_HEADER` during
+	building.  [No default]
+$site_footer::
+	Filename of html text to include at bottom of each page.  Relative to
+	gitweb.cgi script.  Can be set using `GITWEB_SITE_FOOTER` during
+	building.  [No default]
+$home_text::
+	Points to an HTML file which, if it exists, is included on the
+	gitweb projects overview page ("projects_list" view).  Relative to
+	gitweb.cgi script.  Default value can be adjusted using during build
+	via `GITWEB_HOMETEXT` variable.
++
+	[Default: 'indextext.html']
+
+$projects_list_description_width::
+	The width (in characters) of the projects list "Description" column.
+	Longer descriptions will be cut (trying to cut at word boundary);
+	full description is available as 'title' attribute (usually shown on
+	mouseover).  By default set to 25, which might be too small if you
+	use long project descriptions.
+$default_projects_order::
+	Default value of ordering of projects on projects list page.  Valid
+	values are "none" (unsorted), "project" (by project name, i.e. path
+	to repository relative to `$projectroot`), "descr" (project
+	description), "owner", and "age" (by date of most current commit).
+
+	Default value is "project".  Unknown value means unsorted.
+
+Changing gitweb behavior
+~~~~~~~~~~~~~~~~~~~~~~~~
+Those configuration variables control _internal_ gitweb behavior.
+
+$default_blob_plain_mimetype::
+	Default mimetype for blob_plain (raw) view, if mimetype checking
+	doesn't result in some other type; by default "text/plain".
+$default_text_plain_charset::
+	Default charset for text files. If not set, web server configuration
+	would be used.
+$fallback_encoding::
+	Gitweb assumes this charset if line contains non-UTF-8 characters.
+	Fallback decoding is used without error checking, so it can be even
+	"utf-8". Value must be valid encoding; see *Encoding::Supported*(3pm)
+	man page for a list.  By default "latin1", aka. "iso-8859-1".
+@diff_opts::
+	Rename detection options for git-diff and git-diff-tree. By default
+	(\'-M'); set it to (\'-C') or (\'-C', \'-C') to also detect copies,
+	or set it to () i.e. empty list if you don't want to have renames
+	detection.
+
+Extra features, administrative
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Most of features are configured via `%feature` hash; however some of extra
+gitweb features can be turned on and configured using variables described
+below.  This list beside configuration variables that control how gitweb
+looks does contain variables configuring administrative side of gitweb
+(e.g. cross-site scripting prevention; admittedly this as side effect
+affects how "summary" pages look like, or load limiting).
+
+@git_base_url_list::
+	List of git base URLs used for URL to where fetch project from, shown
+	in project summary page.  Full URL is "`$git_base_url/$project`".  You
+	can setup multiple base URLs (for example one for `git://` protocol
+	access, and one for `http://` "dumb" protocol access).  Note that per
+	repository configuration can be set in '$GIT_DIR/cloneurl' file, or as
+	values of multi-value `gitweb.url` configuration variable in project
+	config.
++
+You can setup one single value (single entry/item in this list) during
+building by using `GITWEB_BASE_URL` built-time configuration variable.
+[No default]
+
+$projects_list_group_categories::
+	Enables the grouping of projects by category on the project list page.
+	The category of a project is determined by the `$GIT_DIR/category` file
+	or the `gitweb.category` variable in its repository configuration.
+	[Disabled by default].
+$project_list_default_category::
+	Default category for projects for which none is specified.  If set to
+	the empty string, such projects will remain uncategorized and listed at
+	the top, above categorized projects.  Used only if project cateories are
+	enabled, which means if `$projects_list_group_categories` is true.
+	[Default: "" (empty string)]
+$prevent_xss::
+	If true, some gitweb features are disabled to prevent content in
+	repositories from launching cross-site scripting (XSS) attacks.  Set this
+	to true if you don't trust the content of your repositories.
+	[Default: false].
+$maxload::
+	Used to set the maximum load that we will still respond to gitweb queries.
+	If server load exceed this value then return "503 Service Unavailable"
+	error. Server load is taken to be 0 if gitweb cannot determine its value.
+	Set it to undefined value to turn it off. [Default: 300]
+$per_request_config::
+	If set to code reference, it would be run once per each request.  You can
+	set parts of configuration that change per session, e.g. by adding
+	the following code to gitweb configuration file
+--------------------------------------------------------------------------------
+our $per_request_config = sub {
+	$ENV{GL_USER} = $cgi->remote_user || "gitweb";
+};
+--------------------------------------------------------------------------------
+Otherwise it is treated as boolean value: if true gitweb would process
+config file once per request, if false it would process config file only
+once.
+
+*Note*: $my_url, $my_uri, and $base_url are overwritten with their default
+values before every request, so if you want to change them, be sure to set
+this variable to true or a code reference effecting the desired changes.
+
+[Default: true]
+
+Other variables
+~~~~~~~~~~~~~~~
+Usually you should not need to change (adjust) any of configuration
+variables described below; they should be automatically set by gitweb to
+correct value.
+
+$version::
+	Gitweb version, set automatically when creating gitweb.cgi from
+	gitweb.perl. You might want to modify it if you are running modified
+	gitweb, for example `our $version .= " with caching";`.
+$my_url::
+$my_uri::
+	Full URL and absolute URL of gitweb script;
+	in earlier versions of gitweb you might have need to set those
+	variables, now there should be no need to do it.  See
+	`$per_request_config` if you need to set them still.
+$base_url::
+	Base URL for relative URLs in pages generated by gitweb,
+	(e.g. `$logo`, `$favicon`, `@stylesheets` if they are relative URLs),
+	needed and used only for URLs with nonempty PATH_INFO via
+	'<base href="$base_url">'.  Usually gitweb sets its value correctly,
+	and there is no need to set this variable, e.g. to $my_uri or "/".
+	See `$per_request_config` if you need to set it anyway.
+
+
+CONFIGURING GITWEB FEATURES
+---------------------------
+Many gitweb features can be enabled (or disabled) and configured using the
+`%feature` hash.  Names of gitweb features are keys of this hash.
+
+Each `%feature` hash element is a hash reference and has the following
+structure:
+----------------------------------------------------------------------
+"<feature_name>" => {
+	"sub" => <feature-sub (subroutine)>,
+	"override" => <allow-override (boolean)>,
+	"default" => [ <options>... ]
+},
+----------------------------------------------------------------------
+Some of features does not support project specific override.  For those
+features the structure of appropriate `%feature` hash element has a simpler
+form:
+----------------------------------------------------------------------
+"<feature_name>" => {
+	"override" => 0,
+	"default" => [ <options>... ]
+},
+----------------------------------------------------------------------
+As one can see it lacks \'sub' element.
+
+The meaning of respective parts of feature configuration are described
+below:
+
+default::
+	List (array reference) of feature parameters (if there are any),
+	used also to toggle (enable or disable) given feature.
+
+	Note that it is currently *always* an array reference, even if
+	feature doesn't accept any configuration parameters, and \'default'
+	is used only to turn it on or off.  In such case you turn feature on
+	by setting this element to `[1]`, and torn it off by setting it to
+	`[0]`.  See also part about "blame" feature in the "Examples"
+	section.
+
+	To disable feature that accepts parameters (is configurable), you
+	need to set this element to empty list i.e. `[]`.
+
+override::
+	If it has a true value then given feature is overridable, which
+	means that it can be configured (or enabled/disabled) on
+	per-repository basis.
+
+	Usually given "<feature>" is configurable via `gitweb.<feature>`
+	config variable in per-repository git configuration file.
+
+	*Note* that no feature is overridable by default.
+
+sub::
+	Subroutine that will be called with default options as parameters to
+	examine per-repository configuration, but only if feature is
+	overridable (\'override' is set to true).  If not present then
+	per-repository override for given feature is not supported.
+
+	You wouldn't need to ever change it in gitweb config file.
+
+Features in `%feature`
+~~~~~~~~~~~~~~~~~~~~~~
+Below there are described gitweb features that are configurable via
+`%feature` hash.  For a complete list please consult gitweb sources.
+
+blame::
+	Enable the "blame" and "blame_incremental" blob views, showing for
+	each line the last commit that modified it; see linkgit:git-blame[1].
+	This can be very CPU-intensive and is therefore disabled by default.
+
+	This feature can be configured on a per-repository basis via
+	repository's `gitweb.blame` configuration variable (boolean).
+
+snapshot::
+	Enable and configure "snapshot" action, providing a compressed
+	archive of any tree or commit; see also linkgit:git-archive[1].
+	This can potentally generate high traffic if you have large project.
+
+	The value (of \'default') is a list of names of snapshot formats
+	defined in `%known_snapshot_formats` hash, that you wish to offer.
+	Among supported formats are "tgz", "tbz2", "txz" (gzip/bzip2/xz
+	compressed tar archive) and "zip"; please consult gitweb sources for
+	a definitive list.  By default only "tgz" is offered.
+
+	This feature can be configured on a per-repository basis via
+	repository's `gitweb.blame` configuration variable, which contains
+	a comma separated list of formats, or "none" to disable snapshots.
+	Unknown values will be ignored.
+
+grep::
+	Enable grep search, which will list the files in currently selected
+	tree (directory) containing the given string; see linkgit:git-rep[1].
+	This can be potentially CPU-intensive, of course.  Enabled by default.
+
+	This feature can be configured on a per-repository basis via
+	repository's `gitweb.grep` configuration variable (boolean).
+
+pickaxe::
+	Enable the so called pickaxe search, which will list the commits
+	that modified a given string in a file.  This can be practical and
+	quite faster alternative to "blame" action, but still potentially
+	CPU-intensive.  Enabled by default.
+
+	The pickaxe search is described in linkgit:git-log[1] (the
+	description of `-S<string>` option, which refers to pickaxe entry in
+	linkgit:gitdiffcore[7] for more details).
+
+	This feature can be configured on a per-repository basis via
+	repository's `gitweb.pickaxe` configuration variable (boolean).
+
+show-sizes::
+	Enable showing size of blobs (ordinary files) in a "tree" view, in a
+	separate column, similar to what `ls -l` does; see description of
+	`-l` option in linkgit:git-ls-tree[1] manpage.  This cost a bit of
+	I/O.  Enabled by default.
+
+	This feature can be configured on a per-repository basis via
+	repository's `gitweb.showsizes` configuration variable (boolean).
+
+patches::
+	Configure "patches" view, which displays list of commits in email
+	(plain text) output format; see also linkgit:git-format-patch[1].
+	The value is the maximum number of patches in a patchset generated
+	in "patches" view.  Set this to 0 or undef to disable patch view, or
+	to a negative number to remove any limit.  Default value is 16.
+
+	This feature can be configured on a per-repository basis via
+	repository's `gitweb.patches` configuration variable (integer).
+
+avatar::
+	Avatar support.  When this feature is enabled, views such as
+	"shortlog" or "commit" will display an avatar associated with
+	the email of the committer(s) and/or author(s).
+
+	Currently available providers are *"gravatar"* and *"picon"*.
+	If an unknown provider is specified, the feature is disabled.
+	*Note* that some provides might require extra Perl packages to be
+	installed; see 'gitweb/INSTALL' for more details.
+
+	This feature can be configured on a per-repository basis via
+	repository's `gitweb.avatar` configuration variable.
+
+	See also `%avatar_size` with pixel sizes for icons and avatars
+	("default" is used for one-line like "log" and "shortlog", "double"
+	is used for two-line like "commit", "commitdiff" or "tag").  If the
+	default font sizes or lineheights are changed (e.g. via adding extra
+	CSS stylesheet in `@stylesheets`), it may be appropriate to change
+	these values.
+
+highlight::
+	Server-side syntax hightlight support in "blob" view.  It requires
+	`$highlight_bin` program available (see description of this variable
+	in "Configuration variables" section above), and therefore is
+	disabled by default.
+
+	This feature can be configured on a per-repository basis via
+	repository's `gitweb.highlight` configuration variable (boolean).
+
+remote_heads::
+	Enable displaying remote heads (remote-tracking branches) in the "heads"
+	list.  In most cases it is unnecessary internal private detail, and it
+	is therefore disabled by default.  linkgit:git-instaweb[1], which is
+	usually used to browse local repositories, enables and uses this
+	feature.
+
+	This feature can be configured on a per-repository basis via
+	repository's `gitweb.remote_heads` configuration variable (boolean).
+
+
+The list below presents features that do not allow project specific
+overrides.
+
+search::
+	Enable text search, which will list the commits which match author,
+	committer or commit text to a given string; see description of
+	`--author`, `--committer` and `--grep` options in linkgit:git-log[1]
+	manpage.  Enabled by default.
+
+	Project specific override is not supported.
+
+forks::
+	Make gitweb consider projects in subdirectories of project root
+	(basename) to be forks of existing projects.  Given project
+	`$projname.git`, projects matching `$projname/*.git` will not be
+	shown in the main projects list, instead a \'+' mark will be added
+	to `$projname` there and a "forks" view will be enabled for the
+	project, listing all the forks.  If project list is taken from a
+	file, forks have to be listed after the main project.
+
+	Project specific override is not supported.
+
+actions::
+	Insert custom links to the action bar of all project pages.  This
+	enables you to link to third-party scripts integrating into gitweb.
+
+	The "default" value consists of a list of triplets in the form
+	`("<label>", "<link>", "<position>")` where "position" is the label
+	after which to insert the link, "link" is a format string where `%n`
+	expands to the project name, `%f` to the project path within the
+	filesystem, `%h` to the current hash (\'h' gitweb parameter) and
+	`%b` to the current hash base (\'hb' gitweb parameter); `%%` expands
+	to \'%'.
+
+	For example http://repo.or.cz git hosting site sets it to the
+	following to enable graphical log (via third party tool
+	*git-browser*):
+----------------------------------------------------------------------
+$feature{'actions'}{'default'} =
+	[ ('graphiclog', '/git-browser/by-commit.html?r=%n', 'summary')];
+----------------------------------------------------------------------
+This adds link titled "graphiclog" after "summary" link, leading to
+`git-browser` script, passing `r=<project>` as a query parameter.
+
+Project specific override is not supported.
+
+timed::
+	Enable displaying how much time and how many git commands it took to
+	generate and display page in the page footer (at the bottom of
+	page).  For example it might be: "This page took 6.53325 seconds and
+	13 git commands to generate."  Disabled by default.
+
+	Project specific override is not supported.
+
+javascript-timezone::
+
+	Enable and configure ability to change common timezone for dates in
+	gitweb output via JavaScript.  Dates in gitweb output include
+	authordate and comitterdate in "commit", "commitdiff" and "log"
+	views, and taggerdate in "tag" view.  Enabled by default.
+
+	Value is list of three values: default timezone (if client didn't
+	select other timezone and saved it in a cookie), name of cookie
+	where to store selected timezone, and CSS class used to mark up
+	dates for manipulation.  If you want to turn it off, set "default"
+	to empty list: `[]`.
+
+	In most case you would want to change only default timezone:
+---------------------------------------------------------------------------
+$feature{'javascript-timezone'}{'default'}[0] = "utc";
+---------------------------------------------------------------------------
+Timezone value can be "local" (for local timezone that browser uses), "utc"
+(what gitweb uses when JavaScript or this feature is disabled), or numerical
+timezone in the form of "+/-HHMM" for example "+0200".  This way is
+guaranteed to be backward compatibile.
+
+Project specific override is not supported.
+
+
+EXAMPLES
+--------
+
+To enable blame, pickaxe search, and snapshot support (allowing "tar.gz" and
+"zip" snapshots), while allowing individual projects to turn them off, put
+the following in your GITWEB_CONFIG file:
+
+        $feature{'blame'}{'default'} = [1];
+        $feature{'blame'}{'override'} = 1;
+
+        $feature{'pickaxe'}{'default'} = [1];
+        $feature{'pickaxe'}{'override'} = 1;
+
+        $feature{'snapshot'}{'default'} = ['zip', 'tgz'];
+        $feature{'snapshot'}{'override'} = 1;
+
+If you allow overriding for the snapshot feature, you can specify which
+snapshot formats are globally disabled. You can also add any command line
+options you want (such as setting the compression level). For instance, you
+can disable Zip compressed snapshots and set *gzip*(1) to run at level 6 by
+adding the following lines to your gitweb configuration file:
+
+        $known_snapshot_formats{'zip'}{'disabled'} = 1;
+        $known_snapshot_formats{'tgz'}{'compressor'} = ['gzip','-6'];
+
+ENVIRONMENT
+-----------
+The location of per-instance and system-wide configuration files can be set
+using the following environment variables:
+
+GITWEB_CONFIG::
+	Sets location of per-instance configuration file.
+GITWEB_CONFIG_SYSTEM::
+	Sets location of system-wide configuration file.  This file is read
+	only if per-instance one does not exist.
+
+FILES
+-----
+gitweb_config.perl::
+	This is default value for per-instance configuration file.  The
+	format of this file is described above.
+/etc/gitweb.conf::
+	This is default value for system-wide configuration file.  This file
+	is used only if per-instance configuration variable is not found.
+
+SEE ALSO
+--------
+linkgit:gitweb[1], linkgit:git-instaweb[1]
+
+'gitweb/README', 'gitweb/INSTALL'
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/gitweb/Makefile b/gitweb/Makefile
index 5d20515..dfdefef 100644
--- a/gitweb/Makefile
+++ b/gitweb/Makefile
@@ -172,6 +172,11 @@ test-installed:
 	GITWEB_TEST_INSTALLED='$(DESTDIR_SQ)$(gitwebdir_SQ)' \
 		$(MAKE) -C ../t gitweb-test
 
+### Documentation
+
+doc:
+	$(MAKE) -C ../Documentation gitweb-doc
+
 ### Installation rules
 
 install: all
@@ -185,5 +190,5 @@ install: all
 clean:
 	$(RM) gitweb.cgi static/gitweb.min.js static/gitweb.min.css GITWEB-BUILD-OPTIONS
 
-.PHONY: all clean install test test-installed .FORCE-GIT-VERSION-FILE FORCE
+.PHONY: all clean install test test-installed doc .FORCE-GIT-VERSION-FILE FORCE
 
diff --git a/gitweb/README b/gitweb/README
index a4cfcb4..1e6cf27 100644
--- a/gitweb/README
+++ b/gitweb/README
@@ -20,139 +20,8 @@ Ultimate description on how to reconfigure the default features setting
 in your `GITWEB_CONFIG` or per-project in `project.git/config` can be found
 as comments inside 'gitweb.cgi'.
 
-See also the "Gitweb config file" (with an example of config file), and
-the "Gitweb repositories" sections in INSTALL file for gitweb.
-
-
-The gitweb config file is a fragment of perl code. You can set variables
-using "our $variable = value"; text from "#" character until the end
-of a line is ignored. See perlsyn(1) man page for details.
-
-Below is the list of variables which you might want to set in gitweb config.
-See the top of 'gitweb.cgi' for the full list of variables and their
-descriptions.
-
-Gitweb config file variables
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-You can set, among others, the following variables in gitweb config files
-(with the exception of $projectroot and $projects_list this list does
-not include variables usually directly set during build):
- * $GIT
-   Core git executable to use.  By default set to "$GIT_BINDIR/git", which
-   in turn is by default set to "$(bindir)/git".  If you use git from binary
-   package, set this to "/usr/bin/git".  This can just be "git" if your
-   webserver has a sensible PATH.  If you have multiple git versions
-   installed it can be used to choose which one to use.
- * $version
-   Gitweb version, set automatically when creating gitweb.cgi from
-   gitweb.perl. You might want to modify it if you are running modified
-   gitweb.
- * $projectroot
-   Absolute filesystem path which will be prepended to project path;
-   the path to repository is $projectroot/$project.  Set to
-   $GITWEB_PROJECTROOT during installation.  This variable have to be
-   set correctly for gitweb to find repositories.
- * $projects_list
-   Source of projects list, either directory to scan, or text file
-   with list of repositories (in the "<URI-encoded repository path> SP
-   <URI-encoded repository owner>" line format; actually there can be
-   any sequence of whitespace in place of space (SP)).  Set to
-   $GITWEB_LIST during installation.  If empty, $projectroot is used
-   to scan for repositories.
- * $my_url, $my_uri
-   Full URL and absolute URL of gitweb script;
-   in earlier versions of gitweb you might have need to set those
-   variables, now there should be no need to do it.  See
-   $per_request_config if you need to set them still.
- * $base_url
-   Base URL for relative URLs in pages generated by gitweb,
-   (e.g. $logo, $favicon, @stylesheets if they are relative URLs),
-   needed and used only for URLs with nonempty PATH_INFO via
-   <base href="$base_url">.  Usually gitweb sets its value correctly,
-   and there is no need to set this variable, e.g. to $my_uri or "/".
-   See $per_request_config if you need to set it anyway.
- * $home_link
-   Target of the home link on top of all pages (the first part of view
-   "breadcrumbs").  By default set to absolute URI of a page ($my_uri).
- * @stylesheets
-   List of URIs of stylesheets (relative to base URI of a page). You
-   might specify more than one stylesheet, for example use gitweb.css
-   as base, with site specific modifications in separate stylesheet
-   to make it easier to upgrade gitweb. You can add 'site' stylesheet
-   for example by using
-      push @stylesheets, "gitweb-site.css";
-   in the gitweb config file.
- * $logo_url, $logo_label
-   URI and label (title) of GIT logo link (or your site logo, if you choose
-   to use different logo image). By default they point to git homepage;
-   in the past they pointed to git documentation at www.kernel.org.
- * $projects_list_description_width
-   The width (in characters) of the projects list "Description" column.
-   Longer descriptions will be cut (trying to cut at word boundary);
-   full description is available as 'title' attribute (usually shown on
-   mouseover).  By default set to 25, which might be too small if you
-   use long project descriptions.
- * $projects_list_group_categories
-   Enables the grouping of projects by category on the project list page.
-   The category of a project is determined by the $GIT_DIR/category
-   file or the 'gitweb.category' variable in its repository configuration.
-   Disabled by default.
- * $project_list_default_category
-   Default category for projects for which none is specified.  If set
-   to the empty string, such projects will remain uncategorized and
-   listed at the top, above categorized projects.
- * @git_base_url_list
-   List of git base URLs used for URL to where fetch project from, shown
-   in project summary page.  Full URL is "$git_base_url/$project".
-   You can setup multiple base URLs (for example one for  git:// protocol
-   access, and one for http:// "dumb" protocol access).  Note that per
-   repository configuration in 'cloneurl' file, or as values of gitweb.url
-   project config.
- * $default_blob_plain_mimetype
-   Default mimetype for blob_plain (raw) view, if mimetype checking
-   doesn't result in some other type; by default 'text/plain'.
- * $default_text_plain_charset
-   Default charset for text files. If not set, web server configuration
-   would be used.
- * $mimetypes_file
-   File to use for (filename extension based) guessing of MIME types before
-   trying /etc/mime.types. Path, if relative, is taken currently as
-   relative to the current git repository.
- * $fallback_encoding
-   Gitweb assumes this charset if line contains non-UTF-8 characters.
-   Fallback decoding is used without error checking, so it can be even
-   'utf-8'. Value must be valid encoding; see Encoding::Supported(3pm) man
-   page for a list.   By default 'latin1', aka. 'iso-8859-1'.
- * @diff_opts
-   Rename detection options for git-diff and git-diff-tree. By default
-   ('-M'); set it to ('-C') or ('-C', '-C') to also detect copies, or
-   set it to () if you don't want to have renames detection.
- * $prevent_xss
-   If true, some gitweb features are disabled to prevent content in
-   repositories from launching cross-site scripting (XSS) attacks.  Set this
-   to true if you don't trust the content of your repositories. The default
-   is false.
- * $maxload
-   Used to set the maximum load that we will still respond to gitweb queries.
-   If server load exceed this value then return "503 Service Unavailable" error.
-   Server load is taken to be 0 if gitweb cannot determine its value.  Set it to
-   undefined value to turn it off.  The default is 300.
- * $highlight_bin
-   Path to the highlight executable to use (must be the one from
-   http://www.andre-simon.de due to assumptions about parameters and output).
-   Useful if highlight is not installed on your webserver's PATH.
-   [Default: highlight]
- * $per_request_config
-   If set to code reference, it would be run once per each request.  You can
-   set parts of configuration that change per session, e.g. by setting it to
-     sub { $ENV{GL_USER} = $cgi->remote_user || "gitweb"; }
-   Otherwise it is treated as boolean value: if true gitweb would process
-   config file once per request, if false it would process config file only
-   once.  Note: $my_url, $my_uri, and $base_url are overwritten with
-   their default values before every request, so if you want to change
-   them, be sure to set this variable to true or a code reference effecting
-   the desired changes.  The default is true.
+See also gitweb.conf(5) manpage.
+
 
 Projects list file format
 ~~~~~~~~~~~~~~~~~~~~~~~~~
-- 
1.7.5

[RFC/PATCHv3 5/5] gitweb: Starting work on a man page for gitweb (WIP)

[Jakub Narebski]

Gitweb documentation currently consist of gitweb/README, gitweb/INSTALL
and comments in gitweb source code.  This is harder to find, use and
browse that manpages ("man gitweb" or "git help gitweb") and HTML
documentation ("git help --web gitweb").

The goal is to move documentation out of gitweb/README to gitweb.txt and
gitweb.conf.txt manpages, reducing its size 10x from around 500 to
around 50 lines (two pages), and move information not related drectly to
building and installing gitweb out of gitweb/INSTALL there.

To build gitweb documentation you can use

  make -C gitweb doc

or

  cd gitweb; make doc


This is a work in progress.  Much of what is in it has been pulled
directly from the README and INSTALL files of gitweb.  Some effort
has been made to de-duplicate any of this, i.e. to remove contents
from gitweb/README and gitweb/INSTALL.  The AsciiDoc might (and
probably does) contain formatting errors.

Inspired and somewhat modelled by SVN::Web manpage.

Inspired-by: Drew Northup <drew.northup@maine.edu>
Signed-off-by: Jakub Narebski <jnareb@gmail.com>
---
As you can see it is now much longer (702 lines versus 334 in previous
"skeleton" version).

Differences from previous version:

* Duplicated contents removed from gitweb/INSTALL and gitweb/README,
  but leaving simplest cases to make them a bit more self-contained.

* Added some references from gitweb.conf.txt to gitweb.txt

* Added "Generating projects list using gitweb", "Controlling access
  to git repositories", "Per-repository gitweb configuration"
  sections, and "Advanced web server setup" chapter.

 Documentation/Makefile        |    2 +-
 Documentation/gitweb.conf.txt |    8 +
 Documentation/gitweb.txt      |  702 +++++++++++++++++++++++++++++++++++++++++
 gitweb/INSTALL                |   96 +-----
 gitweb/README                 |  278 ++---------------
 5 files changed, 740 insertions(+), 346 deletions(-)
 create mode 100644 Documentation/gitweb.txt

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 68d0ebb..2fcbeac 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -1,7 +1,7 @@
 MAN1_TXT= \
 	$(filter-out $(addsuffix .txt, $(ARTICLES) $(SP_ARTICLES)), \
 		$(wildcard git-*.txt)) \
-	gitk.txt git.txt
+	gitk.txt gitweb.txt git.txt
 MAN5_TXT=gitattributes.txt gitignore.txt gitmodules.txt githooks.txt \
 	gitrepository-layout.txt gitweb.conf.txt
 MAN7_TXT=gitcli.txt gittutorial.txt gittutorial-2.txt \
diff --git a/Documentation/gitweb.conf.txt b/Documentation/gitweb.conf.txt
index 2bfe2e5..8dece6a 100644
--- a/Documentation/gitweb.conf.txt
+++ b/Documentation/gitweb.conf.txt
@@ -36,6 +36,10 @@ CGI script with the default name 'gitweb_config.perl' -- allowing
 one to have multiple gitweb instances with different configurations by
 the use of symlinks.
 
+Note that some configuration can be controlled on per-repository rather than
+gitweb-wide basis: see "Per-repository gitweb configuration" subsection on
+linkgit:gitweb[1] manpage.
+
 
 DISCUSSION
 ----------
@@ -88,6 +92,8 @@ Location of repositories
 Configuration variables described below control finding git repositories by
 gitweb, and control display and access to repositories.
 
+See also "Repositories" and later subsections in linkgit:gitweb[1] manpage.
+
 $projectroot::
 	Absolute filesystem path which will be prepended to project path;
 	the path to repository is `$projectroot/$project`.  Set to
@@ -143,6 +149,8 @@ though the above might be done by using `$export_ok` instead
 ----------------------------------------------------------------------------
 our $export_ok = "git-daemon-export-ok";
 ----------------------------------------------------------------------------
+See also more involved example in "Controlling access to git repositories"
+subsection on linkgit:gitweb[1] manpage.
 
 $strict_export::
 	Only allow viewing of repositories also shown on the overview page.
diff --git a/Documentation/gitweb.txt b/Documentation/gitweb.txt
new file mode 100644
index 0000000..53af722
--- /dev/null
+++ b/Documentation/gitweb.txt
@@ -0,0 +1,702 @@
+gitweb(1)
+=========
+
+NAME
+----
+gitweb - Git web interface (web frontend to Git repositories)
+
+SYNOPSIS
+--------
+To get started with gitweb, run linkgit:git-instaweb[1] from a git repository.
+This would configure and start your web server and run web browser pointing to
+gitweb page.
+
+See http://git.kernel.org/?p=git/git.git;a=tree;f=gitweb or
+http://repo.or.cz/w/git.git/tree/HEAD:/gitweb/ for gitweb source code, browsed
+using gitweb.
+
+
+DESCRIPTION
+-----------
+Gitweb provides a web interface to git repositories.  It's features include:
+
+* Viewing multiple Git repositories with common root.
+* Browsing every revision of the repository.
+* Viewing the contents of files in the repository at any revision.
+* Viewing the revision log of branches, history of files and directories,
+  see what was changed when, by who.
+* Viewing the blame/annotation details of any file (if enabled).
+* Generating RSS and Atom feeds of commits, for any branch.
+  The feeds are auto-discoverable in modern web browsers.
+* Viewing everything that was changed in a revision, and step through
+  revisions one at a time, viewing the history of the repository.
+* Finding commits which commit messages matches given search term.
+
+CONFIGURATION
+-------------
+Various aspects of gitweb's behavior can be controlled through the configuration
+file 'gitweb_conf.perl' or '/etc/gitweb.conf'.  See the linkgit:gitweb.conf[5]
+for details.
+
+Repositories
+~~~~~~~~~~~~
+Gitweb can show information from one or more Git repositories.  These
+repositories have to be all on local filesystem, and have to share common
+repository root, i.e. be all under a single parent repository (but see also
+"Advanced web server setup" section, "Webserver configuration with multiple
+projects' root" subsection).
+
+-----------------------------------------------------------------------
+our $projectroot = '/path/to/parent/directory';
+-----------------------------------------------------------------------
+
+The default value for `$projectroot` is '/pub/git'.  You can change it during
+building gitweb via `GITWEB_PROJECTROOT` build configuration variable.
+
+By default all git repositories under `$projectroot` are visible and available
+to gitweb.  The list of projects is generated by default by scanning the
+`$projectroot` directory for git repositories (for object databases to be
+more exact; gitweb is not interested in a working area, and is best suited
+to showing "bare" repositories).
+
+The name of repository in gitweb is path to it's `$GIT_DIR` (it's object
+database) relative to `$projectroot`.  Therefore the repository $repo can be
+found at "$projectroot/$repo".
+
+
+Projects list file format
+~~~~~~~~~~~~~~~~~~~~~~~~~
+Instead of having gitweb find repositories by scanning filesystem starting from
+$projectroot, you can provide a pre-generated list of [visible] projects by
+setting `$projects_list` to a plain text file with a list of projects (with some
+additional info).
+
+This file uses the following format:
+
+* One record (for project / repository) per line; does not support line
+continuation (newline escaping).
+
+* Leading and trailing whitespace are ignored.
+
+* Whitespace separated fields; any run of whitespace can be used as field
+separator (rules for Perl's "`split(" ", $line)`").
+
+* Fields use modified URI encoding, defined in RFC 3986, section 2.1
+(Percent-Encoding), or rather "Query string encoding" (see
+link:http://en.wikipedia.org/wiki/Query_string#URL_encoding[]), the difference
+being that SP (" ") can be encoded as "{plus}" (and therefore "{plus}" has to be
+also percent-encoded).
++
+Reserved characters are: "%" (used for encoding), "{plus}" (can be used to
+encode SPACE), all whitespace characters as defined in Perl, including SP,
+TAB and LF, (used to separate fields in a record).
+
+* Currently recognized fields are:
+<repository path>::
+	path to repository GIT_DIR, relative to `$projectroot`
+<repository owner>::
+	displayed as repository owner, preferably full name, or email,
+	or both
+
+You can generate the projects list index file using the project_index action
+(the 'TXT' link on projects list page) directly from gitweb; see also
+"Generating projects list using gitweb" section below.
+
+Example contents:
+-----------------------------------------------------------------------
+foo.git       Joe+R+Hacker+<joe@example.com>
+foo/bar.git   O+W+Ner+<owner@example.org>
+-----------------------------------------------------------------------
+
+
+By default this file controls only which projects are *visible* on projects
+list page (note that entries that do not point to correctly recognized git
+repositories won't be displayed by gitweb).  Even if a project is not
+visible on projects list page, you can view it nevertheless by hand-crafting
+a gitweb URL.  By setting `$strict_export` configuration variable (see
+linkgit:gitweb.conf[5]) to true value you can allow viewing only of
+repositories also shown on the overview page (i.e. only projects explicitely
+listed in projects list file will be accessible).
+
+
+Generating projects list using gitweb
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+We assume that GITWEB_CONFIG has its default Makefile value, namely
+'gitweb_config.perl'. Put the following in 'gitweb_make_index.perl' file:
+----------------------------------------------------------------------------
+read_config_file("gitweb_config.perl");
+
+$projects_list = $projectroot; # with gitweb_make_index.perl scan for repos
+----------------------------------------------------------------------------
+
+Then create the following script to get list of project in the format
+suitable for GITWEB_LIST build configuration variable (or
+`$projects_list` variable in gitweb config):
+
+----------------------------------------------------------------------------
+#!/bin/sh
+
+export GITWEB_CONFIG="gitweb_make_index.perl"
+export GATEWAY_INTERFACE="CGI/1.1"
+export HTTP_ACCEPT="*/*"
+export REQUEST_METHOD="GET"
+export QUERY_STRING="a=project_index"
+
+perl -- /var/www/cgi-bin/gitweb.cgi
+----------------------------------------------------------------------------
+
+Run this script and save its output to a file.  This file could then be used
+as projects list file, which means that you can set `$projects_list` to its
+filename.
+
+
+Controlling access to git repositories
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+By default all git repositories under `$projectroot` are visible and
+available to gitweb.  You can however configure how gitweb controls access
+to repositories.
+
+* As described in "Projects list file format" section, you can control which
+projects are *visible* by selectively including repositories in projects
+list file, and setting `$projects_list` gitweb configuration variable to
+point to it.  With `$strict_export` set, projects list file can be used to
+control which repositories are *available* as well.
+
+* You can configure gitweb to only list and allow viewing of the explicitly
+exported repositories, via `$export_ok` variable in gitweb config file; see
+linkgit:gitweb.conf[5] manpage.  If it evaluates to true, gitweb shows
+repositories only if this file named by `$export_ok` exists in its object
+database (if directory has the magic file named `$export_ok`).
++
+For example linkgit:git-daemon[1] by default (unless `--export-all` option
+is used) allows pulling only for those repositories that have
+'git-daemon-export-ok' file.  Adding
++
+--------------------------------------------------------------------------
+our $export_ok = "git-daemon-export-ok";
+--------------------------------------------------------------------------
++
+makes gitweb show and allow access only to those repositories that can be
+fetched from via `git://` protocol.
+
+* Finally, it is possible to specify an arbitrary perl subroutine that will
+be called for each repository to determine if it can be exported.  The
+subroutine receives an absolute path to the project (repository) as its only
+parameter (i.e. "$projectroot/$project").
++
+For example, if you use mod_perl to run the script, and have dumb
+http protocol authentication configured for your repositories, you
+can use the following hook to allow access only if the user is
+authorized to read the files:
++
+--------------------------------------------------------------------------
+$export_auth_hook = sub {
+	use Apache2::SubRequest ();
+	use Apache2::Const -compile => qw(HTTP_OK);
+	my $path = "$_[0]/HEAD";
+	my $r    = Apache2::RequestUtil->request;
+	my $sub  = $r->lookup_file($path);
+	return $sub->filename eq $path
+	    && $sub->status == Apache2::Const::HTTP_OK;
+};
+--------------------------------------------------------------------------
+
+
+Per-repository gitweb configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+You can configure individual repositories shown in gitweb by creating file
+in the 'GIT_DIR' of git repository, or by setting some repo configuration
+variable (in 'GIT_DIR/config', see linkgit:git-config[1]).
+
+You can use the following files in repository:
+
+README.html::
+	A html file (HTML fragment) which is included on the gitweb project
+	"summary" page inside `<div>` block element. You can use it for longer
+	description of a project, to provide links (for example to project's
+	homepage), etc. This is recognized only if XSS prevention is off
+	(`$prevent_xss` is false, see linkgit:gitweb.conf[5]); a way to include
+	a README safely when XSS prevention is on may be worked out in the
+	future.
+
+description (or `gitweb.description`)::
+	Short (shortened to `$projects_list_description_width` in the projects
+	list page, which is 25 characters by default; see
+	linkgit:gitweb.conf[5]) single line description of a project (of a
+	repository).  Plain text file; HTML will be escaped.  By default set to
+-------------------------------------------------------------------------------
+Unnamed repository; edit this file to name it for gitweb.
+-------------------------------------------------------------------------------
+from the template during repository creation, usually installed in
+'/usr/share/git-core/templates/'.  You can use the `gitweb.description` repo
+configuration variable, but the file takes precedence.
+
+category (or `gitweb.category`)::
+	Singe line category of a project, used to group projects if
+	`$projects_list_group_categories` is enabled.  By default (file and
+	configuration variable absent), uncategorized projects are put in the
+	`$project_list_default_category` category.  You can use the
+	`gitweb.category` repo configuration variable, but the file takes
+	precedence.
+
+	The configuration variables `$projects_list_group_categories` and
+	`$project_list_default_category` are described in linkgit:gitweb.conf[5]
+
+cloneurl (or multiple-valued `gitweb.url`)::
+	File with repository URL (used for clone and fetch), one per line.
+	Displayed in the project summary page. You can use multiple-valued
+	`gitweb.url` repository configuration variable for that, but the file
+	takes precedence.
+
+	This is per-repository enhancement / version of global prefix-based
+	`@git_base_url_list` gitweb configuration variable (see
+	linkgit:gitweb.conf[5]).
+
+gitweb.owner::
+	You can use the `gitweb.owner` repository configuration variable to set
+	repository's owner.  It is displayed in the project list and summary
+	page.
+
+	If it's not set, filesystem directory's owner is used (via GECOS field,
+	i.e. real name field from *getpwuid*(3)) if `$projects_list` is unset
+	(gitweb scans `$projectroot` for repositories); if `$projects_list`
+	points to file with list of repositories, then project owner defaults to
+	value from this file for given repository.
+
+various `gitweb.*` config variables (in config)::
+	Read description of `%feature` hash for detailed list, and descriptions.
+	See also "Configuring gitweb features" section in linkgit:gitweb.conf[5]
+
+
+ACTIONS, AND URLS
+-----------------
+Gitweb can use path_info (component) based URLs, or it can pass all necessary
+information via query parameters.  The typical gitweb URLs are broken down in to
+five components:
+
+-----------------------------------------------------------------------
+.../gitweb.cgi/<repo>/<action>/<revision>:/<path>?<arguments>
+-----------------------------------------------------------------------
+
+repo::
+	The repository the action will be performed on.
++
+	All actions except for those that list all available projects,
+	in whatever form, require this parameter.
+
+action::
+	The action that will be run.  Defaults to 'projects_list' if repo
+	is not set, and to 'summary' otherwise.
+
+revision::
+	Revision shown.  Defaults to HEAD.
+
+path::
+	The path within the <repository> that the action is performed on,
+	for those actions that require it.
+
+arguments::
+	Any arguments that control the behaviour of the action.
+
+Some actions require or allow to specify two revisions, and sometimes even two
+pathnames.  In most general form such path_info (component) based gitweb URL
+looks like this:
+
+-----------------------------------------------------------------------
+.../gitweb.cgi/<repo>/<action>/<revision_from>:/<path_from>..<revision_to>:/<path_to>?<arguments>
+-----------------------------------------------------------------------
+
+
+Each action is implemented as a subroutine, and must be present in %actions
+hash.  Some actions are disabled by default, and must be turned on via feature
+mechanism.  For example to enable 'blame' view add the following to gitweb
+configuration file:
+
+-----------------------------------------------------------------------
+$feature{'blame'}{'default'} = [1];
+-----------------------------------------------------------------------
+
+
+Actions:
+~~~~~~~~
+The standard actions are:
+
+project_list::
+	Lists the available Git repositories.  This is the default command if no
+	repository is specified in the URL.
+
+summary::
+	Displays summary about given repository.  This is the default command if
+	no action is specified in URL, and only repository is specified.
+
+heads::
+remotes::
+	Lists all local or all remote-tracking branches in given repository.
++
+	The latter is not available by default, unless configured.
+
+tags::
+	List all tags (lightweight and annotated) in given repository.
+
+blob::
+tree::
+	Shows the files and directories in a given repository path, at given
+	revision.  This is default command if no action is specified in the URL,
+	and path is given.
+
+blob_plain::
+	Returns the raw data for the file in given repository, at given path and
+	revision.  Links to this action are marked 'raw'.
+
+blobdiff::
+	Shows the difference between two revisions of the same file.
+
+blame::
+blame_incremental::
+	Shows the blame (also called annotation) information for a file. On a
+	per line basis it shows the revision in which that line was last changed
+	and the user that committed the change.  The incremental version (which
+	if configured is used automatically when JavaScript is enabled) uses
+	Ajax to incrementally add blame info to the contents of given file.
++
+	This action is disabled by default for performance reasons.
+
+commit::
+commitdiff::
+	Shows information about a specific commit in a repository.  The 'commit'
+	view shows information about commit in more detail, the 'commitdiff'
+	action shows changeset for given commit.
+
+patch:: 
+	Returns the commit in plain text mail format, suitable for applying with
+	linkgit:git-am[1].
+
+tag::
+	Display specific annotated tag (tag object).	
+
+log::
+shortlog::
+	Shows log information (commit message or just commit subject) for a
+	given branch (starting from given revision).
++
+	The 'shortlog' view is more compact; it shows one commit per line.
+
+history::
+	Shows history of the file or directory in a given repository path,
+	starting from given revision (defaults to HEAD, i.e. default branch).
++
+	This view is similar to 'shortlog' view.
+
+rss::
+atom::
+	Generates an RSS (or Atom) feed of changes to repository.
+
+
+WEBSERVER CONFIGURATION
+-----------------------
+This section explains how to configure some common webservers to run gitweb. In
+all cases, `/path/to/gitweb` in the examples is the directory you ran installed
+gitweb in, and contains `gitweb_config.perl`.
+
+If you've configured a web server that isn't listed here for gitweb, please send
+in the instructions so they can be included in a future release.
+
+Apache as CGI
+~~~~~~~~~~~~~
+Apache must be configured to support CGI scripts in the directory in
+which gitweb is installed.  Let's assume that it is '/var/www/cgi-bin'
+directory.
+
+-----------------------------------------------------------------------
+ScriptAlias /cgi-bin/ "/var/www/cgi-bin/"
+
+<Directory "/var/www/cgi-bin">
+    Options Indexes FollowSymlinks ExecCGI
+    AllowOverride None
+    Order allow,deny
+    Allow from all
+</Directory>
+-----------------------------------------------------------------------
+
+With that configuration the full path to browse repositories would be:
+
+  http://server/cgi-bin/gitweb.cgi
+
+Apache with mod_perl, via ModPerl::Registry
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+You can use mod_perl with gitweb.  You must install Apache::Registry
+(for mod_perl 1.x) or ModPerl::Registry (for mod_perl 2.x) to enable
+this support.
+
+Assuming that gitweb is installed to '/var/www/perl', the following
+Apache configuration (for mod_perl 2.x) is suitable.
+
+-----------------------------------------------------------------------
+Alias /perl "/var/www/perl"
+
+<Directory "/var/www/perl">
+    SetHandler perl-script
+    PerlResponseHandler ModPerl::Registry
+    PerlOptions +ParseHeaders
+    Options Indexes FollowSymlinks +ExecCGI
+    AllowOverride None
+    Order allow,deny
+    Allow from all
+</Directory>
+-----------------------------------------------------------------------
+
+With that configuration the full path to browse repositories would be:
+
+  http://server/perl/gitweb.cgi
+
+Apache with FastCGI
+~~~~~~~~~~~~~~~~~~~
+Gitweb works with Apache and FastCGI.  First you need to rename, copy
+or symlink gitweb.cgi to gitweb.fcgi.  Let's assume that gitweb is
+installed in '/usr/share/gitweb' directory.  The following Apache
+configuration is suitable (UNTESTED!)
+
+-----------------------------------------------------------------------
+FastCgiServer /usr/share/gitweb/gitweb.cgi
+ScriptAlias /gitweb /usr/share/gitweb/gitweb.cgi
+
+Alias /gitweb/static /usr/share/gitweb/static
+<Directory /usr/share/gitweb/static>
+    SetHandler default-handler
+</Directory>
+-----------------------------------------------------------------------
+
+With that configuration the full path to browse repositories would be:
+
+  http://server/gitweb
+
+
+ADVANCED WEB SERVER SETUP
+-------------------------
+All of those examples use request rewriting, and need `mod_rewrite`
+(or equivalent; examples below are written for Apache).
+
+Single URL for gitweb and for fetching
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+If you want to have one URL for both gitweb and your `http://`
+repositories, you can configure Apache like this:
+
+-----------------------------------------------------------------------
+<VirtualHost *:80>
+    ServerName    git.example.org
+    DocumentRoot  /pub/git
+    SetEnv        GITWEB_CONFIG   /etc/gitweb.conf
+
+    # turning on mod rewrite
+    RewriteEngine on
+
+    # make the front page an internal rewrite to the gitweb script
+    RewriteRule ^/$  /cgi-bin/gitweb.cgi
+
+    # make access for "dumb clients" work
+    RewriteRule ^/(.*\.git/(?!/?(HEAD|info|objects|refs)).*)?$ \
+                /cgi-bin/gitweb.cgi%{REQUEST_URI}  [L,PT]
+</VirtualHost>
+-----------------------------------------------------------------------
+
+The above configuration expects your public repositories to live under
+'/pub/git' and will serve them as `http://git.domain.org/dir-under-pub-git`,
+both as cloneable GIT URL and as browseable gitweb interface.  If you then
+start your linkgit:git-daemon[1] with `--base-path=/pub/git --export-all`
+then you can even use the `git://` URL with exactly the same path.
+
+Setting the environment variable `GITWEB_CONFIG` will tell gitweb to use the
+named file (i.e. in this example '/etc/gitweb.conf') as a configuration for
+gitweb.  You don't really need it in above example; it is required only if
+your configuration file is in different place than built-in (during
+compiling gitweb) 'gitweb_config.perl' or '/etc/gitweb.conf'.  See
+linkgit:gitweb.conf[5] for details, especially information about precedence
+rules.
+
+If you use the rewrite rules from the example you *might* also need
+something like the following in your gitweb configuration file
+('/etc/gitweb.conf' following example):
+----------------------------------------------------------------------------
+@stylesheets = ("/some/absolute/path/gitweb.css");
+$my_uri    = "/";
+$home_link = "/";
+$per_request_config = 1;
+----------------------------------------------------------------------------
+Nowadays though gitweb should create HTML base tag when needed (to set base
+URI for relative links), so it should work automatically.
+
+
+Webserver configuration with multiple projects' root
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+If you want to use gitweb with several project roots you can edit your
+Apache virtual host and gitweb configuration files in the following way.
+
+The virtual host configuration (in Apache configuration file) should look
+like this:
+--------------------------------------------------------------------------
+<VirtualHost *:80>
+    ServerName    git.example.org
+    DocumentRoot  /pub/git
+    SetEnv        GITWEB_CONFIG  /etc/gitweb.conf
+
+    # turning on mod rewrite
+    RewriteEngine on
+
+    # make the front page an internal rewrite to the gitweb script
+    RewriteRule ^/$  /cgi-bin/gitweb.cgi  [QSA,L,PT]
+
+    # look for a public_git folder in unix users' home
+    # http://git.example.org/~<user>/
+    RewriteRule ^/\~([^\/]+)(/|/gitweb.cgi)?$	/cgi-bin/gitweb.cgi \
+                [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT]
+
+    # http://git.example.org/+<user>/
+    #RewriteRule ^/\+([^\/]+)(/|/gitweb.cgi)?$	/cgi-bin/gitweb.cgi \
+                 [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT]
+
+    # http://git.example.org/user/<user>/
+    #RewriteRule ^/user/([^\/]+)/(gitweb.cgi)?$	/cgi-bin/gitweb.cgi \
+                 [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT]
+
+    # defined list of project roots
+    RewriteRule ^/scm(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi \
+                [QSA,E=GITWEB_PROJECTROOT:/pub/scm/,L,PT]
+    RewriteRule ^/var(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi \
+                [QSA,E=GITWEB_PROJECTROOT:/var/git/,L,PT]
+
+    # make access for "dumb clients" work
+    RewriteRule ^/(.*\.git/(?!/?(HEAD|info|objects|refs)).*)?$ \
+                /cgi-bin/gitweb.cgi%{REQUEST_URI}  [L,PT]
+</VirtualHost>
+--------------------------------------------------------------------------
+
+Here actual project root is passed to gitweb via `GITWEB_PROJECT_ROOT`
+environment variable from a web server, so you need to put the following
+line in gitweb configuration file ('/etc/gitweb.conf' in above example):
+--------------------------------------------------------------------------
+$projectroot = $ENV{'GITWEB_PROJECTROOT'} || "/pub/git";
+--------------------------------------------------------------------------
+*Note* that this requires to be set for each request, so either
+`$per_request_config` must be false, or the above must be put in code
+referenced by `$per_request_config`;
+
+These configurations enable two things. First, each unix user (`<user>`) of
+the server will be able to browse through gitweb git repositories found in
+'~/public_git/' with the following url:
+
+  http://git.example.org/~<user>/
+
+If you do not want this feature on your server just remove the second
+rewrite rule.
+
+If you already use `mod_userdir` in your virtual host or you don't want to
+use the \'~' as first character, just comment or remove the second rewrite
+rule, and uncomment one of the following according to what you want.
+
+Second, repositories found in '/pub/scm/' and '/var/git/' will be accesible
+through `http://git.example.org/scm/` and `http://git.example.org/var/`.
+You can add as many project roots as you want by adding rewrite rules like
+the third and the fourth.
+
+
+PATH_INFO usage
+~~~~~~~~~~~~~~~
+If you enable PATH_INFO usage in gitweb by putting
+----------------------------------------------------------------------------
+$feature{'pathinfo'}{'default'} = [1];
+----------------------------------------------------------------------------
+in your gitweb configuration file, it is possible to set up your server so
+that it consumes and produces URLs in the form
+
+  http://git.example.com/project.git/shortlog/sometag
+
+i.e. without 'gitweb.cgi' part, by using a configuration such as the
+following.  This configuration assumes that '/var/www/gitweb' is the
+DocumentRoot of your webserver, contains the gitweb.cgi script and
+complementary static files (stylesheet, favicon, JavaScript):
+
+----------------------------------------------------------------------------
+<VirtualHost *:80>
+	ServerAlias git.example.com
+
+	DocumentRoot /var/www/gitweb
+
+	<Directory /var/www/gitweb>
+		Options ExecCGI
+		AddHandler cgi-script cgi
+
+		DirectoryIndex gitweb.cgi
+
+		RewriteEngine On
+		RewriteCond %{REQUEST_FILENAME} !-f
+		RewriteCond %{REQUEST_FILENAME} !-d
+		RewriteRule ^.* /gitweb.cgi/$0 [L,PT]
+	</Directory>
+</VirtualHost>
+----------------------------------------------------------------------------
+The rewrite rule guarantees that existing static files will be properly
+served, whereas any other URL will be passed to gitweb as PATH_INFO
+parameter.
+
+*Notice* that in this case you don't need special settings for
+`@stylesheets`, `$my_uri` and `$home_link`, but you lose "dumb client"
+access to your project .git dirs (described in "Single URL for gitweb and
+for fetching" section).  A possible workaround for the latter is the
+following: in your project root dir (e.g. '/pub/git') have the projects
+named *without* a .git extension (e.g. '/pub/git/project' instead of
+'/pub/git/project.git') and configure Apache as follows:
+----------------------------------------------------------------------------
+<VirtualHost *:80>
+	ServerAlias git.example.com
+
+	DocumentRoot /var/www/gitweb
+
+	AliasMatch ^(/.*?)(\.git)(/.*)?$ /pub/git$1$3
+	<Directory /var/www/gitweb>
+		Options ExecCGI
+		AddHandler cgi-script cgi
+
+		DirectoryIndex gitweb.cgi
+
+		RewriteEngine On
+		RewriteCond %{REQUEST_FILENAME} !-f
+		RewriteCond %{REQUEST_FILENAME} !-d
+		RewriteRule ^.* /gitweb.cgi/$0 [L,PT]
+	</Directory>
+</VirtualHost>
+----------------------------------------------------------------------------
+
+The additional AliasMatch makes it so that
+
+  http://git.example.com/project.git
+
+will give raw access to the project's git dir (so that the project can be
+cloned), while
+
+  http://git.example.com/project
+
+will provide human-friendly gitweb access.
+
+This solution is not 100% bulletproof, in the sense that if some project has
+a named ref (branch, tag) starting with 'git/', then paths such as
+
+  http://git.example.com/project/command/abranch..git/abranch
+
+will fail with a 404 error.
+
+
+BUGS
+----
+Please report any bugs or feature requests to git@vger.kernel.org,
+putting "gitweb" in the subject of email.
+
+SEE ALSO
+--------
+linkgit:gitweb.conf[5], linkgit:git-instaweb[1]
+
+'gitweb/README', 'gitweb/INSTALL'
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/gitweb/INSTALL b/gitweb/INSTALL
index c5236fe..c61fd62 100644
--- a/gitweb/INSTALL
+++ b/gitweb/INSTALL
@@ -229,7 +229,7 @@ Gitweb config file
 ------------------
 
 See also "Runtime gitweb configuration" section in README file
-for gitweb (in gitweb/README).
+for gitweb (in gitweb/README), and gitweb.conf(5) manpage.
 
 - You can configure gitweb further using the gitweb configuration file;
   by default this is a file named gitweb_config.perl in the same place as
@@ -276,97 +276,19 @@ adding the following lines to your $GITWEB_CONFIG:
 Gitweb repositories
 -------------------
 
-- By default all git repositories under projectroot are visible and
-  available to gitweb. The list of projects is generated by default by
-  scanning the projectroot directory for git repositories (for object
-  databases to be more exact).
-
-  You can provide a pre-generated list of [visible] repositories,
-  together with information about their owners (the project ownership
-  defaults to the owner of the repository directory otherwise), by setting
-  the GITWEB_LIST build configuration variable (or the $projects_list
-  variable in the gitweb config file) to point to a plain file.
-
-  Each line of the projects list file should consist of the url-encoded path
-  to the project repository database (relative to projectroot), followed
-  by the url-encoded project owner on the same line (separated by a space).
-  Spaces in both project path and project owner have to be encoded as either
-  '%20' or '+'.
-
-  Other characters that have to be url-encoded, i.e. replaced by '%'
-  followed by two-digit character number in octal, are: other whitespace
-  characters (because they are field separator in a record), plus sign '+'
-  (because it can be used as replacement for spaces), and percent sign '%'
-  (which is used for encoding / escaping).
-
-  You can generate the projects list index file using the project_index
-  action (the 'TXT' link on projects list page) directly from gitweb.
-
-- By default, even if a project is not visible on projects list page, you
-  can view it nevertheless by hand-crafting a gitweb URL. You can set the
-  GITWEB_STRICT_EXPORT build configuration variable (or the $strict_export
-  variable in the gitweb config file) to only allow viewing of
-  repositories also shown on the overview page.
-
-- Alternatively, you can configure gitweb to only list and allow
-  viewing of the explicitly exported repositories, via the
-  GITWEB_EXPORT_OK build configuration variable (or the $export_ok
-  variable in gitweb config file). If it evaluates to true, gitweb
-  shows repositories only if this file exists in its object database
-  (if directory has the magic file named $export_ok).
-
-- Finally, it is possible to specify an arbitrary perl subroutine that
-  will be called for each project to determine if it can be exported.
-  The subroutine receives an absolute path to the project as its only
-  parameter.
-
-  For example, if you use mod_perl to run the script, and have dumb
-  http protocol authentication configured for your repositories, you
-  can use the following hook to allow access only if the user is
-  authorized to read the files:
-
-    $export_auth_hook = sub {
-        use Apache2::SubRequest ();
-        use Apache2::Const -compile => qw(HTTP_OK);
-        my $path = "$_[0]/HEAD";
-        my $r    = Apache2::RequestUtil->request;
-        my $sub  = $r->lookup_file($path);
-        return $sub->filename eq $path
-            && $sub->status == Apache2::Const::HTTP_OK;
-    };
-
-
-Generating projects list using gitweb
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-We assume that GITWEB_CONFIG has its default Makefile value, namely
-gitweb_config.perl. Put the following in gitweb_make_index.perl file:
-
-	$GITWEB_CONFIG = "gitweb_config.perl";
-	do $GITWEB_CONFIG if -e $GITWEB_CONFIG;
-
-	$projects_list = $projectroot;
-
-Then create the following script to get list of project in the format
-suitable for GITWEB_LIST build configuration variable (or
-$projects_list variable in gitweb config):
-
-	#!/bin/sh
-
-	export GITWEB_CONFIG="gitweb_make_index.perl"
-	export GATEWAY_INTERFACE="CGI/1.1"
-	export HTTP_ACCEPT="*/*"
-	export REQUEST_METHOD="GET"
-	export QUERY_STRING="a=project_index"
-
-	perl -- /var/www/cgi-bin/gitweb.cgi
+By default gitweb shows all git repositories under single common repository
+root on a local filesystem; see description of GITWEB_PROJECTROOT build-time
+configuration variable above (and also of GITWEB_LIST).
+
+More advanced usage, like limiting access or visibility of repositories and
+managing multiple roots are described on gitweb manpage.
 
 
 Example web server configuration
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-See also "Webserver configuration" section in README file for gitweb
-(in gitweb/README).
+See also "Webserver configuration" and "Advanced web server setup" sections
+in gitweb(1) manpage.
 
 
 - Apache2, gitweb installed as CGI script,
diff --git a/gitweb/README b/gitweb/README
index 1e6cf27..b952d45 100644
--- a/gitweb/README
+++ b/gitweb/README
@@ -7,9 +7,18 @@ The one working on:
 From the git version 1.4.0 gitweb is bundled with git.
 
 
+Build time gitweb configuration
+-------------------------------
+There are many configuration variables which affect building gitweb (among
+others creating gitweb.cgi out of gitweb.perl by replacing placeholders such
+as `++GIT_BINDIR++` by their build-time values).
+
+Building and installing gitweb is described in gitweb's INSTALL file
+(in 'gitweb/INSTALL').
+
+
 Runtime gitweb configuration
 ----------------------------
-
 You can adjust gitweb behaviour using the file specified in `GITWEB_CONFIG`
 (defaults to 'gitweb_config.perl' in the same directory as the CGI), and
 as a fallback `GITWEB_CONFIG_SYSTEM` (defaults to /etc/gitweb.conf).
@@ -23,266 +32,19 @@ as comments inside 'gitweb.cgi'.
 See also gitweb.conf(5) manpage.
 
 
-Projects list file format
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Instead of having gitweb find repositories by scanning filesystem starting
-from $projectroot (or $projects_list, if it points to directory), you can
-provide list of projects by setting $projects_list to a text file with list
-of projects (and some additional info).  This file uses the following
-format:
-
-One record (for project / repository) per line, whitespace separated fields;
-does not support (at least for now) lines continuation (newline escaping).
-Leading and trailing whitespace are ignored, any run of whitespace can be
-used as field separator (rules for Perl's "split(' ', $line)").  Keyed by
-the first field, which is project name, i.e. path to repository GIT_DIR
-relative to $projectroot.  Fields use modified URI encoding, defined in
-RFC 3986, section 2.1 (Percent-Encoding), or rather "Query string encoding"
-(see http://en.wikipedia.org/wiki/Query_string#URL_encoding), the difference
-being that SP (' ') can be encoded as '+' (and therefore '+' has to be also
-percent-encoded).  Reserved characters are: '%' (used for encoding), '+'
-(can be used to encode SPACE), all whitespace characters as defined in Perl,
-including SP, TAB and LF, (used to separate fields in a record).
-
-Currently list of fields is
- * <repository path>  - path to repository GIT_DIR, relative to $projectroot
- * <repository owner> - displayed as repository owner, preferably full name,
-                        or email, or both
-
-You can additionally use $projects_list file to limit which repositories
-are visible, and together with $strict_export to limit access to
-repositories (see "Gitweb repositories" section in gitweb/INSTALL).
-
-
-Per-repository gitweb configuration
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-You can also configure individual repositories shown in gitweb by creating
-file in the GIT_DIR of git repository, or by setting some repo configuration
-variable (in GIT_DIR/config).
-
-You can use the following files in repository:
- * README.html
-   A .html file (HTML fragment) which is included on the gitweb project
-   summary page inside <div> block element. You can use it for longer
-   description of a project, to provide links (for example to project's
-   homepage), etc. This is recognized only if XSS prevention is off
-   ($prevent_xss is false); a way to include a readme safely when XSS
-   prevention is on may be worked out in the future.
- * description (or gitweb.description)
-   Short (shortened by default to 25 characters in the projects list page)
-   single line description of a project (of a repository). Plain text file;
-   HTML will be escaped. By default set to
-     Unnamed repository; edit this file to name it for gitweb.
-   from the template during repository creation. You can use the
-   gitweb.description repo configuration variable, but the file takes
-   precedence.
- * category (or gitweb.category)
-   Singe line category of a project, used to group projects if
-   $projects_list_group_categories is enabled. By default (file and
-   configuration variable absent), uncategorized projects are put in
-   the $project_list_default_category category. You can use the
-   gitweb.category repo configuration variable, but the file takes
-   precedence.
- * cloneurl (or multiple-valued gitweb.url)
-   File with repository URL (used for clone and fetch), one per line.
-   Displayed in the project summary page. You can use multiple-valued
-   gitweb.url repository configuration variable for that, but the file
-   takes precedence.
- * gitweb.owner
-   You can use the gitweb.owner repository configuration variable to set
-   repository's owner. It is displayed in the project list and summary
-   page. If it's not set, filesystem directory's owner is used
-   (via GECOS field / real name field from getpwiud(3)).
- * various gitweb.* config variables (in config)
-   Read description of %feature hash for detailed list, and some
-   descriptions.
-
-
-Webserver configuration
------------------------
-
-If you want to have one URL for both gitweb and your http://
-repositories, you can configure apache like this:
-
-<VirtualHost *:80>
-    ServerName		git.example.org
-    DocumentRoot	/pub/git
-    SetEnv			GITWEB_CONFIG	/etc/gitweb.conf
-
-    # turning on mod rewrite
-    RewriteEngine on
-
-    # make the front page an internal rewrite to the gitweb script
-    RewriteRule ^/$  /cgi-bin/gitweb.cgi
-
-    # make access for "dumb clients" work
-    RewriteRule ^/(.*\.git/(?!/?(HEAD|info|objects|refs)).*)?$ /cgi-bin/gitweb.cgi%{REQUEST_URI}  [L,PT]
-</VirtualHost>
-
-The above configuration expects your public repositories to live under
-/pub/git and will serve them as http://git.domain.org/dir-under-pub-git,
-both as cloneable GIT URL and as browseable gitweb interface.
-If you then start your git-daemon with --base-path=/pub/git --export-all
-then you can even use the git:// URL with exactly the same path.
-
-Setting the environment variable GITWEB_CONFIG will tell gitweb to use
-the named file (i.e. in this example /etc/gitweb.conf) as a
-configuration for gitweb.  Perl variables defined in here will
-override the defaults given at the head of the gitweb.perl (or
-gitweb.cgi).  Look at the comments in that file for information on
-which variables and what they mean.
-
-If you use the rewrite rules from the example you'll likely also need
-something like the following in your gitweb.conf (or gitweb_config.perl) file:
-
-  @stylesheets = ("/some/absolute/path/gitweb.css");
-  $my_uri = "/";
-  $home_link = "/";
-
-
-Webserver configuration with multiple projects' root
-----------------------------------------------------
-
-If you want to use gitweb with several project roots you can edit your apache
-virtual host and gitweb.conf configuration files like this :
-
-virtual host configuration :
-
-<VirtualHost *:80>
-    ServerName			git.example.org
-    DocumentRoot		/pub/git
-    SetEnv				GITWEB_CONFIG	/etc/gitweb.conf
-
-    # turning on mod rewrite
-    RewriteEngine on
-
-    # make the front page an internal rewrite to the gitweb script
-    RewriteRule ^/$ 		/cgi-bin/gitweb.cgi [QSA,L,PT]
-
-    # look for a public_git folder in unix users' home
-    # http://git.example.org/~<user>/
-    RewriteRule ^/\~([^\/]+)(/|/gitweb.cgi)?$	/cgi-bin/gitweb.cgi [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT]
-
-    # http://git.example.org/+<user>/
-    #RewriteRule ^/\+([^\/]+)(/|/gitweb.cgi)?$	/cgi-bin/gitweb.cgi [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT]
-
-    # http://git.example.org/user/<user>/
-    #RewriteRule ^/user/([^\/]+)/(gitweb.cgi)?$	/cgi-bin/gitweb.cgi [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT]
-
-    # defined list of project roots
-    RewriteRule ^/scm(/|/gitweb.cgi)?$		/cgi-bin/gitweb.cgi [QSA,E=GITWEB_PROJECTROOT:/pub/scm/,L,PT]
-    RewriteRule ^/var(/|/gitweb.cgi)?$		/cgi-bin/gitweb.cgi [QSA,E=GITWEB_PROJECTROOT:/var/git/,L,PT]
-
-    # make access for "dumb clients" work
-    RewriteRule ^/(.*\.git/(?!/?(HEAD|info|objects|refs)).*)?$ /cgi-bin/gitweb.cgi%{REQUEST_URI}  [L,PT]
-</VirtualHost>
-
-gitweb.conf configuration :
-
-$projectroot = $ENV{'GITWEB_PROJECTROOT'} || "/pub/git";
-
-These configurations enable two things. First, each unix user (<user>) of the
-server will be able to browse through gitweb git repositories found in
-~/public_git/ with the following url : http://git.example.org/~<user>/
-
-If you do not want this feature on your server just remove the second rewrite rule.
-
-If you already use mod_userdir in your virtual host or you don't want to use
-the '~' as first character just comment or remove the second rewrite rule and
-uncomment one of the following according to what you want.
-
-Second, repositories found in /pub/scm/ and /var/git/ will be accesible
-through http://git.example.org/scm/ and http://git.example.org/var/.
-You can add as many project roots as you want by adding rewrite rules like the
-third and the fourth.
-
-
-PATH_INFO usage
------------------------
-If you enable PATH_INFO usage in gitweb by putting
-
-   $feature{'pathinfo'}{'default'} = [1];
-
-in your gitweb.conf, it is possible to set up your server so that it
-consumes and produces URLs in the form
-
-http://git.example.com/project.git/shortlog/sometag
-
-by using a configuration such as the following, that assumes that
-/var/www/gitweb is the DocumentRoot of your webserver, and that it
-contains the gitweb.cgi script and complementary static files
-(stylesheet, favicon):
-
-<VirtualHost *:80>
-	ServerAlias git.example.com
-
-	DocumentRoot /var/www/gitweb
-
-	<Directory /var/www/gitweb>
-		Options ExecCGI
-		AddHandler cgi-script cgi
-
-		DirectoryIndex gitweb.cgi
-
-		RewriteEngine On
-		RewriteCond %{REQUEST_FILENAME} !-f
-		RewriteCond %{REQUEST_FILENAME} !-d
-		RewriteRule ^.* /gitweb.cgi/$0 [L,PT]
-	</Directory>
-</VirtualHost>
-
-The rewrite rule guarantees that existing static files will be properly
-served, whereas any other URL will be passed to gitweb as PATH_INFO
-parameter.
-
-Notice that in this case you don't need special settings for
-@stylesheets, $my_uri and $home_link, but you lose "dumb client" access
-to your project .git dirs. A possible workaround for the latter is the
-following: in your project root dir (e.g. /pub/git) have the projects
-named without a .git extension (e.g. /pub/git/project instead of
-/pub/git/project.git) and configure Apache as follows:
-
-<VirtualHost *:80>
-	ServerAlias git.example.com
-
-	DocumentRoot /var/www/gitweb
-
-	AliasMatch ^(/.*?)(\.git)(/.*)?$ /pub/git$1$3
-	<Directory /var/www/gitweb>
-		Options ExecCGI
-		AddHandler cgi-script cgi
-
-		DirectoryIndex gitweb.cgi
-
-		RewriteEngine On
-		RewriteCond %{REQUEST_FILENAME} !-f
-		RewriteCond %{REQUEST_FILENAME} !-d
-		RewriteRule ^.* /gitweb.cgi/$0 [L,PT]
-	</Directory>
-</VirtualHost>
-
-The additional AliasMatch makes it so that
-
-http://git.example.com/project.git
-
-will give raw access to the project's git dir (so that the project can
-be cloned), while
-
-http://git.example.com/project
-
-will provide human-friendly gitweb access.
-
-This solution is not 100% bulletproof, in the sense that if some project
-has a named ref (branch, tag) starting with 'git/', then paths such as
-
-http://git.example.com/project/command/abranch..git/abranch
-
-will fail with a 404 error.
+Web server configuration
+------------------------
+Gitweb can be run as CGI script, as legacy mod_perl application (using
+ModPerl::Registry), and as FastCGI script.  You can find some simple examples
+in "Example web server configuration" section in INSTALL file for gitweb (in
+gitweb/INSTALL).
 
+See "Webserver configuration" and "Advanced web server setup" sections in
+gitweb(1) manpage.
 
 
+AUTHORS
+-------
 Originally written by:
   Kay Sievers <kay.sievers@vrfy.org>
 
-- 
1.7.5

Re: [PATCHv3 1/5] gitweb: Move information about installation from README to INSTALL

[Jonathan Nieder]

Jakub Narebski wrote:

> Almost straightformard moving of "How to configure gitweb for your
> local system" section from gitweb/README to gitweb/INSTALL, as it is
> about build time configuration.  Updated references to it.
>
> Signed-off-by: Jakub Narebski <jnareb@gmail.com>

s/Updated/Update/.  The patch is obviously good; thanks for taking
care of it.

Re: [PATCHv3 2/5] gitweb: Describe CSSMIN and JSMIN in gitweb/INSTALL

[Jonathan Nieder]

Jakub Narebski wrote:

> The build-time configuration variables JSMIN and CSSMIN were mentioned
> only in Makefile; add their description to gitweb/INSTALL.
>
> This required moving description of GITWEB_JS up, near GITWEB_CSS and
> just introduced CSMIN and JSMIN.

Why does this require that?  Ah, to make the analogy with GITWEB_CSS
clear and because the JSMIN description refers to it.

> --- a/gitweb/INSTALL
> +++ b/gitweb/INSTALL
> @@ -147,6 +147,19 @@ You can specify the following configuration variables when building GIT:
[...]
> + * CSSMIN, JSMIN
> +   Invocation of a CSS minifier or a JavaScript minifier, respectively,
> +   working as a filter (source on standard input, minified result on
> +   standard output).  If set, it is used to generate a minified version of
> +   'static/gitweb.css' or 'static/gitweb.js', respectively.  *Note* that
> +   minified files would have *.min.css and *.min.js extension, which is
> +   important if you also set GITWEB_CSS and/or GITWEB_JS.  [No default]

When I first read this, I thought it meant these command lines were
going to be cooked into the gitweb script and invoked at run time.
Maybe (sorry for the rough text):

* CSSMIN, JSMIN
  Command for a CSS minifier or a Javascript minifier, working as a
  filter [...]
  These are used if defined to generate smaller, non human-readable
  versions of 'gitweb/gitweb.css' and 'static/gitweb.js' at
  'static/gitweb.min.css' and 'static/gitweb.min.js'.  Only the minified
  versions are installed, which is important if you also set GITWEB_CSS
  or GITWEB_JS.  [No default]

Aside from that, looks good.  Thanks.

Re: [PATCHv3 3/5] gitweb: Move "Requirements" up in gitweb/INSTALL

[Jonathan Nieder]

Jakub Narebski wrote:

> This way you can examine prerequisites at first glance

Yes, good idea.

Re: [RFC/PATCHv3 4/5] gitweb: Starting work on a man page for /etc/gitweb.conf (WIP)

[Jonathan Nieder]

Jakub Narebski wrote:

> Some effort has
> been made to de-duplicate any of this.

:)

> * Much simpler "doc" target in gitweb/Makefile.  Now instead of
>   duplicating internal knowledge how Documentation/Makefile works we
>   simply delegate task to "gitweb-doc" target (a la "full-svn-test"
>   in t/Makefile) in Documentation/Makefile.

Seems sensible as long as the main Makefile never learns

	gitweb-doc:
		$(MAKE) -C gitweb doc

The toplevel Makefile could do "$(MAKE) -C Documentation gitweb-doc"
and still avoid the usual pitfalls of recursive make stepping on its
own toes.

Longer term, I would like to try making gitweb/Makefile include a
build-helpers/Makefile.doc library and moving this documentation back
to the gitweb/ directory, which would make the gitweb directory
self-contained again (except for the build-helpers/Makefile.doc file).
Not sure what to do about that "except for..." bit.  I don't think my
half-baked long-term ideas should be allowed to slow this down. ;-)

> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -3,7 +3,7 @@ MAN1_TXT= \
>  		$(wildcard git-*.txt)) \
>  	gitk.txt git.txt
>  MAN5_TXT=gitattributes.txt gitignore.txt gitmodules.txt githooks.txt \
> -	gitrepository-layout.txt
> +	gitrepository-layout.txt gitweb.conf.txt
>  MAN7_TXT=gitcli.txt gittutorial.txt gittutorial-2.txt \
>  	gitcvs-migration.txt gitcore-tutorial.txt gitglossary.txt \
>  	gitdiffcore.txt gitrevisions.txt gitworkflows.txt
> @@ -170,6 +170,9 @@ info: git.info gitman.info
>  
>  pdf: user-manual.pdf
>  
> +GITWEB_DOC = $(filter gitweb.%,$(DOC_HTML) $(DOC_MAN1) $(DOC_MAN5) $(DOC_MAN7))
> +gitweb-doc: $(GITWEB_DOC)

Nice.

> @@ -334,4 +337,4 @@ quick-install-man:
>  quick-install-html:
>  	'$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(HTML_REF) $(DESTDIR)$(htmldir)
>  
> -.PHONY: FORCE
> +.PHONY: FORCE gitweb-doc

Is there any reason other phony targets (like "install" and "pdf")
aren't listed here?

> --- /dev/null
> +++ b/Documentation/gitweb.conf.txt
> @@ -0,0 +1,716 @@
> +gitweb.conf(5)
> +==============
> +
> +NAME
> +----
> +gitweb.conf - Gitweb configuration file

I suppose the novice can look to the DESCRIPTION or SEE ALSO section
to learn what gitweb is.

> +SYNOPSIS
> +--------
> +[verse]
> +'/etc/gitweb.conf'
> +'$GITWEBDIR/gitweb_config.perl'

Micronit: a single line like

	SYNOPSIS
	--------
	$GITWEBDIR/gitweb_config.perl, /etc/gitweb.conf

might fit better with the pattern established by gitattributes(5) and
its kin.

> +DESCRIPTION
> +-----------
> +The gitweb CGI script for viewing Git repositories over the web uses a
> +perl script fragment as its configuration file.  You can set variables
> +using "`our $variable = value`"; text from a "#" character until the
> +end of a line is ignored.  See *perlsyn*(1) for details.
> +
> +An example:
> +
> +    # gitweb configuration file for http://git.example.org
> +    #
> +    our $projectroot = "/srv/git"; # FHS recommendation
> +    our $site_name = 'Example.org >> Repos';

Nice.

> +The configuration file is used to override the default settings that
> +were built into gitweb at the time 'gitweb.cgi' script was generated.
> +
> +While one could just alter the configuration settings in the gitweb
> +CGI itself, those changes would be lost upon upgrade.

What if I upgrade using RCS "merge"? :)  So maybe:

	s/one could just alter/one can alter/
	s/would be lost/could be lost/

to clarify that (1) editing the CGI script is allowed and fine but (2)
it might be a pain to keep those changes.

> Configuration
> +settings might also be placed into a file in the same directory as the
> +CGI script with the default name 'gitweb_config.perl' -- allowing
> +one to have multiple gitweb instances with different configurations by
> +the use of symlinks.

Might also in addition to what?  Continuing the thought from before:

	So gitweb allows settings to be placed in a separate file named
	'gitweb_config.perl' in the same directory as the CGI script.
	This also allows one to set up multiple gitweb instances with
	different configurations by using symlinks to a common gitweb.cgi
	script.

> +DISCUSSION
> +----------

First, as a general thought, by the time I get this far I start
thinking, "so where's the list of possible settings?".  But there are
certainly some more basic pieces of information to cover before then
(like the global configuration file), so I think this part is in the
right place.  It just could benefit from being a little shorter.

> +The location of system-wide gitweb configuration file is defined at compile
> +time using the configuration value `GITWEB_CONFIG_SYSTEM` and defaults to
> +'/etc/gitweb.conf'.  The name of the per-instance configuration file is
> +defined in gitweb by `GITWEB_CONFIG`, and defaults to 'gitweb_config.perl'
> +(relative path means located in the same directory gitweb is installed).

Maybe:

	In addition to the per-instance configuration file, there can
	be a system-wide configuration file to act as a fallback when
	the per-instance configuration file does not exist.

	The system-wide configuration file is named /etc/gitweb.conf
	by default.  Filenames for the system-wide and per-instance
	configuration variables can be overridden at compile time and
	run time; see the FILES section for details.

[...]
> +Values defined in configuration files override built-in values found in the
> +gitweb CGI.

Reasonable.

> +*NOTE:* If per-instance configuration file ('gitweb_config.perl') exists,
> +then system-wide configuration file ('/etc/gitweb.conf') is _not used at
> +all_!!!

Over the top. :)  I think the best way to document this is to contrast
it with /etc/gitweb-common.conf once the latter exists.

> +The syntax of the configuration files is that of Perl, as these files are
> +indeed handled as fragments of Perl code (the language that gitweb itself is
> +written in). Variables may be set using "`our $variable = value`"; text from
> +"#" character until the end of a line is ignored. See the *perlsyn*(1) man
> +page for more information.

Duplicates DESCRIPTION.

> +
> +Actually using `our` qualifier in `our $variable = <value>;` is a safety
> +check: if newer gitweb does no longer use given variable, by using `our` we
> +won't get syntax errors.

Maybe this could move to a later NOTES section?

> +
> +The default configuration with no configuration file at all may work
> +perfectly well for some installations.  Still, a configuration file is
> +useful for customizing or tweaking the behavior of gitweb in many ways, and
> +some optional features will not be present unless explicitly enabled using
> +the configurable `%features` variable (see also "Configuring gitweb
> +features" section below).

I suppose this is based on the text

	The most notable thing that is not configurable at compile time are the
	optional features, stored in the '%features' variable.

I'd suggest removing the paragraph.

> +CONFIGURATION VARIABLES
> +-----------------------
> +Some of configuration variables have their default values (embedded in CGI
> +file) set during building gitweb -- if that is the case, it is put in their
> +description.  See gitweb's 'INSTALL' file for instructions on building and
> +installing gitweb.

Reasonable.  Nit: s/put/mentioned/

> +
> +Location of repositories
> +~~~~~~~~~~~~~~~~~~~~~~~~
> +Configuration variables described below control finding git repositories by
> +gitweb, and control display and access to repositories.

	The configuration variables described below determine where gitweb looks
	for repositories and which will be displayed.

(missing "The", elaboring on what it means to control repository search.)

> +
> +$projectroot::
> +	Absolute filesystem path which will be prepended to project path;
> +	the path to repository is `$projectroot/$project`.  Set to
> +	`$GITWEB_PROJECTROOT` during installation.  This variable has to be
> +	set correctly for gitweb to find repositories.
> ++
> +For example if `$projectroot` is set to "/srv/git" by putting the following
> +in gitweb config file:
> +----------------------------------------------------------------------------
> +our $projectroot = "/srv/git";
> +----------------------------------------------------------------------------
> +then
> +------------------------------------------------
> +http://git.example.com/gitweb.cgi?p=foo/bar.git
> +------------------------------------------------
> +or its path_info based equivalent
> +------------------------------------------------
> +http://git.example.com/gitweb.cgi/foo/bar.git
> +------------------------------------------------
> +will map to path '/srv/git/foo/bar.git' on filesystem.

Nice.  s/(path|filesystem)/the &/

> +
> +$project_maxdepth::
> +	Filesystem traversing depth limit for recursively scanning for git
> +	repositories, used if `$projects_list` (below) is unset.  The default
> +	value of this variable is determined by build-time configuration
> +	variable `GITWEB_PROJECT_MAXDEPTH`, which defaults to 2007.

gitweb/INSTALL says:

	The filesystem traversing limit for getting the project list; the number
	is taken as depth relative to the projectroot.  It is used when
	GITWEB_LIST is a directory (or is not set; then project root is used).
	This is meant to speed up project listing on large work trees by limiting
	search depth.  [Default: 2007]

I'm still not clear on what it actually means.  Is it used when
$projects_list points to a directory or not?  What if $projects_list
points to a file with lines that name directories?  What happens
when listing forks of a repository?

> +
> +$projects_list::
> +	Plain text file listing projects or name of directory
> +	to be scanned for projects.
> +
> +	Project list files should list one project per line, with each line
> +	having the following format
> +-----------------------------------------------------------------------------
> +<URI-encoded filesystem path to repository> SP <URI-encoded repository owner>
> +-----------------------------------------------------------------------------
> +
> +The default value of this variable is determined by the `GITWEB_LIST`
> +makefile variable at installation time.  If this variable is empty, gitweb
> +will fall back to scanning the `$projectroot` directory for repositories.

This gets formatted with the second and later paragraphs being
unindented; presumably it needs a "+", like so:

		... paragraph 1 ...
	+
	--
	... remaining paragraphs ...
	--

Can't this point to a directory, too?

> +
> +$export_ok::
> +	Show repository only if this file exists (in repository).  Only
> +	effective if this variable evaluates to true.  Can be set during
> +	building gitweb via `GITWEB_EXPORT_OK`.  [No default / Not set]

Am I supposed to show a repository?  Ah, no, this is about what gitweb
does.  Maybe

	Filename to look for in repositories to determine whether to
	show them.  If this variable evaluates to true, gitweb will
	only show repositories that contain a magic file with that
	name; otherwise, which repositories gitweb shows is controlled
	by the $strict_export option.  Can be set when building gitweb
	using the `GITWEB_EXPORT_OK` variable.  [No default]

Might be simpler to put the documentation of $strict_export first.
gitweb/INSTALL says:

	gitweb
	shows repositories only if this file exists in its object database
	(if directory has the magic file named $export_ok)

but I assume what was meant is the git dir, not .git/objects.

Incidentally, wouldn't it be more intuitive to treat all values of
$export_ok as true (i.e., check "if (defined($export_ok))" instead of
"if ($export_ok)") so the user doesn't need to know what values perl
considers to be true?

> +$export_auth_hook::
> +	Show repository only if this subroutine returns true, when given as
> +	the only parameter the full path to the project.

		Subroutine to decide whether to show a project.  Its only
		parameter is the full filesystem path to the repository.
	+
	Example:

[...]
> +$strict_export::
> +	Only allow viewing of repositories also shown on the overview page.
> +	This for example makes `$gitweb_export_ok` file decide if repository is
> +	available and not only if it is shown.  If `$gitweb_list` points to
> +	file with list of project, only those repositories listed would be
> +	available for gitweb.  Can be set during building gitweb via
> +	`GITWEB_STRICT_EXPORT`.  [No default / Not set]

I think I'd put this before $export_ok (because simpler) and steal
text from INSTALL.

	By default, even if a project is not visible on the projects list
	page, you can view it by hand-crafting a gitweb URL.  Set the
	$strict_export variable to true if you want to only allow
	repositories shown on the overview page to be viewed.  Can be
	set during ...

> +Finding files
> +~~~~~~~~~~~~~
> +Those configuration variables tell gitweb where to find files.  Values of
> +those variables are paths on filesystem.  Of those only `$GIT` is required
> +to be (correctly) set for gitweb to be able to work; all the rest are
> +required only for extra configuration or extra features.

Perhaps:

	System paths
	~~~~~~~~~~~~
	These configuration variables tell gitweb where to find commands and 
	system files.  The values of these variables are commands or
	paths on the filesystem.  Of these, only ...

(s/those/these/; add some wiggle room since $GIT = "git" is allowed;
change the title to contrast with the repository location variables;
add a comma.)

> +
> +$GIT::
> +	Core git executable to use.  By default set to `$GIT_BINDIR/git`, which
> +	in turn is by default set to `$(bindir)/git`.  If you use git from binary
> +	package, set this to "/usr/bin/git".  This can just be "git" if your
> +	webserver has a sensible PATH.  If you have multiple git versions installed
> +	it can be used to choose which one to use.

A setting like $GIT = "git --exec-path=elsewhere" would not work
because the entire string is used as the first argument to execvp.
Not sure how to say it: maybe just

	Command name to use when running git commands.  By default
	this is set to ...

("command name" being a phrase I made up on the spot for "path or
bare command name, suitable for passing to execvp".)

I think a better default would be "git", so if a newer git gets
installed in /usr/local/bin then gitweb would notice automatically.

> +$mimetypes_file::
> +	File to use for (filename extension based) guessing of MIME types before
> +	trying '/etc/mime.types'.  Path, if relative, is taken currently as
> +	relative to the current git repository.  [Unset by default]

What makes $mimetypes_file fit in this section but not $export_ok?  (I
have no good answer.  Maybe a separate section for MIME type guessing
would be more discoverable?)

> +
> +$highlight_bin::
> +	Path to the highlight executable to use (must be the one from
> +	http://www.andre-simon.de due to assumptions about parameters and output).
> +	Useful if 'highlight' is not installed on your webserver's PATH.
> +
> +	*Note* that if you want to add support for new syntax (supported by
> +	"highlight" but not used by gitweb), you need to modify `%highlight_ext`
> +	or `%highlight_basename`, depending on whether you detect type of file
> +	based on extension (for example "*.sh") or on its basename (for example
> +	"Makefile").  Keys of those hashes are extension or basename,
> +	respectively, and value for given key is name of syntax to be passed via
> +	`--syntax <syntax>` to highlighter.
> +
> +	[Default: 'highlight']

Needs "+" continuation lines, presumably.

> +Links and their targets
> +~~~~~~~~~~~~~~~~~~~~~~~
> +Configuration variables described below configure some of gitweb links:
> +their target and their look (text or image), and where to find page
> +prerequisites (stylesheet, favicon, images, scripts).  Usually they are left
> +at their default values, with the possible exception of `@stylesheets`
> +variable.

Does "Usually they are left at" mean "Usually there is no reason to change
them from"?  Aside from that, makes sense.

> +
> +@stylesheets::
> +	List of URIs of stylesheets (relative to base URI of a page). You
> +	might specify more than one stylesheet, for example use gitweb.css
> +	as base, with site specific modifications in separate stylesheet
> +	to make it easier to upgrade gitweb. You can add a `site` stylesheet
> +	for example by putting
> +----------------------------------------------------------------------------
> +push @stylesheets, "gitweb-site.css";
> +----------------------------------------------------------------------------
> +in the gitweb config file.  Those values that are relative paths, are
> +relative to base URI of gitweb.
> +
> +This list should contain URI of gitweb's stylesheet.  The URI of gitweb
> +stylesheet is set during build time via `GITWEB_CSS` variable.  It's default
> +value is 'static/gitweb.css' (or 'static/gitweb.min.css' if the `CSSMIN`
> +variable is defined, i.e. if CSS minifier is used during build.
> +
> +*Note*: there is also legacy `$stylesheet` configuration variable, which was
> +used by older gitweb.

s/gitweb$/gitweb's/; s/It's/Its/.  Missing closing paren, I think.

s/legacy/the legacy/.  How does this interact with the legacy setting (e.g.,
if I am new on my job as gitweb administrator and encounter such a line,
what does it mean and what would I want to change it to)?

Missing "+" continuation lines.

> +
> +$logo::
> +	Points to the location where you put 'git-logo.png' on your web
> +	server, or to be more generic URI of logo, 72x27 size).  This image
> +	is displayed in top right corner of each gitweb page, and used as
> +	logo for Atom feed.  Relative to base URI of gitweb (as a path).
> +	Can be adjusted during building gitweb using `GITWEB_LOGO` variable
> ++
> +	[Default: 'static/git-logo.png']

Re "as a path": can this be a URI pointing to another server if I want
it to?

[...]
> +$home_link::
> +	Target of the home link on top of all pages (the first part of view
> +	"breadcrumbs").  By default set to absolute URI of a page ($my_uri).

s/By default set to absolute URI of a page/The default is the absolute
URI for the gitweb script/

Stopping here.  Will resume later but since having something is better
than nothing, I am tempted to say this should be applied e.g. to
"next" so people can start using it right away and finding/fixing
documentation bugs.

Re: [RFC/PATCHv3 4/5] gitweb: Starting work on a man page for /etc/gitweb.conf (WIP)

[Jonathan Nieder]

Jonathan Nieder wrote:
> Jakub Narebski wrote:

>> +$GIT::
>> +	Core git executable to use.  By default set to `$GIT_BINDIR/git`, which
[...]
> I think a better default would be "git", so if a newer git gets
> installed in /usr/local/bin then gitweb would notice automatically.

Wait, that's quite wrong.  What I was forgetting about is the case
where the webmaster does not control the web hosting but just has a
place to drop CGI scripts under ~/public_html/cgi-bin.  In such a case
it would be very convenient that "make install-gitweb" just does the
right thing (including using a private copy of git).

Sorry for the nonsense.

Re: [RFC/PATCHv3 4/5] gitweb: Starting work on a man page for /etc/gitweb.conf (WIP)

[Drew Northup]

On Mon, 2011-06-06 at 17:12 -0500, Jonathan Nieder wrote:
> Jakub Narebski wrote:


> > +SYNOPSIS
> > +--------
> > +[verse]
> > +'/etc/gitweb.conf'
> > +'$GITWEBDIR/gitweb_config.perl'
> 
> Micronit: a single line like
> 
> 	SYNOPSIS
> 	--------
> 	$GITWEBDIR/gitweb_config.perl, /etc/gitweb.conf
> 
> might fit better with the pattern established by gitattributes(5) and
> its kin.

I thought that's how I had originally put it.
> 
> > +DESCRIPTION
> > +-----------
> > +The gitweb CGI script for viewing Git repositories over the web uses a
> > +perl script fragment as its configuration file.  You can set variables
> > +using "`our $variable = value`"; text from a "#" character until the
> > +end of a line is ignored.  See *perlsyn*(1) for details.
> > +
> > +An example:
> > +
> > +    # gitweb configuration file for http://git.example.org
> > +    #
> > +    our $projectroot = "/srv/git"; # FHS recommendation
> > +    our $site_name = 'Example.org >> Repos';
> 
> Nice.
> 
> > +The configuration file is used to override the default settings that
> > +were built into gitweb at the time 'gitweb.cgi' script was generated.
> > +
> > +While one could just alter the configuration settings in the gitweb
> > +CGI itself, those changes would be lost upon upgrade.
> 
> What if I upgrade using RCS "merge"? :)  So maybe:
> 
> 	s/one could just alter/one can alter/
> 	s/would be lost/could be lost/
> 
> to clarify that (1) editing the CGI script is allowed and fine but (2)
> it might be a pain to keep those changes.

The point of this was originally if you were a mere mortal then upgrades
of the gitweb CGI would flush all of the settings you just spent a week
getting right down the drain. That's the point of the stronger language.
It's meant to be a solid "If you do it that way you can expect it to
hurt" message.
> 
> > Configuration
> > +settings might also be placed into a file in the same directory as the
> > +CGI script with the default name 'gitweb_config.perl' -- allowing
> > +one to have multiple gitweb instances with different configurations by
> > +the use of symlinks.
> 
> Might also in addition to what?  

This comment is nonsensical, please clarify it.

> Continuing the thought from before:
> 
> 	So gitweb allows settings to be placed in a separate file named
> 	'gitweb_config.perl' in the same directory as the CGI script.
> 	This also allows one to set up multiple gitweb instances with
> 	different configurations by using symlinks to a common gitweb.cgi
> 	script.

How is this any different from what I wrote?
> 
> > +DISCUSSION
> > +----------
> 
> First, as a general thought, by the time I get this far I start
> thinking, "so where's the list of possible settings?".  But there are
> certainly some more basic pieces of information to cover before then
> (like the global configuration file), so I think this part is in the
> right place.  It just could benefit from being a little shorter.

I used resolv.conf(5) as the model here. I realized that without a
little introduction most of the settings and the way they are applied
didn't make a heck of a lot of sense if you've never seen them before.
> 
> > +The location of system-wide gitweb configuration file is defined at compile
> > +time using the configuration value `GITWEB_CONFIG_SYSTEM` and defaults to
> > +'/etc/gitweb.conf'.  The name of the per-instance configuration file is
> > +defined in gitweb by `GITWEB_CONFIG`, and defaults to 'gitweb_config.perl'
> > +(relative path means located in the same directory gitweb is installed).
> 
> Maybe:
> 
> 	In addition to the per-instance configuration file, there can
> 	be a system-wide configuration file to act as a fallback when
> 	the per-instance configuration file does not exist.
> 
> 	The system-wide configuration file is named /etc/gitweb.conf
> 	by default.  Filenames for the system-wide and per-instance
> 	configuration variables can be overridden at compile time and
> 	run time; see the FILES section for details.

This is the manpage for the system wide configuration file. If you'd
like to scrap this effort in favor of something else please speak up.
> 
> [...]
> > +Values defined in configuration files override built-in values found in the
> > +gitweb CGI.
> 
> Reasonable.
> 
> > +*NOTE:* If per-instance configuration file ('gitweb_config.perl') exists,
> > +then system-wide configuration file ('/etc/gitweb.conf') is _not used at
> > +all_!!!
> 
> Over the top. :)  I think the best way to document this is to contrast
> it with /etc/gitweb-common.conf once the latter exists.

If we were to change gitweb to handle configuration files like the rest
of git (and in fact like most things we deal with daily, where settings
are overridden one by one) then this section becomes moot. Until or
unless that becomes the case it is important to loudly make note of it. 

Also (and unfortunately), what appears to be truly over the top markup
in plain text is just barely visible in the compiled manpage and is
actually reasonable in the (X)HTML version. Please check the final
output before complaining about my markup, if that is indeed your
intent.
> 
> > +The syntax of the configuration files is that of Perl, as these files are
> > +indeed handled as fragments of Perl code (the language that gitweb itself is
> > +written in). Variables may be set using "`our $variable = value`"; text from
> > +"#" character until the end of a line is ignored. See the *perlsyn*(1) man
> > +page for more information.
> 
> Duplicates DESCRIPTION.

Perhaps it does, but not everybody is a Perl coder. It was that way in
the text I started from and I saw little point in changing it.
> 
> > +
> > +Actually using `our` qualifier in `our $variable = <value>;` is a safety
> > +check: if newer gitweb does no longer use given variable, by using `our` we
> > +won't get syntax errors.
> 
> Maybe this could move to a later NOTES section?

Fine with me.
> 
> > +
> > +The default configuration with no configuration file at all may work
> > +perfectly well for some installations.  Still, a configuration file is
> > +useful for customizing or tweaking the behavior of gitweb in many ways, and
> > +some optional features will not be present unless explicitly enabled using
> > +the configurable `%features` variable (see also "Configuring gitweb
> > +features" section below).
> 
> I suppose this is based on the text
> 
> 	The most notable thing that is not configurable at compile time are the
> 	optional features, stored in the '%features' variable.
> 
> I'd suggest removing the paragraph.

The motivation for this paragraph was actually the innumerable tutorials
out there which tell people to mangle the CGI directly because:
(1) There didn't seem to be a standard documented configuration file
(2) There wasn't an appropriate place to shove %features settings that
the author could find.
(3) It really needed to be said that you might not actually have to mess
with anything.

Apparently you think that clearing these misconceptions up is a useless
exercise, or at least it sounds a lot like it.

> > +Links and their targets
> > +~~~~~~~~~~~~~~~~~~~~~~~
> > +Configuration variables described below configure some of gitweb links:
> > +their target and their look (text or image), and where to find page
> > +prerequisites (stylesheet, favicon, images, scripts).  Usually they are left
> > +at their default values, with the possible exception of `@stylesheets`
> > +variable.
> 
> Does "Usually they are left at" mean "Usually there is no reason to change
> them from"?  Aside from that, makes sense.

Yes, that's equivalent.

> 
> Stopping here.  Will resume later but since having something is better
> than nothing, I am tempted to say this should be applied e.g. to
> "next" so people can start using it right away and finding/fixing
> documentation bugs.

And so am I [stopping], I suppose. I have had work to do for the past
few weeks that really caused me to NEED my weekends for things other
than writing code and flossing documentation. Unless I am needed for
something I'm going to just let this live or die on it's own for now, as
I cannot keep up with this pace of patching right now. (That was in
large part the whole point of my flagging this as WIP.)
-- 
-Drew Northup
________________________________________________
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59

Re: [RFC/PATCHv3 4/5] gitweb: Starting work on a man page for /etc/gitweb.conf (WIP)

[Jonathan Nieder]

Hi,

Drew Northup wrote:
> On Mon, 2011-06-06 at 17:12 -0500, Jonathan Nieder wrote:

>> Micronit: a single line like
>>
>> 	SYNOPSIS
>> 	--------
>> 	$GITWEBDIR/gitweb_config.perl, /etc/gitweb.conf
>>
>> might fit better with the pattern established by gitattributes(5) and
>> its kin.
>
> I thought that's how I had originally put it.

I take that as a "yes, it would work better".

To save others the trouble of digging previous rounds up for
comparison:

 - the original: http://thread.gmane.org/gmane.comp.version-control.git/173422
 - v2: http://thread.gmane.org/gmane.comp.version-control.git/174700/focus=174701
 - v3: http://thread.gmane.org/gmane.comp.version-control.git/175140/focus=175145

The original had one line but it didn't mention
$GITWEBDIR/gitweb_config.perl.  So we are slowly converging.

[...]
>>> +The configuration file is used to override the default settings that
>>> +were built into gitweb at the time 'gitweb.cgi' script was generated.
>>> +
>>> +While one could just alter the configuration settings in the gitweb
>>> +CGI itself, those changes would be lost upon upgrade.
>>
>> What if I upgrade using RCS "merge"? :)  So maybe:
>>
>> 	s/one could just alter/one can alter/
>> 	s/would be lost/could be lost/
>>
>> to clarify that (1) editing the CGI script is allowed and fine but (2)
>> it might be a pain to keep those changes.
>
> The point of this was originally if you were a mere mortal then upgrades
> of the gitweb CGI would flush all of the settings you just spent a week
> getting right down the drain. That's the point of the stronger language.
> It's meant to be a solid "If you do it that way you can expect it to
> hurt" message.

Sorry, I suppose I was unclear.  All I meant is that as a naïve
reader, I found myself losing trust with "those changes would be lost
upon upgrade".  Oddly enough, by contrast something like:

	While it would be possible to change the gitweb CGI directly
	instead, DON'T DO THAT!  Your changes would be lost on upgrade!

would have worked fine for me, since there are enough cues to know I
am reading hyperbole rather than an explanation of mechanism.

Anyway, it was just how I read it, and it's likely my proposed change
would have made it worse in some other way.

>>> Configuration
>>> +settings might also be placed into a file in the same directory as the
>>> +CGI script with the default name 'gitweb_config.perl' -- allowing
>>> +one to have multiple gitweb instances with different configurations by
>>> +the use of symlinks.
>>
>> Might also in addition to what?  
>
> This comment is nonsensical, please clarify it.

I found the sentence starting with "Configuration settings" hard to
understand because the "also" didn't have an obvious antecedent.
Therefore I proposed some alternative phrasing:

>> Continuing the thought from before:
>>
>> 	So gitweb allows settings to be placed in a separate file named
>> 	'gitweb_config.perl' in the same directory as the CGI script.
>> 	This also allows one to set up multiple gitweb instances with
>> 	different configurations by using symlinks to a common gitweb.cgi
>> 	script.
>
> How is this any different from what I wrote?

I'm starting to sense annoyance.  Please feel free to ignore my
comments if you think they're unhelpful; they're meant as a gift, not
demands.

Anyway, the difference is in phrasing.  Saying "So" is meant to make
the relationship to the previous sentence clearer: we are explaining
the purpose of the configuration file, by contrasting it with editing
the CGI script directly.  The next sentence is a separate thought, so
I thought it might be clearer to put it in a separate sentence.

>>> +DISCUSSION
>>> +----------
>>
>> First, as a general thought, by the time I get this far I start
>> thinking, "so where's the list of possible settings?".  But there are
>> certainly some more basic pieces of information to cover before then
>> (like the global configuration file), so I think this part is in the
>> right place.  It just could benefit from being a little shorter.
>
> I used resolv.conf(5) as the model here. I realized that without a
> little introduction most of the settings and the way they are applied
> didn't make a heck of a lot of sense if you've never seen them before.

Yes, I think the general structure is good.

>>> +The location of system-wide gitweb configuration file is defined at compile
>>> +time using the configuration value `GITWEB_CONFIG_SYSTEM` and defaults to
>>> +'/etc/gitweb.conf'.  The name of the per-instance configuration file is
>>> +defined in gitweb by `GITWEB_CONFIG`, and defaults to 'gitweb_config.perl'
>>> +(relative path means located in the same directory gitweb is installed).
>>
>> Maybe:
>>
>> 	In addition to the per-instance configuration file, there can
>> 	be a system-wide configuration file to act as a fallback when
>> 	the per-instance configuration file does not exist.
>>
>> 	The system-wide configuration file is named /etc/gitweb.conf
>> 	by default.  Filenames for the system-wide and per-instance
>> 	configuration variables can be overridden at compile time and
>> 	run time; see the FILES section for details.
>
> This is the manpage for the system wide configuration file. If you'd
> like to scrap this effort in favor of something else please speak up.

Huh?

>>> +*NOTE:* If per-instance configuration file ('gitweb_config.perl') exists,
>>> +then system-wide configuration file ('/etc/gitweb.conf') is _not used at
>>> +all_!!!
>>
>> Over the top. :)  I think the best way to document this is to contrast
>> it with /etc/gitweb-common.conf once the latter exists.
>
> If we were to change gitweb to handle configuration files like the rest
> of git (and in fact like most things we deal with daily, where settings
> are overridden one by one) then this section becomes moot. Until or
> unless that becomes the case it is important to loudly make note of it. 

Does using three exclamation marks and italics make it clearer?

Previously there was no manpage documenting this at all, so I think
explaining it is already a big and good step.  If this needs to be
so prominent that people just skimming through will notice it, then
I'd suggest putting it in the DESCRIPTION section higher up.  But I'm
not the one writing this; others are free to disagree.

>>> +The syntax of the configuration files is that of Perl, as these files are
[...]
>>> +page for more information.
>>
>> Duplicates DESCRIPTION.
>
> Perhaps it does, but not everybody is a Perl coder. It was that way in
> the text I started from and I saw little point in changing it.

No, the paragraph is actually repeated from the DESCRIPTION section.

[...]
>>> +The default configuration with no configuration file at all may work
>>> +perfectly well for some installations.  Still, a configuration file is
>>> +useful for customizing or tweaking the behavior of gitweb in many ways, and
>>> +some optional features will not be present unless explicitly enabled using
>>> +the configurable `%features` variable (see also "Configuring gitweb
>>> +features" section below).
>>
>> I suppose this is based on the text
>> 
>> 	The most notable thing that is not configurable at compile time are the
>> 	optional features, stored in the '%features' variable.
>> 
>> I'd suggest removing the paragraph.
>
> The motivation for this paragraph was actually the innumerable tutorials
> out there which tell people to mangle the CGI directly because:
> (1) There didn't seem to be a standard documented configuration file
> (2) There wasn't an appropriate place to shove %features settings that
> the author could find.
> (3) It really needed to be said that you might not actually have to mess
> with anything.
>
> Apparently you think that clearing these misconceptions up is a useless
> exercise, or at least it sounds a lot like it.

What?  I wrote exactly what I was thinking, which was that I thought this
paragraph was based on the text I quoted from gitweb/INSTALL and that
contrasting the run-time and compile-time configuration as that
paragraph did didn't seem very important for the installed manpage
(since the reader might not have been involved in the installation at
all).

If the point was actually to say "Contrary to popular belief, you can
set %features in the configuration file instead of hard-coding it in
the CGI script itself", why not say that directly?

[...]
> I cannot keep up with this pace of patching right now.

No problem.  For what it's worth, I skipped a couple of rounds of
reading, too; I suppose they came quickly.  Does that mean you don't
want to be cc-ed on later incarnations of the patch, or would you like
to stay notified?

It seems my review was not very useful; sorry about that.  Thanks for
some clarifications.

Ciao,
Jonathan

Re: [RFC/PATCHv3 4/5] gitweb: Starting work on a man page for /etc/gitweb.conf (WIP)

[Drew Northup]

On Tue, 2011-06-07 at 08:44 -0500, Jonathan Nieder wrote:
> Hi,
> 
> Drew Northup wrote:
> > On Mon, 2011-06-06 at 17:12 -0500, Jonathan Nieder wrote:
> 
> >> Micronit: a single line like
> >>
> >> 	SYNOPSIS
> >> 	--------
> >> 	$GITWEBDIR/gitweb_config.perl, /etc/gitweb.conf
> >>
> >> might fit better with the pattern established by gitattributes(5) and
> >> its kin.
> >
> > I thought that's how I had originally put it.
> 
> I take that as a "yes, it would work better".

Agreed, it would.
> 
> To save others the trouble of digging previous rounds up for
> comparison:
> 
>  - the original: http://thread.gmane.org/gmane.comp.version-control.git/173422
>  - v2: http://thread.gmane.org/gmane.comp.version-control.git/174700/focus=174701
>  - v3: http://thread.gmane.org/gmane.comp.version-control.git/175140/focus=175145
> 
> The original had one line but it didn't mention
> $GITWEBDIR/gitweb_config.perl.  So we are slowly converging.

Thanks for looking that up (and the refs above).
> 
> [...]
> >>> +The configuration file is used to override the default settings that
> >>> +were built into gitweb at the time 'gitweb.cgi' script was generated.
> >>> +
> >>> +While one could just alter the configuration settings in the gitweb
> >>> +CGI itself, those changes would be lost upon upgrade.
> >>
> >> What if I upgrade using RCS "merge"? :)  So maybe:
> >>
> >> 	s/one could just alter/one can alter/
> >> 	s/would be lost/could be lost/
> >>
> >> to clarify that (1) editing the CGI script is allowed and fine but (2)
> >> it might be a pain to keep those changes.
> >
> > The point of this was originally if you were a mere mortal then upgrades
> > of the gitweb CGI would flush all of the settings you just spent a week
> > getting right down the drain. That's the point of the stronger language.
> > It's meant to be a solid "If you do it that way you can expect it to
> > hurt" message.
> 
> Sorry, I suppose I was unclear.  All I meant is that as a naïve
> reader, I found myself losing trust with "those changes would be lost
> upon upgrade".  Oddly enough, by contrast something like:
> 
> 	While it would be possible to change the gitweb CGI directly
> 	instead, DON'T DO THAT!  Your changes would be lost on upgrade!
> 
> would have worked fine for me, since there are enough cues to know I
> am reading hyperbole rather than an explanation of mechanism.
> 
> Anyway, it was just how I read it, and it's likely my proposed change
> would have made it worse in some other way.

Your complaint is valid from the perspective you just outlined. The
point I was trying to drive home was that you can expect the upgrade
process to replace the executable because that's what upgrades do--they
replace executables. Obviously stating it that plainly to somebody
unfamiliar with how the whole install/upgrade process works at the
filesystem level isn't going to be very helpful. Perhaps a combination
of the "one can alter" and "are likely to be overwritten [upon upgrade]"
would do the trick?
> 
> >>> Configuration
> >>> +settings might also be placed into a file in the same directory as the
> >>> +CGI script with the default name 'gitweb_config.perl' -- allowing
> >>> +one to have multiple gitweb instances with different configurations by
> >>> +the use of symlinks.
> >>
> >> Might also in addition to what?  
> >
> > This comment is nonsensical, please clarify it.
> 
> I found the sentence starting with "Configuration settings" hard to
> understand because the "also" didn't have an obvious antecedent.
> Therefore I proposed some alternative phrasing:
> 
> >> Continuing the thought from before:
> >>
> >> 	So gitweb allows settings to be placed in a separate file named
> >> 	'gitweb_config.perl' in the same directory as the CGI script.
> >> 	This also allows one to set up multiple gitweb instances with
> >> 	different configurations by using symlinks to a common gitweb.cgi
> >> 	script.
> >
> > How is this any different from what I wrote?
> 
> I'm starting to sense annoyance.  Please feel free to ignore my
> comments if you think they're unhelpful; they're meant as a gift, not
> demands.
> 
> Anyway, the difference is in phrasing.  Saying "So" is meant to make
> the relationship to the previous sentence clearer: we are explaining
> the purpose of the configuration file, by contrasting it with editing
> the CGI script directly.  The next sentence is a separate thought, so
> I thought it might be clearer to put it in a separate sentence.

Yes, annoyance would be the right word. I was trying very hard to find
how what you were proposing was different and not finding it (other than
what appeared to me to be dealing with the reader in a disrespectful
manner). Now that I know where you were aiming I can think about an
appropriate change. (I'm not there yet, but it may very well come to
me.)
In any case, these are things that I'd need to see not in patch context,
but as part of the larger file to make much sense of. I seem to recall
that something is missing here that was prior to the words
"Configuration settings" in my original, which I'll have to check on. If
that is the case it would explain the lack antecedent clarity you noted.
If not then the text could be made more clear unto itself.

> >>> +The location of system-wide gitweb configuration file is defined at compile
> >>> +time using the configuration value `GITWEB_CONFIG_SYSTEM` and defaults to
> >>> +'/etc/gitweb.conf'.  The name of the per-instance configuration file is
> >>> +defined in gitweb by `GITWEB_CONFIG`, and defaults to 'gitweb_config.perl'
> >>> +(relative path means located in the same directory gitweb is installed).
> >>
> >> Maybe:
> >>
> >> 	In addition to the per-instance configuration file, there can
> >> 	be a system-wide configuration file to act as a fallback when
> >> 	the per-instance configuration file does not exist.
> >>
> >> 	The system-wide configuration file is named /etc/gitweb.conf
> >> 	by default.  Filenames for the system-wide and per-instance
> >> 	configuration variables can be overridden at compile time and
> >> 	run time; see the FILES section for details.
> >
> > This is the manpage for the system wide configuration file. If you'd
> > like to scrap this effort in favor of something else please speak up.
> 
> Huh?

If this is what you are proposing then we should be working on a
"gitweb_config.perl" manpage and not a "gitweb.conf" manpage. I know a
fair number of people around here put priority on the former and would
just as soon ignore the latter. That's what your proposed change says to
me (while I also understand that your own position is likely far more
nuanced than that).
> 
> >>> +*NOTE:* If per-instance configuration file ('gitweb_config.perl') exists,
> >>> +then system-wide configuration file ('/etc/gitweb.conf') is _not used at
> >>> +all_!!!
> >>
> >> Over the top. :)  I think the best way to document this is to contrast
> >> it with /etc/gitweb-common.conf once the latter exists.
> >
> > If we were to change gitweb to handle configuration files like the rest
> > of git (and in fact like most things we deal with daily, where settings
> > are overridden one by one) then this section becomes moot. Until or
> > unless that becomes the case it is important to loudly make note of it. 
> 
> Does using three exclamation marks and italics make it clearer?

That could probably be cut down to one, I'll grant you that. I was
trying to avoid use of the <blink> tag.
> 
> Previously there was no manpage documenting this at all, so I think
> explaining it is already a big and good step.  If this needs to be
> so prominent that people just skimming through will notice it, then
> I'd suggest putting it in the DESCRIPTION section higher up.  But I'm
> not the one writing this; others are free to disagree.

I thought seriously about doing that but decided against it as it took
this important bit of information out of the appropriate context. If I
don't present that there's more than one way to configure gitweb first
this text by itself doesn't make a whole lot of sense (and therefore
will likely be ignored).
> 
> >>> +The syntax of the configuration files is that of Perl, as these files are
> [...]
> >>> +page for more information.
> >>
> >> Duplicates DESCRIPTION.
> >
> > Perhaps it does, but not everybody is a Perl coder. It was that way in
> > the text I started from and I saw little point in changing it.
> 
> No, the paragraph is actually repeated from the DESCRIPTION section.

Well then, I suppose that is a problem! I don't recall doing that, but
it should be corrected. 
(As noted below and prior, I haven't been able to apply the interim
patches to my @home working copy, so if it came from there I currently
don't know it.)
> 
> [...]
> >>> +The default configuration with no configuration file at all may work
> >>> +perfectly well for some installations.  Still, a configuration file is
> >>> +useful for customizing or tweaking the behavior of gitweb in many ways, and
> >>> +some optional features will not be present unless explicitly enabled using
> >>> +the configurable `%features` variable (see also "Configuring gitweb
> >>> +features" section below).
> >>
> >> I suppose this is based on the text
> >> 
> >> 	The most notable thing that is not configurable at compile time are the
> >> 	optional features, stored in the '%features' variable.
> >> 
> >> I'd suggest removing the paragraph.
<snip>
> >
> > Apparently you think that clearing these misconceptions up is a useless
> > exercise, or at least it sounds a lot like it.
> 
> What?  I wrote exactly what I was thinking, which was that I thought this
> paragraph was based on the text I quoted from gitweb/INSTALL and that
> contrasting the run-time and compile-time configuration as that
> paragraph did didn't seem very important for the installed manpage
> (since the reader might not have been involved in the installation at
> all).
> 
> If the point was actually to say "Contrary to popular belief, you can
> set %features in the configuration file instead of hard-coding it in
> the CGI script itself", why not say that directly?

Ok, we can do that (or something very much like it, whatever ends up
fitting best). Remember that this was sourced prior to our on-list
discussion about what came from gitweb/INSTALL being primarily fodder
for a different document. I haven't had the chance to modify it since,
and I have the impression that Jakub has been busy working on other
parts of this project (of which he's done quite a bit). Removing the
paragraph wholesale doesn't fix the problem so far as I see it, but the
presentation of the information can certainly be better tuned.
> 
> [...]
> > I cannot keep up with this pace of patching right now.
> 
> No problem.  For what it's worth, I skipped a couple of rounds of
> reading, too; I suppose they came quickly.  Does that mean you don't
> want to be cc-ed on later incarnations of the patch, or would you like
> to stay notified?

I'd like to stay cc'd, I just haven't been able to apply the previous
patch versions to my @home work tree before the next has come out,
limiting my chances to be able to effectively review them.

I apologize for being a bit snappy, but sometimes I really do have a low
tolerance for comments that just seem (to me) to be "this here is really
useless" complaints and not suggestions of an upgrade.
-- 
-Drew Northup
________________________________________________
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59

Re: [RFC/PATCHv3 4/5] gitweb: Starting work on a man page for /etc/gitweb.conf (WIP)

[Jakub Narebski]

Quick reply; more detailed responses will follow.

On Tue, 7 Jun 2011, Drew Northup wrote:
> On Tue, 2011-06-07 at 08:44 -0500, Jonathan Nieder wrote:
>> Drew Northup wrote:
>>> On Mon, 2011-06-06 at 17:12 -0500, Jonathan Nieder wrote:
>>>> Jakub Narebski wrote:

>>>>> +The location of system-wide gitweb configuration file is defined at compile
>>>>> +time using the configuration value `GITWEB_CONFIG_SYSTEM` and defaults to
>>>>> +'/etc/gitweb.conf'.  The name of the per-instance configuration file is
>>>>> +defined in gitweb by `GITWEB_CONFIG`, and defaults to 'gitweb_config.perl'
>>>>> +(relative path means located in the same directory gitweb is installed).
>>>>
>>>> Maybe:
>>>>
>>>> 	In addition to the per-instance configuration file, there can
>>>> 	be a system-wide configuration file to act as a fallback when
>>>> 	the per-instance configuration file does not exist.
>>>>
>>>> 	The system-wide configuration file is named /etc/gitweb.conf
>>>> 	by default.  Filenames for the system-wide and per-instance
>>>> 	configuration variables can be overridden at compile time and
>>>> 	run time; see the FILES section for details.
>>>
>>> This is the manpage for the system wide configuration file. If you'd
>>> like to scrap this effort in favor of something else please speak up.
>> 
>> Huh?
> 
> If this is what you are proposing then we should be working on a
> "gitweb_config.perl" manpage and not a "gitweb.conf" manpage. I know a
> fair number of people around here put priority on the former and would
> just as soon ignore the latter. That's what your proposed change says to
> me (while I also understand that your own position is likely far more
> nuanced than that).

I think this manpage is about both system-wide and per-instance config
file, just like gitignore is about both in-tree .gitignore and private
$GIT_DIR/info/exclude, like gitattributes is about both in-tree 
.gitattributes and $GIT_DIR/info/attributes,... just like ssh_config
is about both system-wide ssh_config and per-user .ssh/config.

And like all of those manpages are named after one file, just like
this manpage.

Perhaps we could even symlink/hardlink gitweb_config.perl manpage
to gitweb.conf manpage...


P.S. I am sorry that I didn't state more clear that I modified Drew's
original submission, and didn't write in more detail what I have changed.
Some of mistakes are mine, not Drew...

-- 
Jakub Narebski
Poland

Re: [RFC/PATCHv3 4/5] gitweb: Starting work on a man page for /etc/gitweb.conf (WIP)

[Junio C Hamano]

Drew Northup <drew.northup@maine.edu> writes:

> On Tue, 2011-06-07 at 08:44 -0500, Jonathan Nieder wrote:
> ...
> If this is what you are proposing then we should be working on a
> "gitweb_config.perl" manpage and not a "gitweb.conf" manpage. I know a
> fair number of people around here put priority on the former and would
> just as soon ignore the latter. That's what your proposed change says to
> me (while I also understand that your own position is likely far more
> nuanced than that).

Hmm, do you want to have two (and then three, see below) separate manpages
that essentially describe the same thing, and refer to each other when
they talk about the precedence order?

>> >>> +*NOTE:* If per-instance configuration file ('gitweb_config.perl') exists,
>> >>> +then system-wide configuration file ('/etc/gitweb.conf') is _not used at
>> >>> +all_!!!
>> >>
>> >> Over the top. :)  I think the best way to document this is to contrast
>> >> it with /etc/gitweb-common.conf once the latter exists.
>> >
>> > If we were to change gitweb to handle configuration files like the rest
>> > of git (and in fact like most things we deal with daily, where settings
>> > are overridden one by one) then this section becomes moot. Until or
>> > unless that becomes the case it is important to loudly make note of it. 
>> 
>> Does using three exclamation marks and italics make it clearer?
>
> That could probably be cut down to one, I'll grant you that. I was
> trying to avoid use of the <blink> tag.

I vaguely recall that there was an effort to document /etc/gitweb.conf as
a mere "fallback default", not a "system-wide configuration file", which
is what it is, and also to introduce a true "system-wide configuration" as
a separate file, so that the system-wide one will be read, and then either
per-instance gitweb_config.perl or the fallback default /etc/gitweb.conf
will update it. What happened to that effort?

In any case, with the current design, /etc/gitweb.conf is _not_ the
system-wide configuration file but it is a fallback default for instances
that do not have per-instance configuration, so the quoted part would need
rewording anyway, I think.

Re: [RFC/PATCHv3 4/5] gitweb: Starting work on a man page for /etc/gitweb.conf (WIP)

[Drew Northup]

On Tue, 2011-06-07 at 10:00 -0700, Junio C Hamano wrote:
> Drew Northup <drew.northup@maine.edu> writes:
> 
> > On Tue, 2011-06-07 at 08:44 -0500, Jonathan Nieder wrote:
> > ...
> > If this is what you are proposing then we should be working on a
> > "gitweb_config.perl" manpage and not a "gitweb.conf" manpage. I know a
> > fair number of people around here put priority on the former and would
> > just as soon ignore the latter. That's what your proposed change says to
> > me (while I also understand that your own position is likely far more
> > nuanced than that).
> 
> Hmm, do you want to have two (and then three, see below) separate manpages
> that essentially describe the same thing, and refer to each other when
> they talk about the precedence order?

No, I am just saying that if this isn't primarily meant to be
about /etc/gitweb.conf (which is what I was told to use here on this
very list) then we shouldn't name it after gitweb.conf, nor should we
focus on gitweb.conf (the removal of the gitweb.conf we are then
effectively deprecating can be discussed later; I have already voiced my
opinion on this strategy of ignoring /etc/gitweb.conf but still having
it anyway and been summarily declared insane).

The change he made isn't, to me anyway, one of precedence order but is
one of focus and theme. Perhaps most people around here aren't trained
to hew so closely to the stated purpose of a work as I am and therefore
don't see the change he suggested as starkly. So be it. 
I really don't like starting work on something for a project because I
was told that (1) it was needed and, (2) it would be welcome only to
find that neither statement was particularly true. I'd strongly prefer
to have been told from the outset "Don't bother to document that, as
you're the only one using it that way," and, "Document this instead, as
just because you're not using it doesn't mean that we don't think
everyone else should be."
> 
> >> >>> +*NOTE:* If per-instance configuration file ('gitweb_config.perl') exists,
> >> >>> +then system-wide configuration file ('/etc/gitweb.conf') is _not used at
> >> >>> +all_!!!
> >> >>
> >> >> Over the top. :)  I think the best way to document this is to contrast
> >> >> it with /etc/gitweb-common.conf once the latter exists.
> >> >
> >> > If we were to change gitweb to handle configuration files like the rest
> >> > of git (and in fact like most things we deal with daily, where settings
> >> > are overridden one by one) then this section becomes moot. Until or
> >> > unless that becomes the case it is important to loudly make note of it. 
> >> 
> >> Does using three exclamation marks and italics make it clearer?
> >
> > That could probably be cut down to one, I'll grant you that. I was
> > trying to avoid use of the <blink> tag.
> 
> I vaguely recall that there was an effort to document /etc/gitweb.conf as
> a mere "fallback default", not a "system-wide configuration file", which
> is what it is, and also to introduce a true "system-wide configuration" as
> a separate file, so that the system-wide one will be read, and then either
> per-instance gitweb_config.perl or the fallback default /etc/gitweb.conf
> will update it. What happened to that effort?

You shot it down, that's what. Or more correctly you shot down the use
of /etc/gitweb.conf as a system-wide source of default settings instead
proposing that it be used as a fallback (?) and that
an /etc/gitweb-defaults.conf (or something like that) be used as a
per-item default (or at least that's what I got out of what was said).
I'm not sure what to think of that, but I haven't had the chance to test
that patch-set in any case, much less incorporate it into the
documentation. All of that would come after I'm no longer confused as to
what the intended end-result would be.
> 
> In any case, with the current design, /etc/gitweb.conf is _not_ the
> system-wide configuration file but it is a fallback default for instances
> that do not have per-instance configuration, so the quoted part would need
> rewording anyway, I think.

And THAT is the problem. If it isn't a system-wide configuration file
then let's stop putting it in /etc, deprecate it, and get it over with.
I didn't even know that to be the case when I started writing this, I
was just trying to make more readily available the advice I'd been given
on this list. Only after getting started did I learn that gitweb treats
a file in /etc like nothing else I normally use (aside from
adduser/useradd's use of /etc/skel as a directory template).

I'm crawling back into my hole now.
-- 
-Drew Northup
________________________________________________
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59

Re: [RFC/PATCHv3 4/5] gitweb: Starting work on a man page for /etc/gitweb.conf (WIP)

[Jakub Narebski]

On Tue, 7 June 2011, Drew Northup wrote:
> On Tue, 2011-06-07 at 10:00 -0700, Junio C Hamano wrote:
>> Drew Northup <drew.northup@maine.edu> writes:
>> 
>>> On Tue, 2011-06-07 at 08:44 -0500, Jonathan Nieder wrote:
>>> ...
>>> If this is what you are proposing then we should be working on a
>>> "gitweb_config.perl" manpage and not a "gitweb.conf" manpage. I know a
>>> fair number of people around here put priority on the former and would
>>> just as soon ignore the latter. That's what your proposed change says to
>>> me (while I also understand that your own position is likely far more
>>> nuanced than that).
>> 
>> Hmm, do you want to have two (and then three, see below) separate manpages
>> that essentially describe the same thing, and refer to each other when
>> they talk about the precedence order?
> 
> No, I am just saying that if this isn't primarily meant to be
> about /etc/gitweb.conf (which is what I was told to use here on this
> very list) then we shouldn't name it after gitweb.conf,

We have to name it somehow.  For example ssh_config(5) is named after 
system-wide settings file, while it describes also user settings in
.ssh/config.  We would follow this example with gitweb.conf(5)

A bit closed, gitignore(5) and gitattributes(5) both are named after
in-tree file '.gitignore' and '.gitattributes', but describe also
private $GIT_DIR/info/exclude (not ignore!) and $GIT_DIR/info/attributes
respectively.


Anyway we can use symlinks or hardlinks (or just a plain copy) to have
this manpage under both gitweb.conf(5) and gitweb_config(5) or 
gitweb_config.perl(5).  There is precedent: many function manpages
are grouped together.  For example printf,  fprintf, sprintf, snprintf,
vprintf, vfprintf, vsprintf, vsnprintf all use single printf(3) manpage.

But that is better left for a separate commit, if we decide to do this.

> nor should we focus on gitweb.conf

Manpage describing gitweb.conf also describes gitweb_conf.perl.  The
difference is minuscule, so it is IMVHO better to cover both with one
manpage, and add a few paragraphs about precedence etc.  Isn't it?

> (the removal of the gitweb.conf we are then 
> effectively deprecating can be discussed later; I have already voiced my
> opinion on this strategy of ignoring /etc/gitweb.conf but still having
> it anyway and been summarily declared insane).

The problem is backward compatibility.  To not repeat myself, see my
thoughts on this issue later, at the end of this email.

> 
> The change he made isn't, to me anyway, one of precedence order but is
> one of focus and theme. Perhaps most people around here aren't trained
> to hew so closely to the stated purpose of a work as I am and therefore
> don't see the change he suggested as starkly. So be it. 
> I really don't like starting work on something for a project because I
> was told that (1) it was needed and, (2) it would be welcome only to
> find that neither statement was particularly true. I'd strongly prefer
> to have been told from the outset "Don't bother to document that, as
> you're the only one using it that way," and, "Document this instead, as
> just because you're not using it doesn't mean that we don't think
> everyone else should be."

Actually it both was needed and welcome.  Thanks again for your work.

The fact that your hard and welcome work on gitweb.conf manpage with
small additions (which you don't need to put yourself; we can do it
instead) is more general manpage about gitweb config files is a happy
thing.
 

>> I vaguely recall that there was an effort to document /etc/gitweb.conf as
>> a mere "fallback default", not a "system-wide configuration file", which
>> is what it is, and also to introduce a true "system-wide configuration" as
>> a separate file, so that the system-wide one will be read, and then either
>> per-instance gitweb_config.perl or the fallback default /etc/gitweb.conf
>> will update it. What happened to that effort?

If the "version C" effort, namely introducing gitweb-common.conf in

  [PATCH/RFC 2/2 (version C)] gitweb: Introduce common system-wide settings for convenience
  Message-Id: <201105261658.20140.jnareb@gmail.com>
  http://thread.gmane.org/gmane.comp.version-control.git/174424/focus=174517

in thread titled

  [PATCH 0/2] gitweb: Improve handling of configuration files

is not in cooking stage, but fell into cracks, I can always resend said
patch.
 
> You shot it down, that's what. Or more correctly you shot down the use
> of /etc/gitweb.conf as a system-wide source of default settings instead
> proposing that it be used as a fallback (?) and that
> an /etc/gitweb-defaults.conf (or something like that) be used as a
> per-item default (or at least that's what I got out of what was said).
> I'm not sure what to think of that, but I haven't had the chance to test
> that patch-set in any case, much less incorporate it into the
> documentation. All of that would come after I'm no longer confused as to
> what the intended end-result would be.
>> 
>> In any case, with the current design, /etc/gitweb.conf is _not_ the
>> system-wide configuration file but it is a fallback default for instances
>> that do not have per-instance configuration, so the quoted part would need
>> rewording anyway, I think.
> 
> And THAT is the problem. If it isn't a system-wide configuration file
> then let's stop putting it in /etc, deprecate it, and get it over with.
> I didn't even know that to be the case when I started writing this, I
> was just trying to make more readily available the advice I'd been given
> on this list. Only after getting started did I learn that gitweb treats
> a file in /etc like nothing else I normally use (aside from
> adduser/useradd's use of /etc/skel as a directory template).

What about /etc/bashrc ?  Isn't is treated as fallback, and you have to
source it explicitly?

Anyway, because of backward compatibility (bug-compatible) we have to
name new system-wide config file /etc/gitweb-common.conf, fallback config
be at /etc/gitweb.conf, and per-instance config file gitweb_config.perl
Note that these are only defaults; they can be overridden at build time
(though you cannot change names of respective environmental variables).

Perhaps at some flag day (1.8.0 is probably to close) we can change it so
that system-wide config file is /etc/gitweb.conf, per-instance config file
(overriding system-wide settings) is gitweb_config.perl, and fallback
system-installed config file used if per-instance config file does not
exists is /etc/gitweb_config.perl

But still the manpage should IMVHO be gitweb.conf(5)!

-- 
Jakub Narebski
Poland

Re: [RFC/PATCHv3 4/5] gitweb: Starting work on a man page for /etc/gitweb.conf (WIP)

[Drew Northup]

On Tue, 2011-06-07 at 21:36 +0200, Jakub Narebski wrote:
> Anyway, because of backward compatibility (bug-compatible) we have to
> name new system-wide config file /etc/gitweb-common.conf, fallback config
> be at /etc/gitweb.conf, and per-instance config file gitweb_config.perl
> Note that these are only defaults; they can be overridden at build time
> (though you cannot change names of respective environmental variables).
> 
> Perhaps at some flag day (1.8.0 is probably to close) we can change it so
> that system-wide config file is /etc/gitweb.conf, per-instance config file
> (overriding system-wide settings) is gitweb_config.perl, and fallback
> system-installed config file used if per-instance config file does not
> exists is /etc/gitweb_config.perl

I would not have asked that such a large change happen any sooner than
that.

-- 
-Drew Northup
________________________________________________
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59

Re: [PATCHv3 2/5] gitweb: Describe CSSMIN and JSMIN in gitweb/INSTALL

[Jakub Narebski]

On Mon, 6 June 2011, Jonathan Nieder wrote:

Thank you very much for your review and comments.

> Jakub Narebski wrote:
> 
> > The build-time configuration variables JSMIN and CSSMIN were mentioned
> > only in Makefile; add their description to gitweb/INSTALL.
> >
> > This required moving description of GITWEB_JS up, near GITWEB_CSS and
> > just introduced CSMIN and JSMIN.
> 
> Why does this require that?  Ah, to make the analogy with GITWEB_CSS
> clear and because the JSMIN description refers to it.

Yes, moving description of GITWEB_JS was required because I wanted to
cover both of CSSMIN and JSMIN with one entry, which entry of course
refers to both GITWEB_CSS and GITWEB_JS.

> > --- a/gitweb/INSTALL
> > +++ b/gitweb/INSTALL
> > @@ -147,6 +147,19 @@ You can specify the following configuration variables when building GIT:
> [...]
> > + * CSSMIN, JSMIN
> > +   Invocation of a CSS minifier or a JavaScript minifier, respectively,
> > +   working as a filter (source on standard input, minified result on
> > +   standard output).  If set, it is used to generate a minified version of
> > +   'static/gitweb.css' or 'static/gitweb.js', respectively.  *Note* that
> > +   minified files would have *.min.css and *.min.js extension, which is
> > +   important if you also set GITWEB_CSS and/or GITWEB_JS.  [No default]
> 
> When I first read this, I thought it meant these command lines were
> going to be cooked into the gitweb script and invoked at run time.
> Maybe (sorry for the rough text):
> 
> * CSSMIN, JSMIN
>   Command for a CSS minifier or a Javascript minifier, working as a
>   filter [...]
>   These are used if defined to generate smaller, non human-readable
>   versions of 'gitweb/gitweb.css' and 'static/gitweb.js' at
>   'static/gitweb.min.css' and 'static/gitweb.min.js'.  Only the minified
>   versions are installed, which is important if you also set GITWEB_CSS
>   or GITWEB_JS.  [No default]
> 
> Aside from that, looks good.  Thanks.

Thanks.  I'll incorporate those comments in next round... or as a separate
improvement (it is not that bad, I think, to not allow it to be fixed
"in tree").

Anyway the description could use some improvements.  We need to cover the
following issues:

1. CSSMIN and JSMIN are invoked during building gitweb.

2. CSSMIN and JSMIN are interpreted as shell commands, so
   * if you refer to script by full path, you need to quote spaces
     yourself, e.g. 

     JSMIN="'c:/Program Files/JSMin/jsmin.exe'"

   * you can provide options, so you can e.g. use

     JSMIN="perl -MJavaScript::Minifier=minify -we 'minify(input => *STDIN, output => *STDOUT);'"

3. CSSMIN and JSMIN must accept source on standard input, and print
   minified version to standard output, i.e. they are invoked as

     $(CSSMIN) <$< >$@

4. Minified files will be named static/gitweb.min.css and
   static/gitweb.min.js, respectively

5. If you do not set GITWEB_CSS and GITWEB_JS, but use CSS and/or JSMIN,
   they would be set to appropriate values automatically

6. The "install" target in gitweb Makefile, and "install-gitweb" target
   in main Makefile, would install minified versions (if any).

7. If you set both CSSMIN and GITWEB_CSS, you have to adjust GITWEB_CSS
   by yourself.  Same for JSMIN and GITWEB_JS.

Help with wording those would be much appreciated, in more compact form.
Thanks in advance.

-- 
Jakub Narebski
Poland (not native English speaker)

Re: [RFC/PATCHv3 4/5] gitweb: Starting work on a man page for /etc/gitweb.conf (WIP)

[Jakub Narebski]

On Tue, 7 Jun 2011, Jonathan Nieder wrote:

Thank you for your review and comments, and for participating
in discussion!

> Jakub Narebski wrote:
> 
> > Some effort has
> > been made to de-duplicate any of this.
> 
> :)

Please excuse me, but I have noticed that I have "No effort has been made"
just before sending patches.  So this is unfortunate result of fixing it
"on the go".
 
> > * Much simpler "doc" target in gitweb/Makefile.  Now instead of
> >   duplicating internal knowledge how Documentation/Makefile works we
> >   simply delegate task to "gitweb-doc" target (a la "full-svn-test"
> >   in t/Makefile) in Documentation/Makefile.
> 
> Seems sensible as long as the main Makefile never learns
> 
> 	gitweb-doc:
> 		$(MAKE) -C gitweb doc
> 
> The toplevel Makefile could do "$(MAKE) -C Documentation gitweb-doc"
> and still avoid the usual pitfalls of recursive make stepping on its
> own toes.

What do you mean about recursive make troubles here?  There is no loop:
Makefile -> gitweb/Makefile -> Documentation/Makefile.

Do you means something like the following

  $ make -j 2 doc gitweb-doc
 
if main Makefile's "gitweb-doc" would delegate via gitweb/Makefile
instead of straight to Documentation/Makefile?

> Longer term, I would like to try making gitweb/Makefile include a
> build-helpers/Makefile.doc library and moving this documentation back
> to the gitweb/ directory, which would make the gitweb directory
> self-contained again (except for the build-helpers/Makefile.doc file).
> Not sure what to do about that "except for..." bit.  I don't think my
> half-baked long-term ideas should be allowed to slow this down. ;-)

First, this would move dependency from Documentation/Makefile to
build-helpers/Makefile-doc.inc
 
Second such helper would need to solve the ussue that currently in
Documentation/Makefile one must specify explicitely to which man section
given manpage belongs.  You would have to come with some efficient way
to get that information from AsciiDoc source and/or file position in
hierarchy.

Third, we would still depend on t/Makefile for tests...


BTW. does anyone know any converter from AsciiDoc to POD, or POD
formatter formatting to AsciiDoc?

> > --- a/Documentation/Makefile
> > +++ b/Documentation/Makefile
[...]
> > @@ -170,6 +170,9 @@ info: git.info gitman.info
> >  
> >  pdf: user-manual.pdf
> >  
> > +GITWEB_DOC = $(filter gitweb.%,$(DOC_HTML) $(DOC_MAN1) $(DOC_MAN5) $(DOC_MAN7))
> > +gitweb-doc: $(GITWEB_DOC)
> 
> Nice.

I try... :-)

> > @@ -334,4 +337,4 @@ quick-install-man:
> >  quick-install-html:
> >  	'$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(HTML_REF) $(DESTDIR)$(htmldir)
> >  
> > -.PHONY: FORCE
> > +.PHONY: FORCE gitweb-doc
> 
> Is there any reason other phony targets (like "install" and "pdf")
> aren't listed here?

I don't know; they weren't there.
 
> > --- /dev/null
> > +++ b/Documentation/gitweb.conf.txt
> > @@ -0,0 +1,716 @@
> > +gitweb.conf(5)
> > +==============
> > +
> > +NAME
> > +----
> > +gitweb.conf - Gitweb configuration file
> 
> I suppose the novice can look to the DESCRIPTION or SEE ALSO section
> to learn what gitweb is.

Well, we could write "Configuration file for git web interface"... but
there are [much] more web interfaces for git than gitweb.
 
> > +SYNOPSIS
> > +--------
> > +[verse]
> > +'/etc/gitweb.conf'
> > +'$GITWEBDIR/gitweb_config.perl'
> 
> Micronit: a single line like
> 
> 	SYNOPSIS
> 	--------
> 	$GITWEBDIR/gitweb_config.perl, /etc/gitweb.conf
> 
> might fit better with the pattern established by gitattributes(5) and
> its kin.

I'm sorry, that is my fault and not Drew's.

While Drew was styling gitweb.conf manpage after resolv.conf(5), I took
ssh_config(5) as an example.  But of course consistency within section 5
git manpages are more important.

Will fix.

> > +DESCRIPTION
> > +-----------

[...]
> > +The configuration file is used to override the default settings that
> > +were built into gitweb at the time 'gitweb.cgi' script was generated.
> > +
> > +While one could just alter the configuration settings in the gitweb
> > +CGI itself, those changes would be lost upon upgrade.
> 
> What if I upgrade using RCS "merge"? :)  So maybe:
> 
> 	s/one could just alter/one can alter/
> 	s/would be lost/could be lost/
> 
> to clarify that (1) editing the CGI script is allowed and fine but (2)
> it might be a pain to keep those changes.

I can agree with 2nd change, but not the first.  Besides who use rcsmerge
for upgrading (and not something that looks like config file)?

> > +[...] Configuration
> > +settings might also be placed into a file in the same directory as the
> > +CGI script with the default name 'gitweb_config.perl' -- allowing
> > +one to have multiple gitweb instances with different configurations by
> > +the use of symlinks.
> 
> Might also in addition to what?  Continuing the thought from before:
> 
> 	So gitweb allows settings to be placed in a separate file named
> 	'gitweb_config.perl' in the same directory as the CGI script.
> 	This also allows one to set up multiple gitweb instances with
> 	different configurations by using symlinks to a common gitweb.cgi
> 	script.

I think your 2nd paragraph would better be put in notes, or in other
separate (sub)section.
 
> > +DISCUSSION
> > +----------
> 
> First, as a general thought, by the time I get this far I start
> thinking, "so where's the list of possible settings?".  But there are
> certainly some more basic pieces of information to cover before then
> (like the global configuration file), so I think this part is in the
> right place.  It just could benefit from being a little shorter.

Right.

> > +The location of system-wide gitweb configuration file is defined at compile
> > +time using the configuration value `GITWEB_CONFIG_SYSTEM` and defaults to
> > +'/etc/gitweb.conf'.  The name of the per-instance configuration file is
> > +defined in gitweb by `GITWEB_CONFIG`, and defaults to 'gitweb_config.perl'
> > +(relative path means located in the same directory gitweb is installed).
> 
> Maybe:
> 
> 	In addition to the per-instance configuration file, there can
> 	be a system-wide configuration file to act as a fallback when
> 	the per-instance configuration file does not exist.
> 
> 	The system-wide configuration file is named /etc/gitweb.conf
> 	by default.  Filenames for the system-wide and per-instance
> 	configuration variables can be overridden at compile time and
> 	run time; see the FILES section for details.

O.K.  Looks better.
 
> [...]

> > +*NOTE:* If per-instance configuration file ('gitweb_config.perl') exists,
> > +then system-wide configuration file ('/etc/gitweb.conf') is _not used at
> > +all_!!!
> 
> Over the top. :)  I think the best way to document this is to contrast
> it with /etc/gitweb-common.conf once the latter exists.

Well, perhaps it is to be reworded, and use ALL CAPS somewhere, but for
the time being I'd rather have this information there.

Though the point might become moot, if (as you noticed) the patch
introducing /etc/gitweb-common.conf is merged in before this series.
Then this part would have to be reworded.
 
> > +The syntax of the configuration files is that of Perl, as these files are
> > +indeed handled as fragments of Perl code (the language that gitweb itself is
> > +written in). Variables may be set using "`our $variable = value`"; text from
> > +"#" character until the end of a line is ignored. See the *perlsyn*(1) man
> > +page for more information.
> 
> Duplicates DESCRIPTION.

Thanks for notocing this.  I'd try to come up with shorter explanation in
"Description", and longer and more detailed here.
 
> > +
> > +Actually using `our` qualifier in `our $variable = <value>;` is a safety
> > +check: if newer gitweb does no longer use given variable, by using `our` we
> > +won't get syntax errors.
> 
> Maybe this could move to a later NOTES section?

Good idea.

> > +
> > +The default configuration with no configuration file at all may work
> > +perfectly well for some installations.  Still, a configuration file is
> > +useful for customizing or tweaking the behavior of gitweb in many ways, and
> > +some optional features will not be present unless explicitly enabled using
> > +the configurable `%features` variable (see also "Configuring gitweb
> > +features" section below).
> 
> I suppose this is based on the text
> 
> 	The most notable thing that is not configurable at compile time are the
> 	optional features, stored in the '%features' variable.
> 
> I'd suggest removing the paragraph.

O.K., as this is in section that needs to be kept short, perhaps
simplification is in order.  Still, I'd like to mention `%feature`
variable, and refer to later section describing it (which I forgot
to add in this version).
 
> > +CONFIGURATION VARIABLES
> > +-----------------------
> > +Some of configuration variables have their default values (embedded in CGI
> > +file) set during building gitweb -- if that is the case, it is put in their
> > +description.  See gitweb's 'INSTALL' file for instructions on building and
> > +installing gitweb.
> 
> Reasonable.  Nit: s/put/mentioned/

"Mentioned" is certainly better word here.
 
> > +
> > +Location of repositories
> > +~~~~~~~~~~~~~~~~~~~~~~~~
> > +Configuration variables described below control finding git repositories by
> > +gitweb, and control display and access to repositories.
> 
> 	The configuration variables described below determine where gitweb looks
> 	for repositories and which will be displayed.
> 
> (missing "The", elaboring on what it means to control repository search.)

Thanks.

I am not a native English speaker, and I seem to be missing "the" from
time to time.
 
> > +$project_maxdepth::
> > +	Filesystem traversing depth limit for recursively scanning for git
> > +	repositories, used if `$projects_list` (below) is unset.  The default
> > +	value of this variable is determined by build-time configuration
> > +	variable `GITWEB_PROJECT_MAXDEPTH`, which defaults to 2007.
> 
> gitweb/INSTALL says:
> 
> 	The filesystem traversing limit for getting the project list; the number
> 	is taken as depth relative to the projectroot.  It is used when
> 	GITWEB_LIST is a directory (or is not set; then project root is used).
> 	This is meant to speed up project listing on large work trees by limiting
> 	search depth.  [Default: 2007]
> 
> I'm still not clear on what it actually means.  Is it used when
> $projects_list points to a directory or not?  What if $projects_list
> points to a file with lines that name directories?  What happens
> when listing forks of a repository?

All right, I'd try to come up with clearer description.

The `$project_maxdepth` is used _only_ when recursively searching for git
repositories, and it always counts depth relative to $projectroot (since
the fix to "forks" that made it into git.git repository).
 
BTW. I don't know why 2007... ;-P

> > +
> > +$projects_list::
> > +	Plain text file listing projects or name of directory
> > +	to be scanned for projects.
> > +
> > +	Project list files should list one project per line, with each line
> > +	having the following format
> > +-----------------------------------------------------------------------------
> > +<URI-encoded filesystem path to repository> SP <URI-encoded repository owner>
> > +-----------------------------------------------------------------------------
> > +
> > +The default value of this variable is determined by the `GITWEB_LIST`
> > +makefile variable at installation time.  If this variable is empty, gitweb
> > +will fall back to scanning the `$projectroot` directory for repositories.
> 
> This gets formatted with the second and later paragraphs being
> unindented; presumably it needs a "+", like so:
> 
> 		... paragraph 1 ...
> 	+
> 	--
> 	... remaining paragraphs ...
> 	--

It looked all right when I was looking at asciidoc 7.1.3 formatted manpage.
I'd have to check how other manpages solve the problem of literal blocks
inside description list, and multi-paragraph description lists, and follow
their examples.

> Can't this point to a directory, too?

*IMPORTANT ISSUE*

I am trying to _evade_ this issue, because of what I see is MISDESIGN
of gitweb.  

When $projects_list is a file, everything is clear -- pathnames
in this file are relative to $projectroot.

But when $projects_list is a directory, it will be recursively scanned for
git repositories, and gitweb would show in projects list page their
pathnames retalive to $projects_list.  But when viewing single repository
it would compose full path out of _$projectroot_ and project "name".

Therefore what makes sense is either $projects_list set to file listing
repositories, or $projects_list unset; then gitweb would use $projectroot
for $projects_list, and scan $projectsroot.

Perhaps there are some rare changes where having $projects_list be set to
a directory different from $projectroot has sense, but they are very, very
rare (directory populated with symlinks to repositories comes to mind).

So that is why I am always taking here about either $projects_list set to
path of plain text file listing repositories, or $projects_list unset.
Though perhaps I should explain gitweb behavior in some "notes"
(sub)section.
 
> > +
> > +$export_ok::
> > +	Show repository only if this file exists (in repository).  Only
> > +	effective if this variable evaluates to true.  Can be set during
> > +	building gitweb via `GITWEB_EXPORT_OK`.  [No default / Not set]
> 
> Am I supposed to show a repository?  Ah, no, this is about what gitweb
> does.  Maybe
> 
> 	Filename to look for in repositories to determine whether to
> 	show them.  If this variable evaluates to true, gitweb will
> 	only show repositories that contain a magic file with that
> 	name; otherwise, which repositories gitweb shows is controlled
> 	by the $strict_export option.  Can be set when building gitweb
> 	using the `GITWEB_EXPORT_OK` variable.  [No default]

That is better way of stating this, thanks.
 
Perhaps s/evaluates to true/is set/ after fixing gitweb to use

  if (defined $export_ok) {

instead of

  if ($export_ok) {

> Might be simpler to put the documentation of $strict_export first.

I'd consider this.

> gitweb/INSTALL says:
> 
> 	gitweb
> 	shows repositories only if this file exists in its object database
> 	(if directory has the magic file named $export_ok)
> 
> but I assume what was meant is the git dir, not .git/objects.

Yes, I meant $GIT_DIR here.  I need to somehow explain that this file
is not searched for in projects working area.  I'd take a look on how
git-daemon(1) documents this...

> Incidentally, wouldn't it be more intuitive to treat all values of
> $export_ok as true (i.e., check "if (defined($export_ok))" instead of
> "if ($export_ok)") so the user doesn't need to know what values perl
> considers to be true?

You are right.

Though this would need a separate commit, for easier review.
 

> [...]
> > +$strict_export::
> > +	Only allow viewing of repositories also shown on the overview page.
> > +	This for example makes `$gitweb_export_ok` file decide if repository is
> > +	available and not only if it is shown.  If `$gitweb_list` points to
> > +	file with list of project, only those repositories listed would be
> > +	available for gitweb.  Can be set during building gitweb via
> > +	`GITWEB_STRICT_EXPORT`.  [No default / Not set]
> 
> I think I'd put this before $export_ok (because simpler) and steal
> text from INSTALL.
> 
> 	By default, even if a project is not visible on the projects list
> 	page, you can view it by hand-crafting a gitweb URL.  Set the
> 	$strict_export variable to true if you want to only allow
> 	repositories shown on the overview page to be viewed.  Can be
> 	set during ...

All right.
 
> > +Finding files
> > +~~~~~~~~~~~~~
> > +Those configuration variables tell gitweb where to find files.  Values of
> > +those variables are paths on filesystem.  Of those only `$GIT` is required
> > +to be (correctly) set for gitweb to be able to work; all the rest are
> > +required only for extra configuration or extra features.
> 
> Perhaps:
> 
> 	System paths
> 	~~~~~~~~~~~~
> 	These configuration variables tell gitweb where to find commands and 
> 	system files.  The values of these variables are commands or
> 	paths on the filesystem.  Of these, only ...
> 
> (s/those/these/; add some wiggle room since $GIT = "git" is allowed;
> change the title to contrast with the repository location variables;
> add a comma.)

Thanks.  I couldn't come with a good name for this section, and a good
introductory paragraph.
 
> > +
> > +$GIT::
> > +	Core git executable to use.  By default set to `$GIT_BINDIR/git`, which
> > +	in turn is by default set to `$(bindir)/git`.  If you use git from binary
> > +	package, set this to "/usr/bin/git".  This can just be "git" if your
> > +	webserver has a sensible PATH.  If you have multiple git versions installed
> > +	it can be used to choose which one to use.
> 
> A setting like $GIT = "git --exec-path=elsewhere" would not work
> because the entire string is used as the first argument to execvp.
> Not sure how to say it: maybe just
> 
> 	Command name to use when running git commands.  By default
> 	this is set to ...
> 
> ("command name" being a phrase I made up on the spot for "path or
> bare command name, suitable for passing to execvp".)

I thought that "executable" impled name of a _file_, isn't it?
But I'd consider your wording.  Thanks.

> I think a better default would be "git", so if a newer git gets
> installed in /usr/local/bin then gitweb would notice automatically.

I'd rather not we pick first "git" that happens to be in web server PATH.
Though nowadays it should be much more rare to encounter "git" binary
that is not our git (there was section named "other programs named git"
somewhere, but I couldn't find it).

> > +$mimetypes_file::
> > +	File to use for (filename extension based) guessing of MIME types before
> > +	trying '/etc/mime.types'.  Path, if relative, is taken currently as
> > +	relative to the current git repository.  [Unset by default]
> 
> What makes $mimetypes_file fit in this section but not $export_ok?  (I
> have no good answer.  Maybe a separate section for MIME type guessing
> would be more discoverable?)

Because it is name of file to be found on filesystem, and not inside
git repository.  Perhaps I should have made it more clear that this
section is not about files inside git repository that control gitweb
look and behavior.

But perhaps separate section about MIME type handling, containing a three
variables (IIRC) would be a better solution.
 
> > +Links and their targets
> > +~~~~~~~~~~~~~~~~~~~~~~~
> > +Configuration variables described below configure some of gitweb links:
> > +their target and their look (text or image), and where to find page
> > +prerequisites (stylesheet, favicon, images, scripts).  Usually they are left
> > +at their default values, with the possible exception of `@stylesheets`
> > +variable.
> 
> Does "Usually they are left at" mean "Usually there is no reason to change
> them from"?  Aside from that, makes sense.

Yes, it does.  Will fix.
 
> > +
> > +@stylesheets::
> > +	List of URIs of stylesheets (relative to base URI of a page). You
> > +	might specify more than one stylesheet, for example use gitweb.css
> > +	as base, with site specific modifications in separate stylesheet
> > +	to make it easier to upgrade gitweb. You can add a `site` stylesheet
> > +	for example by putting
> > +----------------------------------------------------------------------------
> > +push @stylesheets, "gitweb-site.css";
> > +----------------------------------------------------------------------------
> > +in the gitweb config file.  Those values that are relative paths, are
> > +relative to base URI of gitweb.
> > +
> > +This list should contain URI of gitweb's stylesheet.  The URI of gitweb
> > +stylesheet is set during build time via `GITWEB_CSS` variable.  It's default
> > +value is 'static/gitweb.css' (or 'static/gitweb.min.css' if the `CSSMIN`
> > +variable is defined, i.e. if CSS minifier is used during build.
> > +
> > +*Note*: there is also legacy `$stylesheet` configuration variable, which was
> > +used by older gitweb.
> 
> s/gitweb$/gitweb's/; s/It's/Its/.  Missing closing paren, I think.

O.K.
 
> s/legacy/the legacy/.  How does this interact with the legacy setting (e.g.,
> if I am new on my job as gitweb administrator and encounter such a line,
> what does it mean and what would I want to change it to)?
 
Badly.

If $stylesheet variable is defined, it is used as gitweb's stylesheet, and
@stylesheets variable is ignored.

If you as administrator encounter old gitweb config file with such a line,
you should examine said file to check what was added to stock gitweb CSS,
and put additions / changes in a separate file, which would be then
separate entry in @stylesheets besides stock gitweb CSS

  push @stylesheets, "gitweb-changes.css";

This way upgrading gitweb would upgrade stock part of CSS file.


I think on 1.8.0 boundary, or some other such, we could get rid of legacy
$stylesheet variable, perhaps leaving comment here about how to update
config file.

> > +
> > +$logo::
> > +	Points to the location where you put 'git-logo.png' on your web
> > +	server, or to be more generic URI of logo, 72x27 size).  This image
> > +	is displayed in top right corner of each gitweb page, and used as
> > +	logo for Atom feed.  Relative to base URI of gitweb (as a path).
> > +	Can be adjusted during building gitweb using `GITWEB_LOGO` variable
> > ++
> > +	[Default: 'static/git-logo.png']
> 
> Re "as a path": can this be a URI pointing to another server if I want
> it to?

Yes it can.  This way you can serve static content (images, CSS, scripts)
from some CDN (Content Delivery Network) on different host for a bit better
performance.

Though you would have to install and upgrade such files yourself.
 

Note: URL can be 'path/to/file', or '/path/to/file', or even 
'http://server/path/to/file'.  Only last is absolute _URL_, IIRC.

> [...]
> > +$home_link::
> > +	Target of the home link on top of all pages (the first part of view
> > +	"breadcrumbs").  By default set to absolute URI of a page ($my_uri).
> 
> s/By default set to absolute URI of a page/The default is the absolute
> URI for the gitweb script/
> 
> Stopping here.  Will resume later but since having something is better
> than nothing, I am tempted to say this should be applied e.g. to
> "next" so people can start using it right away and finding/fixing
> documentation bugs.

Thanks.

-- 
Jakub Narebski
Poland

Re: [RFC/PATCHv3 4/5] gitweb: Starting work on a man page for /etc/gitweb.conf (WIP)

[Jakub Narebski]

Jonathan Nieder wrote:
> Jonathan Nieder wrote:
>> Jakub Narebski wrote:
> 
>>> +$GIT::
>>> +	Core git executable to use.  By default set to `$GIT_BINDIR/git`, which
> [...]
>> I think a better default would be "git", so if a newer git gets
>> installed in /usr/local/bin then gitweb would notice automatically.
> 
> Wait, that's quite wrong.  What I was forgetting about is the case
> where the webmaster does not control the web hosting but just has a
> place to drop CGI scripts under ~/public_html/cgi-bin.  In such a case
> it would be very convenient that "make install-gitweb" just does the
> right thing (including using a private copy of git).

Right, "git" might not be in PATH of a web server (which can have
reduced PATH for security reasons anyway).

-- 
Jakub Narebski
Poland

Re: [RFC/PATCHv3 4/5] gitweb: Starting work on a man page for /etc/gitweb.conf (WIP)

[Jakub Narebski]

On Tue, 7 Jun 2011, Drew Northup wrote:
> On Mon, 2011-06-06 at 17:12 -0500, Jonathan Nieder wrote:
> > Jakub Narebski wrote:
> 
> 
> > > +SYNOPSIS
> > > +--------
> > > +[verse]
> > > +'/etc/gitweb.conf'
> > > +'$GITWEBDIR/gitweb_config.perl'
> > 
> > Micronit: a single line like
> > 
> > 	SYNOPSIS
> > 	--------
> > 	$GITWEBDIR/gitweb_config.perl, /etc/gitweb.conf
> > 
> > might fit better with the pattern established by gitattributes(5) and
> > its kin.
> 
> I thought that's how I had originally put it.

I am very sorry.  The fault is all mine, not Drew.  This is my (wrong)
change.

When working on gitweb.txt manpage, and actually moving contents from
gitweb's README and INSTALL, I have also changed this patch to also
remove duplicated contents.  And I couldn't resist the temptation
to bring further changes... though I should have probably left those
for a separate commit, if still claiming this as of Drew's authorship.


[...]

> > Stopping here.  Will resume later but since having something is better
> > than nothing, I am tempted to say this should be applied e.g. to
> > "next" so people can start using it right away and finding/fixing
> > documentation bugs.
> 
> And so am I [stopping], I suppose. I have had work to do for the past
> few weeks that really caused me to NEED my weekends for things other
> than writing code and flossing documentation. Unless I am needed for
> something I'm going to just let this live or die on it's own for now, as
> I cannot keep up with this pace of patching right now. (That was in
> large part the whole point of my flagging this as WIP.)

Should I keep working on it then?

-- 
Jakub Narebski
Poland