[RFC/PATCHv2 0/2] Starting work on man pages for gitweb and gitweb.conf (WIP)

[RFC/PATCHv2 0/2] Starting work on man pages for gitweb and gitweb.conf (WIP)

[Jakub Narebski]

This is very much work in progress.  

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.

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


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

The major part that is left (besides extending both manpages with new
information) is actually de-duplicate contents, i.e. delete those
parts of gitweb/README and gitweb/INSTALL that were copied to those
new manpages.

Both of those are also available in 'gitweb/doc' branch in one of my
repositories:

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


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

Jakub Narebski (1):
  gitweb: Starting work on a man page for gitweb (WIP)

Diffstat:
~~~~~~~~~
 Documentation/Makefile        |    4 +-
 Documentation/gitweb.conf.txt |  436 +++++++++++++++++++++++++++++++++++++++++
 Documentation/gitweb.txt      |  334 +++++++++++++++++++++++++++++++
 git.spec.in                   |    3 +
 gitweb/Makefile               |   14 ++
 5 files changed, 789 insertions(+), 2 deletions(-)
 create mode 100644 Documentation/gitweb.conf.txt
 create mode 100644 Documentation/gitweb.txt

-- 
1.7.5

[RFC/PATCHv2 1/2] 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. No effort has yet
been made to de-duplicate any of this.

TODO:
  * Clean up README and INSTALL files
  * Move most of gitweb's README and INSTALL into gitweb.txt and
    gitweb.conf.txt, so that gitweb documentation can be easily viewed.
  * 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>
---
 Documentation/Makefile        |    2 +-
 Documentation/gitweb.conf.txt |  436 +++++++++++++++++++++++++++++++++++++++++
 git.spec.in                   |    3 +
 gitweb/Makefile               |   13 ++
 4 files changed, 453 insertions(+), 1 deletions(-)
 create mode 100644 Documentation/gitweb.conf.txt

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 36989b7..74ed959 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
diff --git a/Documentation/gitweb.conf.txt b/Documentation/gitweb.conf.txt
new file mode 100644
index 0000000..34f65fa
--- /dev/null
+++ b/Documentation/gitweb.conf.txt
@@ -0,0 +1,436 @@
+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 = 'My Gitweb';  # or 'localhost'
+
+
+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).
+
+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.
+
+
+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 gitwen.
+
+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.
+
+$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 
+----------------------------------------------------------------------------
+our $export_ok = "git-daemon-export-ok";
+----------------------------------------------------------------------------
+instead).
+
+$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.
++
+	[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.
+
+$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]
+
+$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.
+
+
+EXAMPLES
+--------
+
+To enable blame, pickaxe search, and snapshot support, 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:git-instaweb[1]
+
+'gitweb/README', 'gitweb/INSTALL'
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/git.spec.in b/git.spec.in
index 91c8462..06b27eb 100644
--- a/git.spec.in
+++ b/git.spec.in
@@ -200,6 +200,9 @@ rm -rf $RPM_BUILD_ROOT
 %files -n gitweb
 %defattr(-,root,root)
 %{_datadir}/gitweb
+%{!?_without_docs: %{_mandir}/man1/*gitweb*.1*}
+%{!?_without_docs: %{_mandir}/man5/*gitweb*.5*}
+%{!?_without_docs: %doc Documentation/*gitweb*.html }
 
 %files -n perl-Git -f perl-files
 %defattr(-,root,root)
diff --git a/gitweb/Makefile b/gitweb/Makefile
index 0a6ac00..582e1b0 100644
--- a/gitweb/Makefile
+++ b/gitweb/Makefile
@@ -112,6 +112,14 @@ endif
 
 GITWEB_FILES += static/git-logo.png static/git-favicon.png
 
+GITWEB_MAN5_TXT = gitweb.conf.txt
+GITWEB_MAN_TXT = $(GITWEB_MAN1_TXT) $(GITWEB_MAN5_TXT) $(GITWEB_MAN7_TXT)
+GITWEB_MAN = $(patsubst %.txt,%.1,$(GITWEB_MAN1_TXT)) \
+             $(patsubst %.txt,%.5,$(GITWEB_MAN5_TXT)) \
+             $(patsubst %.txt,%.7,$(GITWEB_MAN7_TXT))
+GITWEB_HTML= $(patsubst %.txt,%.html,$(GITWEB_MAN_TXT))
+GITWEB_DOC = $(GITWEB_MAN) $(GITWEB_HTML)
+
 GITWEB_REPLACE = \
 	-e 's|++GIT_VERSION++|$(GIT_VERSION)|g' \
 	-e 's|++GIT_BINDIR++|$(bindir)|g' \
@@ -155,6 +163,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
-- 
1.7.5

[RFC/PATCHv2 2/2] 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.  No effort has
yet 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.

Current version is almost direct translation of SVN::Web manpage, and
is missing much of information that finally are to be moved from
gitweb/README to here.

Inspired-by: Drew Northup <drew.northup@maine.edu>
Signed-off-by: Jakub Narebski <jnareb@gmail.com>
---
 Documentation/Makefile        |    2 +-
 Documentation/gitweb.conf.txt |    2 +-
 Documentation/gitweb.txt      |  334 +++++++++++++++++++++++++++++++++++++++++
 gitweb/Makefile               |    1 +
 4 files changed, 337 insertions(+), 2 deletions(-)
 create mode 100644 Documentation/gitweb.txt

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 74ed959..bf7d7ef 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 34f65fa..4d773ab 100644
--- a/Documentation/gitweb.conf.txt
+++ b/Documentation/gitweb.conf.txt
@@ -427,7 +427,7 @@ gitweb_config.perl::
 
 SEE ALSO
 --------
-linkgit:git-instaweb[1]
+linkgit:gitweb[1], linkgit:git-instaweb[1]
 
 'gitweb/README', 'gitweb/INSTALL'
 
diff --git a/Documentation/gitweb.txt b/Documentation/gitweb.txt
new file mode 100644
index 0000000..3815ca4
--- /dev/null
+++ b/Documentation/gitweb.txt
@@ -0,0 +1,334 @@
+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.
+
+-----------------------------------------------------------------------
+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.  
+
+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 lines
+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.
+
+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 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.
+
+
+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.
+
+
+WEB SERVERS
+-----------
+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
+-------------------------
+
+...
+
+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/Makefile b/gitweb/Makefile
index 582e1b0..240c10a 100644
--- a/gitweb/Makefile
+++ b/gitweb/Makefile
@@ -112,6 +112,7 @@ endif
 
 GITWEB_FILES += static/git-logo.png static/git-favicon.png
 
+GITWEB_MAN1_TXT = gitweb.txt
 GITWEB_MAN5_TXT = gitweb.conf.txt
 GITWEB_MAN_TXT = $(GITWEB_MAN1_TXT) $(GITWEB_MAN5_TXT) $(GITWEB_MAN7_TXT)
 GITWEB_MAN = $(patsubst %.txt,%.1,$(GITWEB_MAN1_TXT)) \
-- 
1.7.5

Re: [RFC/PATCHv2 1/2] Starting work on a man page for /etc/gitweb.conf (WIP)

[Junio C Hamano]

Jakub Narebski <jnareb@gmail.com> writes:

> diff --git a/gitweb/Makefile b/gitweb/Makefile
> index 0a6ac00..582e1b0 100644
> --- a/gitweb/Makefile
> +++ b/gitweb/Makefile
> @@ -112,6 +112,14 @@ endif
>  
>  GITWEB_FILES += static/git-logo.png static/git-favicon.png
>  
> +GITWEB_MAN5_TXT = gitweb.conf.txt
> +GITWEB_MAN_TXT = $(GITWEB_MAN1_TXT) $(GITWEB_MAN5_TXT) $(GITWEB_MAN7_TXT)
> +GITWEB_MAN = $(patsubst %.txt,%.1,$(GITWEB_MAN1_TXT)) \
> +             $(patsubst %.txt,%.5,$(GITWEB_MAN5_TXT)) \
> +             $(patsubst %.txt,%.7,$(GITWEB_MAN7_TXT))
> +GITWEB_HTML= $(patsubst %.txt,%.html,$(GITWEB_MAN_TXT))
> +GITWEB_DOC = $(GITWEB_MAN) $(GITWEB_HTML)
> +
>  GITWEB_REPLACE = \
>  	-e 's|++GIT_VERSION++|$(GIT_VERSION)|g' \
>  	-e 's|++GIT_BINDIR++|$(bindir)|g' \
> @@ -155,6 +163,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

I am not sure if this target is needed or even desirable.

The only potential benefit this complexity and risk of these build
procedure knowledge diverge what is in ../Documentation is to let you say
"cd gitweb && make doc" and avoid building the rest of the documentation,
but I personally do not find it necessary at all.

Aren't you making a mistake similar to the one that let instaweb have
intimate and unnecessary knowledge of how to build gitweb, which you
recently cleaned up?

Re: [RFC/PATCHv2 1/2] Starting work on a man page for /etc/gitweb.conf (WIP)

[Jakub Narebski]

On Sun, 29 May 2011, Junio C Hamano wrote:
> Jakub Narebski <jnareb@gmail.com> writes:
> 
> > diff --git a/gitweb/Makefile b/gitweb/Makefile
> > index 0a6ac00..582e1b0 100644
> > --- a/gitweb/Makefile
> > +++ b/gitweb/Makefile
> > @@ -112,6 +112,14 @@ endif
> >  
> >  GITWEB_FILES += static/git-logo.png static/git-favicon.png
> >  
> > +GITWEB_MAN5_TXT = gitweb.conf.txt
> > +GITWEB_MAN_TXT = $(GITWEB_MAN1_TXT) $(GITWEB_MAN5_TXT) $(GITWEB_MAN7_TXT)
> > +GITWEB_MAN = $(patsubst %.txt,%.1,$(GITWEB_MAN1_TXT)) \
> > +             $(patsubst %.txt,%.5,$(GITWEB_MAN5_TXT)) \
> > +             $(patsubst %.txt,%.7,$(GITWEB_MAN7_TXT))
> > +GITWEB_HTML= $(patsubst %.txt,%.html,$(GITWEB_MAN_TXT))
> > +GITWEB_DOC = $(GITWEB_MAN) $(GITWEB_HTML)
> > +
> >  GITWEB_REPLACE = \
> >  	-e 's|++GIT_VERSION++|$(GIT_VERSION)|g' \
> >  	-e 's|++GIT_BINDIR++|$(bindir)|g' \
> > @@ -155,6 +163,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
> 
> I am not sure if this target is needed or even desirable.

Well, this is the target that it is nice to have.  The implementation
needs to be improved, as you noticed.

> The only potential benefit this complexity and risk of these build
> procedure knowledge diverge what is in ../Documentation is to let you say
> "cd gitweb && make doc" and avoid building the rest of the documentation,
> but I personally do not find it necessary at all.
> 
> Aren't you making a mistake similar to the one that let instaweb have
> intimate and unnecessary knowledge of how to build gitweb, which you
> recently cleaned up?

Thanks for sanity check!

Instead of duplicating Documentation/Makefile knowledge in gitweb/Makefile,
let's just proxy to Documentation/Makefile like for 'test' target:

  +doc:
  +	$(MAKE) -C ../Documentation gitweb
  +

In Documentation/Makefile the new 'gitweb' target could look just like
this:

  +GITWEB_DOC = $(filter gitweb.%,$(DOC_HTML) $(DOC_MAN1) $(DOC_MAN5) $(DOC_MAN7)) 
  +gitweb: $(GITWEB_DOC)

And it would be much shorter, too.

-- 
Jakub Narebski
Poland