{"thread":{"id":"28418","subject":"[PATCH/RFCv4 0/4] Moving gitweb documentation to manpages","startedAt":"2011-09-18T13:34:40Z","lastAt":"2011-09-22T13:41:48Z","messageCount":12,"participants":["Jakub Narebski","Jonathan Nieder"],"isPatch":true,"patchVersion":1,"patchTotal":4},"messages":[{"id":"175714","messageId":"1316352884-26193-1-git-send-email-jnareb@gmail.com","threadId":"28418","inReplyTo":null,"subject":"[PATCH/RFCv4 0/4] Moving gitweb documentation to manpages","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2011-09-18T13:34:40Z","receivedAt":"2011-09-18T13:34:40Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"The original patch adding manpage for /etc/gitweb.conf was sent by\nDrew Northup; I have added manpage for gitweb itself, inspired by his\npatch.  Unfortunately Drew doesn't currently have time to work on this\npatch (patch series), so that is why it is me resending this series.\n\nIt is closer to final version, but still is a bit work in progres.\nThe main improvement is that documentation now renders correctly as\nHTML.\n\nNote that we should probably add gitweb(1) and gitweb.conf(5) manpages\nto the list in git(1) manpage.\n\n\nTable of contents:\n~~~~~~~~~~~~~~~~~~\n1. The changes to Documentation/Makefile adding gitweb-doc target and\nto gitweb/Makefile adding doc target are now upfront as a separate\npatch, compared to previous version of this series:\n\n  \"[RFC/PATCHv3 0/5] Improving gitweb documentation, creating manpages\"\n  http://thread.gmane.org/gmane.comp.version-control.git/175140\n\nThis is mainly so that description of ideas, which is common for both\ngitweb.conf.txt and gitweb.txt, is in a separate upfront commit\nmessage.\n\n\n2. The man page for /etc/gitweb.conf is modified, extended and\nimproved version of original patch by Drew Northup from\n\n  \"[PATCH/WIP] Starting work on a man page for /etc/gitweb.conf\"\n  http://thread.gmane.org/gmane.comp.version-control.git/173422\n\nDrew version was mostly pulled directly from the README and INSTALL\nfiles of gitweb.  I have tried to incorporate comments in mentioned\nthread, and to group config variables by category.  This version\nis also checked that it renders correctly as HTML and as manpage,\ncompared to version send earlier in\n\n  \"[RFC/PATCHv3 4/5] gitweb: Starting work on a man page for /etc/gitweb.conf (WIP)\"\n  http://thread.gmane.org/gmane.comp.version-control.git/175140/focus=175145\n\nThis version now moves, rather than copies, contents from\ngitweb/README file.  It now has up-to-date commit message.\n\nIt was also updated to include new gitweb-comon.conf config file\n(common system-wide config file, used *in addition to* per-instance\ngitweb_config.perl config file).\n\n\n3. The man page for gitweb is improved version of patch I have sent to\ngit mailing list as\n\n  \"[RFC/PATCHv3 5/5] gitweb: Starting work on a man page for gitweb (WIP)\"\n  http://thread.gmane.org/gmane.comp.version-control.git/175140/focus=175146\n \nThis version was fixed to render correctly as HTML and as manpage, and\nhas update commit message.\n\n\n4. The addition of gitweb manpages to 'gitweb' subpackage in\ngitweb.spec (via gitweb.spec.in) is new in this series.\n\n\nShortlog:\n~~~~~~~~~\nDrew Northup (1):\n  gitweb: Add manpage for /etc/gitweb.conf (for gitweb documentation)\n\nJakub Narebski (3):\n  Documentation: Preparation for gitweb manpages\n  gitweb: Add manpage for gitweb\n  gitweb: Add gitweb manpages to 'gitweb' package in git.spec\n\nDiffstat:\n~~~~~~~~~\n Documentation/Makefile        |    7 +-\n Documentation/gitweb.conf.txt |  789 +++++++++++++++++++++++++++++++++++++++++\n Documentation/gitweb.txt      |  703 ++++++++++++++++++++++++++++++++++++\n git.spec.in                   |    7 +\n gitweb/INSTALL                |   96 +-----\n gitweb/Makefile               |    7 +-\n gitweb/README                 |  411 ++--------------------\n 7 files changed, 1540 insertions(+), 480 deletions(-)\n create mode 100644 Documentation/gitweb.conf.txt\n create mode 100644 Documentation/gitweb.txt\n\n-- \n1.7.6\n"},{"id":"175715","messageId":"1316352884-26193-2-git-send-email-jnareb@gmail.com","threadId":"28418","inReplyTo":"1316352884-26193-1-git-send-email-jnareb@gmail.com","subject":"[PATCH/RFCv4 1/4] Documentation: Preparation for gitweb manpages","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2011-09-18T13:34:41Z","receivedAt":"2011-09-18T13:34:41Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Gitweb documentation currently consist of gitweb/README, gitweb/INSTALL\nand comments in gitweb source code.  This is harder to find, use and\nbrowse that manpages (\"man gitweb\" or \"git help gitweb\") and HTML\ndocumentation (\"git help --web gitweb\").\n\nThe goal is to move documentation out of gitweb/README to gitweb.txt and\ngitweb.conf.txt manpages, reducing its size 10x from around 500 to\naround 50 lines (two pages), and move information not related drectly to\nbuilding and installing gitweb out of gitweb/INSTALL there.\n\nThe idea is to have gitweb manpage sources reside in AsciiDoc format\nin Documentation/ directory, like for gitk and git-gui.  Alternate\nsolution would be to have gitweb documentation in gitweb/ directory,\nperhaps in POD format (see perlpod(1)).\n\n\nThis patch adds infrastructure for easy generating gitweb-related\nmanpages.  It adds currently empty 'gitweb-doc' target to\nDocumentation/Makefile, and 'doc' proxy target to gitweb's Makefile.\n\nThis way to build gitweb documentation one can use\n\n  make -C gitweb doc\n\nor\n\n  cd gitweb; make doc\n\nThe gitweb.conf(5) and gitweb(1) manpages will be added in subsequent\ncommits.\n\nSigned-off-by: Jakub Narebski <jnareb@gmail.com>\n---\nThis changes were part of patch adding first gitweb manpage in\nprevious version of this series.\n\nCompared to v3 series it lacks the following hunk (at the very end of\nDocumentation/Makefile):\n\n  @@ -334,4 +337,4 @@ quick-install-man:\n   quick-install-html:\n   \t'$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(HTML_REF) $(DESTDIR)$(htmldir)\n  \n  -.PHONY: FORCE\n  +.PHONY: FORCE gitweb-doc\n\nThis is because it would introduce inconsistency, as 'gitweb-doc'\nwould be only one of many phony targets in Documentation/Makefile\nthat is explicitly marked .PHONY\n\nSo this is something left for other commit.\n\n Documentation/Makefile |    3 +++\n gitweb/Makefile        |    7 ++++++-\n 2 files changed, 9 insertions(+), 1 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 6346a75..44be67b 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -170,6 +170,9 @@ info: git.info gitman.info\n \n pdf: user-manual.pdf\n \n+GITWEB_DOC = $(filter gitweb.%,$(DOC_HTML) $(DOC_MAN1) $(DOC_MAN5) $(DOC_MAN7))\n+gitweb-doc: $(GITWEB_DOC)\n+\n install: install-man\n \n install-man: man\ndiff --git a/gitweb/Makefile b/gitweb/Makefile\nindex 1c85b5f..3014d80 100644\n--- a/gitweb/Makefile\n+++ b/gitweb/Makefile\n@@ -174,6 +174,11 @@ test-installed:\n \tGITWEB_TEST_INSTALLED='$(DESTDIR_SQ)$(gitwebdir_SQ)' \\\n \t\t$(MAKE) -C ../t gitweb-test\n \n+### Documentation\n+\n+doc:\n+\t$(MAKE) -C ../Documentation gitweb-doc\n+\n ### Installation rules\n \n install: all\n@@ -187,5 +192,5 @@ install: all\n clean:\n \t$(RM) gitweb.cgi static/gitweb.min.js static/gitweb.min.css GITWEB-BUILD-OPTIONS\n \n-.PHONY: all clean install test test-installed .FORCE-GIT-VERSION-FILE FORCE\n+.PHONY: all clean install test test-installed doc .FORCE-GIT-VERSION-FILE FORCE\n \n-- \n1.7.6\n"},{"id":"175716","messageId":"1316352884-26193-3-git-send-email-jnareb@gmail.com","threadId":"28418","inReplyTo":"1316352884-26193-1-git-send-email-jnareb@gmail.com","subject":"[PATCH/RFCv4 2/4] gitweb: Add manpage for /etc/gitweb.conf (for gitweb documentation)","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2011-09-18T13:34:42Z","receivedAt":"2011-09-18T13:34:42Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"From: Drew Northup <drew.northup@maine.edu>\n\nMuch of what is in gitweb.conf.txt has been pulled directly from the\nREADME file of gitweb.  The manpage was supplemented with description\nof missing gitweb config variables, and with description of gitweb's\n%features.\n\nThere remains a bit of redundancy, which should be reduced if\npossible... but I think some of duplication of information is\ninevitable.\n\n[jn: Improved, extended, removed duplicate info from README]\n\nSigned-off-by: Drew Northup <drew.northup@maine.edu>\nSigned-off-by: Jakub Narebski <jnareb@gmail.com>\n---\nDifferences from v3 version include:\n\n* SYNOPSIS changed from ssh_config(5) like to gitignore(5) like,\n  i.e. [verse] changed to straight list of files\n\n* The beginning of DISCUSSION section now mentions new gitweb-common.conf\n  file, and was significantly rewritten for better readibility, following\n  gitweb/README.\n\n* FILES and ENVIRONMENT section mention /etc/gitweb-common.conf and\n  GITWEB_CONFIG_COMMON, respectively.\n\n* Added information about inclusion mechanism, i.e. read_config_file()\n  subroutine.\n\n* Fixed formatting of continued description list\n\n* Infrastructure for supporting \"make -C gitweb doc\" (used to test\n  formatted output of manpages from those patches) is now moved to a\n  separate, earlier commit.\n\n Documentation/Makefile        |    2 +-\n Documentation/gitweb.conf.txt |  781 +++++++++++++++++++++++++++++++++++++++++\n gitweb/README                 |  133 +-------\n 3 files changed, 783 insertions(+), 133 deletions(-)\n create mode 100644 Documentation/gitweb.conf.txt\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 44be67b..6d71943 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -3,7 +3,7 @@ MAN1_TXT= \\\n \t\t$(wildcard git-*.txt)) \\\n \tgitk.txt git.txt\n MAN5_TXT=gitattributes.txt gitignore.txt gitmodules.txt githooks.txt \\\n-\tgitrepository-layout.txt\n+\tgitrepository-layout.txt gitweb.conf.txt\n MAN7_TXT=gitcli.txt gittutorial.txt gittutorial-2.txt \\\n \tgitcvs-migration.txt gitcore-tutorial.txt gitglossary.txt \\\n \tgitdiffcore.txt gitnamespaces.txt gitrevisions.txt gitworkflows.txt\ndiff --git a/Documentation/gitweb.conf.txt b/Documentation/gitweb.conf.txt\nnew file mode 100644\nindex 0000000..2769302\n--- /dev/null\n+++ b/Documentation/gitweb.conf.txt\n@@ -0,0 +1,781 @@\n+gitweb.conf(5)\n+==============\n+\n+NAME\n+----\n+gitweb.conf - Gitweb (git web interface) configuration file\n+\n+SYNOPSIS\n+--------\n+/etc/gitweb.conf, /etc/gitweb-common.conf, $GITWEBDIR/gitweb_config.perl\n+\n+DESCRIPTION\n+-----------\n+\n+The gitweb CGI script for viewing Git repositories over the web uses a\n+perl script fragment as its configuration file.  You can set variables\n+using \"`our $variable = value`\"; text from a \"#\" character until the\n+end of a line is ignored.  See *perlsyn*(1) for details.\n+\n+An example:\n+\n+    # gitweb configuration file for http://git.example.org\n+    #\n+    our $projectroot = \"/srv/git\"; # FHS recommendation\n+    our $site_name = 'Example.org >> Repos';\n+\n+\n+The configuration file is used to override the default settings that\n+were built into gitweb at the time 'gitweb.cgi' script was generated.\n+\n+While one could just alter the configuration settings in the gitweb\n+CGI itself, those changes would be lost upon upgrade.  Configuration\n+settings might also be placed into a file in the same directory as the\n+CGI script with the default name 'gitweb_config.perl' -- allowing\n+one to have multiple gitweb instances with different configurations by\n+the use of symlinks.\n+\n+\n+DISCUSSION\n+----------\n+Gitweb obtains configuration data from the following sources in the\n+following order:\n+\n+ * built-in values (some set during build stage),\n+\n+ * common system-wide configuration file (defaults to\n+   '/etc/gitweb-common.conf'),\n+\n+ * either per-instance configuration file (defaults to 'gitweb_config.perl'\n+   in the same directory as the installed gitweb), or if it does not exists\n+   then system-wide configuration file (defaults to '/etc/gitweb.conf').\n+\n+Values obtained in later configuration files override values obtained earlier\n+in above sequence.\n+\n+The location of common system-wide configuration file, of fallback system-wide\n+configuration file and of per-instance configuration file is defined at compile\n+time using the build-time Makefile configuration variables, respectively\n+`GITWEB_CONFIG_COMMON`, `GITWEB_CONFIG_SYSTEM` and `GITWEB_CONFIG`.  \n+\n+You can override location of gitweb configuration files during runtime\n+by setting respective environment variables: `GITWEB_CONFIG_COMMON`,\n+`GITWEB_CONFIG_SYSTEM` and `GITWEB_CONFIG` to non-empty value.\n+\n+\n+The syntax of the configuration files is that of Perl, as these files are\n+indeed handled as fragments of Perl code (the language that gitweb itself is\n+written in). Variables may be set using \"`our $variable = value`\"; text from\n+\"#\" character until the end of a line is ignored. See the *perlsyn*(1) man\n+page for more information.\n+\n+Actually using `our` qualifier in `our $variable = <value>;` is a safety\n+check: if newer gitweb does no longer use given variable, by using `our` we\n+won't get syntax errors.\n+\n+You can include other configuration file using read_config_file()\n+subroutine.  For example, you can read defaults in fallback\n+system-wide GITWEB_CONFIG_SYSTEM from GITWEB_CONFIG by adding\n+\n+  read_config_file($GITWEB_CONFIG_SYSTEM);\n+\n+at very beginning of per-instance GITWEB_CONFIG file.  In this case\n+settings in said per-instance file will override settings from\n+system-wide configuration file.  Note that read_config_file checks\n+itself that the file it reads exists.\n+\n+\n+The default configuration with no configuration file at all may work\n+perfectly well for some installations.  Still, a configuration file is\n+useful for customizing or tweaking the behavior of gitweb in many ways, and\n+some optional features will not be present unless explicitly enabled using\n+the configurable `%features` variable (see also \"Configuring gitweb\n+features\" section below).\n+\n+\n+CONFIGURATION VARIABLES\n+-----------------------\n+Some of configuration variables have their default values (embedded in CGI\n+file) set during building gitweb -- if that is the case, it is put in their\n+description.  See gitweb's 'INSTALL' file for instructions on building and\n+installing gitweb.\n+\n+\n+Location of repositories\n+~~~~~~~~~~~~~~~~~~~~~~~~\n+Configuration variables described below control finding git repositories by\n+gitweb, and control display and access to repositories.\n+\n+$projectroot::\n+\tAbsolute filesystem path which will be prepended to project path;\n+\tthe path to repository is `$projectroot/$project`.  Set to\n+\t`$GITWEB_PROJECTROOT` during installation.  This variable has to be\n+\tset correctly for gitweb to find repositories.\n++\n+For example if `$projectroot` is set to \"/srv/git\" by putting the following\n+in gitweb config file:\n++\n+----------------------------------------------------------------------------\n+our $projectroot = \"/srv/git\";\n+----------------------------------------------------------------------------\n++\n+then\n++\n+------------------------------------------------\n+http://git.example.com/gitweb.cgi?p=foo/bar.git\n+------------------------------------------------\n++\n+or its path_info based equivalent\n++\n+------------------------------------------------\n+http://git.example.com/gitweb.cgi/foo/bar.git\n+------------------------------------------------\n++\n+will map to path '/srv/git/foo/bar.git' on filesystem.\n+\n+$project_maxdepth::\n+\tFilesystem traversing depth limit for recursively scanning for git\n+\trepositories, used if `$projects_list` (below) is unset.  The default\n+\tvalue of this variable is determined by build-time configuration\n+\tvariable `GITWEB_PROJECT_MAXDEPTH`, which defaults to 2007.\n+\n+$projects_list::\n+\tPlain text file listing projects or name of directory\n+\tto be scanned for projects.\n++\n+Project list files should list one project per line, with each line\n+having the following format\n++\n+-----------------------------------------------------------------------------\n+<URI-encoded filesystem path to repository> SP <URI-encoded repository owner>\n+-----------------------------------------------------------------------------\n++\n+The default value of this variable is determined by the `GITWEB_LIST`\n+makefile variable at installation time.  If this variable is empty, gitweb\n+will fall back to scanning the `$projectroot` directory for repositories.\n+\n+$export_ok::\n+\tShow repository only if this file exists (in repository).  Only\n+\teffective if this variable evaluates to true.  Can be set during\n+\tbuilding gitweb via `GITWEB_EXPORT_OK`.  [No default / Not set]\n+\n+$export_auth_hook::\n+\tShow repository only if this subroutine returns true, when given as\n+\tthe only parameter the full path to the project.  Example:\n++\n+----------------------------------------------------------------------------\n+our $export_auth_hook = sub { return -e \"$_[0]/git-daemon-export-ok\"; };\n+----------------------------------------------------------------------------\n++\n+though the above might be done by using `$export_ok` instead\n++\n+----------------------------------------------------------------------------\n+our $export_ok = \"git-daemon-export-ok\";\n+----------------------------------------------------------------------------\n+\n+$strict_export::\n+\tOnly allow viewing of repositories also shown on the overview page.\n+\tThis for example makes `$gitweb_export_ok` file decide if repository is\n+\tavailable and not only if it is shown.  If `$gitweb_list` points to\n+\tfile with list of project, only those repositories listed would be\n+\tavailable for gitweb.  Can be set during building gitweb via\n+\t`GITWEB_STRICT_EXPORT`.  [No default / Not set]\n+\n+\n+Finding files\n+~~~~~~~~~~~~~\n+Those configuration variables tell gitweb where to find files.  Values of\n+those variables are paths on filesystem.  Of those only `$GIT` is required\n+to be (correctly) set for gitweb to be able to work; all the rest are\n+required only for extra configuration or extra features.\n+\n+$GIT::\n+\tCore git executable to use.  By default set to `$GIT_BINDIR/git`, which\n+\tin turn is by default set to `$(bindir)/git`.  If you use git from binary\n+\tpackage, set this to \"/usr/bin/git\".  This can just be \"git\" if your\n+\twebserver has a sensible PATH.  If you have multiple git versions installed\n+\tit can be used to choose which one to use.\n+\n+$mimetypes_file::\n+\tFile to use for (filename extension based) guessing of MIME types before\n+\ttrying '/etc/mime.types'.  Path, if relative, is taken currently as\n+\trelative to the current git repository.  [Unset by default]\n+\n+$highlight_bin::\n+\tPath to the highlight executable to use (must be the one from\n+\thttp://www.andre-simon.de due to assumptions about parameters and output).\n+\tUseful if 'highlight' is not installed on your webserver's PATH.\n+        [Default: 'highlight']\n++\n+*NOTE*: if you want to add support for new syntax (supported by\n+\"highlight\" but not used by gitweb), you need to modify `%highlight_ext`\n+or `%highlight_basename`, depending on whether you detect type of file\n+based on extension (for example \"*.sh\") or on its basename (for example\n+\"Makefile\").  Keys of those hashes are extension or basename,\n+respectively, and value for given key is name of syntax to be passed via\n+`--syntax <syntax>` to highlighter.\n+\n+\n+Links and their targets\n+~~~~~~~~~~~~~~~~~~~~~~~\n+Configuration variables described below configure some of gitweb links:\n+their target and their look (text or image), and where to find page\n+prerequisites (stylesheet, favicon, images, scripts).  Usually they are left\n+at their default values, with the possible exception of `@stylesheets`\n+variable.\n+\n+@stylesheets::\n+\tList of URIs of stylesheets (relative to base URI of a page). You\n+\tmight specify more than one stylesheet, for example use gitweb.css\n+\tas base, with site specific modifications in separate stylesheet\n+\tto make it easier to upgrade gitweb. You can add a `site` stylesheet\n+\tfor example by putting\n++\n+----------------------------------------------------------------------------\n+push @stylesheets, \"gitweb-site.css\";\n+----------------------------------------------------------------------------\n++\n+in the gitweb config file.  Those values that are relative paths, are\n+relative to base URI of gitweb.\n++\n+This list should contain URI of gitweb's stylesheet.  The URI of gitweb\n+stylesheet is set during build time via `GITWEB_CSS` variable.  It's default\n+value is 'static/gitweb.css' (or 'static/gitweb.min.css' if the `CSSMIN`\n+variable is defined, i.e. if CSS minifier is used during build).\n++\n+*Note*: there is also legacy `$stylesheet` configuration variable, which was\n+used by older gitweb.\n+\n+$logo::\n+\tPoints to the location where you put 'git-logo.png' on your web\n+\tserver, or to be more generic URI of logo, 72x27 size).  This image\n+\tis displayed in top right corner of each gitweb page, and used as\n+\tlogo for Atom feed.  Relative to base URI of gitweb (as a path).\n+\tCan be adjusted during building gitweb using `GITWEB_LOGO` variable\n+        [Default: 'static/git-logo.png']\n+\n+$favicon::\n+\tPoints to the location where you put 'git-favicon.png' on your web\n+\tserver, or to be more generic URI of favicon, assumed to be\n+\t\"image/png\" type; web browsers that support favicons (website icons)\n+\tmay display them in the browser's URL bar and next to site name in\n+\tbookmarks.  Relative to base URI of gitweb.  Can be adjusted during\n+\tbuild time using `GITWEB_FAVICON` variable.\n+        [Default: 'static/git-favicon.png']\n+\n+$javascript::\n+\tPoints to the location where you put 'gitweb.js' on your web server,\n+\tor to be more generic URI of JavaScript code used by gitweb.\n+\tRelative to base URI of gitweb.  Set during build time using\n+\t`GITWEB_JS` build-time configuration variable.\n++\n+Default value is either 'static/gitweb.js', or 'static/gitweb.min.js' if\n+`JSMIN` build variable is defined, i.e. if JavaScript minifier is used\n+during build.  *Note* that this single file is build (composed) of\n+individual JavaScript \"modules\".\n+\n+$home_link::\n+\tTarget of the home link on top of all pages (the first part of view\n+\t\"breadcrumbs\").  By default set to absolute URI of a page ($my_uri).\n+\n+$home_link_str::\n+\tDescription of the home link on top of all pages, leading to $home_link\n+\t(usually main gitweb page, which means projects list).  Used as first\n+\tpart of gitweb view \"breadcrumb trail\": `<home> / <project> / <view>`.\n+\tCan be set during build time using `GITWEB_HOME_LINK_STR` variable.\n+\t[Default: \"projects\"]\n+\n+$logo_url::\n+$logo_label::\n+\tURI and label (title) of GIT logo link (or your site logo, if you choose\n+\tto use different logo image). By default they point to git homepage;\n+\tin the past they pointed to git documentation at www.kernel.org.\n+\n+\n+Changing gitweb look\n+~~~~~~~~~~~~~~~~~~~~\n+You can adjust how pages generated by gitweb look using variables described\n+below.  You can change site name, add common headers and footers for all\n+pages, and add description of gitweb installation on its main page (which is\n+projects list page), etc.\n+\n+$site_name::\n+\tName of your site or organization to appear in page titles.  Set it\n+\tto something descriptive for clearer bookmarks etc.  If not set (if\n+\tempty) then gitweb uses value of `SERVER_NAME` CGI environment\n+\tvariable setting prefix of each page title to \"$SERVER_NAME Git\", or\n+\t\"Untitled Git\" if this variable is not set (e.g. if running gitweb\n+\tas standalone script).\n++\n+Can be set using `GITWEB_SITENAME` during building.  [No default]\n+\n+$site_header::\n+\tFilename of html text to include at top of each page.  Relative to\n+\t'gitweb.cgi' script.  Can be set using `GITWEB_SITE_HEADER` during\n+\tbuilding.  [No default]\n+\n+$site_footer::\n+\tFilename of html text to include at bottom of each page.  Relative to\n+\tgitweb.cgi script.  Can be set using `GITWEB_SITE_FOOTER` during\n+\tbuilding.  [No default]\n+\n+$home_text::\n+\tPoints to an HTML file which, if it exists, is included on the\n+\tgitweb projects overview page (\"projects_list\" view).  Relative to\n+\tgitweb.cgi script.  Default value can be adjusted using during build\n+\tvia `GITWEB_HOMETEXT` variable.\n+\t[Default: 'indextext.html']\n+\n+$projects_list_description_width::\n+\tThe width (in characters) of the projects list \"Description\" column.\n+\tLonger descriptions will be cut (trying to cut at word boundary);\n+\tfull description is available as 'title' attribute (usually shown on\n+\tmouseover).  By default set to 25, which might be too small if you\n+\tuse long project descriptions.\n+\n+$default_projects_order::\n+\tDefault value of ordering of projects on projects list page.  Valid\n+\tvalues are \"none\" (unsorted), \"project\" (by project name, i.e. path\n+\tto repository relative to `$projectroot`), \"descr\" (project\n+\tdescription), \"owner\", and \"age\" (by date of most current commit).\n++\n+Default value is \"project\".  Unknown value means unsorted.\n+\n+\n+Changing gitweb behavior\n+~~~~~~~~~~~~~~~~~~~~~~~~\n+Those configuration variables control _internal_ gitweb behavior.\n+\n+$default_blob_plain_mimetype::\n+\tDefault mimetype for blob_plain (raw) view, if mimetype checking\n+\tdoesn't result in some other type; by default \"text/plain\".\n+\n+$default_text_plain_charset::\n+\tDefault charset for text files. If not set, web server configuration\n+\twould be used.\n+\n+$fallback_encoding::\n+\tGitweb assumes this charset if line contains non-UTF-8 characters.\n+\tFallback decoding is used without error checking, so it can be even\n+\t\"utf-8\". Value must be valid encoding; see *Encoding::Supported*(3pm)\n+\tman page for a list.  By default \"latin1\", aka. \"iso-8859-1\".\n+\n+@diff_opts::\n+\tRename detection options for git-diff and git-diff-tree. By default\n+\t(\\'-M'); set it to (\\'-C') or (\\'-C', \\'-C') to also detect copies,\n+\tor set it to () i.e. empty list if you don't want to have renames\n+\tdetection.\n+\n+Extra features, administrative\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+Most of features are configured via `%feature` hash; however some of extra\n+gitweb features can be turned on and configured using variables described\n+below.  This list beside configuration variables that control how gitweb\n+looks does contain variables configuring administrative side of gitweb\n+(e.g. cross-site scripting prevention; admittedly this as side effect\n+affects how \"summary\" pages look like, or load limiting).\n+\n+@git_base_url_list::\n+\tList of git base URLs used for URL to where fetch project from, shown\n+\tin project summary page.  Full URL is \"`$git_base_url/$project`\".  You\n+\tcan setup multiple base URLs (for example one for `git://` protocol\n+\taccess, and one for `http://` \"dumb\" protocol access).  Note that per\n+\trepository configuration can be set in '$GIT_DIR/cloneurl' file, or as\n+\tvalues of multi-value `gitweb.url` configuration variable in project\n+\tconfig.\n++\n+You can setup one single value (single entry/item in this list) during\n+building by using `GITWEB_BASE_URL` built-time configuration variable.\n+[No default]\n+\n+$projects_list_group_categories::\n+\tEnables the grouping of projects by category on the project list page.\n+\tThe category of a project is determined by the `$GIT_DIR/category` file\n+\tor the `gitweb.category` variable in its repository configuration.\n+\t[Disabled by default].\n+\n+$project_list_default_category::\n+\tDefault category for projects for which none is specified.  If set to\n+\tthe empty string, such projects will remain uncategorized and listed at\n+\tthe top, above categorized projects.  Used only if project cateories are\n+\tenabled, which means if `$projects_list_group_categories` is true.\n+\t[Default: \"\" (empty string)]\n+\n+$prevent_xss::\n+\tIf true, some gitweb features are disabled to prevent content in\n+\trepositories from launching cross-site scripting (XSS) attacks.  Set this\n+\tto true if you don't trust the content of your repositories.\n+\t[Default: false].\n+\n+$maxload::\n+\tUsed to set the maximum load that we will still respond to gitweb queries.\n+\tIf server load exceed this value then return \"503 Service Unavailable\"\n+\terror. Server load is taken to be 0 if gitweb cannot determine its value.\n+\tSet it to undefined value to turn it off. [Default: 300]\n+\n+$per_request_config::\n+\tIf set to code reference, it would be run once per each request.  You can\n+\tset parts of configuration that change per session, e.g. by adding\n+\tthe following code to gitweb configuration file\n++\n+--------------------------------------------------------------------------------\n+our $per_request_config = sub {\n+\t$ENV{GL_USER} = $cgi->remote_user || \"gitweb\";\n+};\n+--------------------------------------------------------------------------------\n++\n+Otherwise it is treated as boolean value: if true gitweb would process\n+config file once per request, if false it would process config file only\n+once.  [Default: true]\n++\n+*NOTE*: `$my_url`, `$my_uri`, and `$base_url` are overwritten with their default\n+values before every request, so if you want to change them, be sure to set\n+this variable to true or a code reference effecting the desired changes.\n+\n+\n+Other variables\n+~~~~~~~~~~~~~~~\n+Usually you should not need to change (adjust) any of configuration\n+variables described below; they should be automatically set by gitweb to\n+correct value.\n+\n+\n+$version::\n+\tGitweb version, set automatically when creating gitweb.cgi from\n+\tgitweb.perl. You might want to modify it if you are running modified\n+\tgitweb, for example \n++\n+---------------------------------------------------\n+our $version .= \" with caching\";\n+---------------------------------------------------\n+\n+$my_url::\n+$my_uri::\n+\tFull URL and absolute URL of gitweb script;\n+\tin earlier versions of gitweb you might have need to set those\n+\tvariables, now there should be no need to do it.  See\n+\t`$per_request_config` if you need to set them still.\n+\n+$base_url::\n+\tBase URL for relative URLs in pages generated by gitweb,\n+\t(e.g. `$logo`, `$favicon`, `@stylesheets` if they are relative URLs),\n+\tneeded and used only for URLs with nonempty PATH_INFO via\n+\t'<base href=\"$base_url\">'.  Usually gitweb sets its value correctly,\n+\tand there is no need to set this variable, e.g. to $my_uri or \"/\".\n+\tSee `$per_request_config` if you need to set it anyway.\n+\n+\n+CONFIGURING GITWEB FEATURES\n+---------------------------\n+Many gitweb features can be enabled (or disabled) and configured using the\n+`%feature` hash.  Names of gitweb features are keys of this hash.\n+\n+Each `%feature` hash element is a hash reference and has the following\n+structure:\n+----------------------------------------------------------------------\n+\"<feature_name>\" => {\n+\t\"sub\" => <feature-sub (subroutine)>,\n+\t\"override\" => <allow-override (boolean)>,\n+\t\"default\" => [ <options>... ]\n+},\n+----------------------------------------------------------------------\n+Some of features does not support project specific override.  For those\n+features the structure of appropriate `%feature` hash element has a simpler\n+form:\n+----------------------------------------------------------------------\n+\"<feature_name>\" => {\n+\t\"override\" => 0,\n+\t\"default\" => [ <options>... ]\n+},\n+----------------------------------------------------------------------\n+As one can see it lacks \\'sub' element.\n+\n+The meaning of respective parts of feature configuration are described\n+below:\n+\n+default::\n+\tList (array reference) of feature parameters (if there are any),\n+\tused also to toggle (enable or disable) given feature.\n++\n+Note that it is currently *always* an array reference, even if\n+feature doesn't accept any configuration parameters, and \\'default'\n+is used only to turn it on or off.  In such case you turn feature on\n+by setting this element to `[1]`, and torn it off by setting it to\n+`[0]`.  See also part about \"blame\" feature in the \"Examples\"\n+section.\n++\n+To disable feature that accepts parameters (is configurable), you\n+need to set this element to empty list i.e. `[]`.\n+\n+override::\n+\tIf it has a true value then given feature is overridable, which\n+\tmeans that it can be configured (or enabled/disabled) on\n+\tper-repository basis.\n++\n+Usually given \"<feature>\" is configurable via `gitweb.<feature>`\n+config variable in per-repository git configuration file.\n++\n+*Note* that no feature is overridable by default.\n+\n+sub::\n+\tSubroutine that will be called with default options as parameters to\n+\texamine per-repository configuration, but only if feature is\n+\toverridable (\\'override' is set to true).  If not present then\n+\tper-repository override for given feature is not supported.\n++\n+You wouldn't need to ever change it in gitweb config file.\n+\n+\n+Features in `%feature`\n+~~~~~~~~~~~~~~~~~~~~~~\n+Below there are described gitweb features that are configurable via\n+`%feature` hash.  For a complete list please consult gitweb sources.\n+\n+blame::\n+\tEnable the \"blame\" and \"blame_incremental\" blob views, showing for\n+\teach line the last commit that modified it; see linkgit:git-blame[1].\n+\tThis can be very CPU-intensive and is therefore disabled by default.\n++\n+This feature can be configured on a per-repository basis via\n+repository's `gitweb.blame` configuration variable (boolean).\n+\n+snapshot::\n+\tEnable and configure \"snapshot\" action, providing a compressed\n+\tarchive of any tree or commit; see also linkgit:git-archive[1].\n+\tThis can potentally generate high traffic if you have large project.\n++\n+The value (of \\'default') is a list of names of snapshot formats\n+defined in `%known_snapshot_formats` hash, that you wish to offer.\n+Among supported formats are \"tgz\", \"tbz2\", \"txz\" (gzip/bzip2/xz\n+compressed tar archive) and \"zip\"; please consult gitweb sources for\n+a definitive list.  By default only \"tgz\" is offered.\n++\n+This feature can be configured on a per-repository basis via\n+repository's `gitweb.blame` configuration variable, which contains\n+a comma separated list of formats, or \"none\" to disable snapshots.\n+Unknown values will be ignored.\n+\n+grep::\n+\tEnable grep search, which will list the files in currently selected\n+\ttree (directory) containing the given string; see linkgit:git-grep[1].\n+\tThis can be potentially CPU-intensive, of course.  Enabled by default.\n++\n+This feature can be configured on a per-repository basis via\n+repository's `gitweb.grep` configuration variable (boolean).\n+\n+pickaxe::\n+\tEnable the so called pickaxe search, which will list the commits\n+\tthat modified a given string in a file.  This can be practical and\n+\tquite faster alternative to \"blame\" action, but still potentially\n+\tCPU-intensive.  Enabled by default.\n++\n+The pickaxe search is described in linkgit:git-log[1] (the\n+description of `-S<string>` option, which refers to pickaxe entry in\n+linkgit:gitdiffcore[7] for more details).\n++\n+This feature can be configured on a per-repository basis via\n+repository's `gitweb.pickaxe` configuration variable (boolean).\n+\n+show-sizes::\n+\tEnable showing size of blobs (ordinary files) in a \"tree\" view, in a\n+\tseparate column, similar to what `ls -l` does; see description of\n+\t`-l` option in linkgit:git-ls-tree[1] manpage.  This cost a bit of\n+\tI/O.  Enabled by default.\n++\n+This feature can be configured on a per-repository basis via\n+repository's `gitweb.showsizes` configuration variable (boolean).\n+\n+patches::\n+\tConfigure \"patches\" view, which displays list of commits in email\n+\t(plain text) output format; see also linkgit:git-format-patch[1].\n+\tThe value is the maximum number of patches in a patchset generated\n+\tin \"patches\" view.  Set this to 0 or undef to disable patch view, or\n+\tto a negative number to remove any limit.  Default value is 16.\n++\n+This feature can be configured on a per-repository basis via\n+repository's `gitweb.patches` configuration variable (integer).\n+\n+avatar::\n+\tAvatar support.  When this feature is enabled, views such as\n+\t\"shortlog\" or \"commit\" will display an avatar associated with\n+\tthe email of the committer(s) and/or author(s).\n++\n+Currently available providers are *\"gravatar\"* and *\"picon\"*.\n+If an unknown provider is specified, the feature is disabled.\n+*Note* that some provides might require extra Perl packages to be\n+installed; see 'gitweb/INSTALL' for more details.\n++\n+This feature can be configured on a per-repository basis via\n+repository's `gitweb.avatar` configuration variable.\n++\n+See also `%avatar_size` with pixel sizes for icons and avatars\n+(\"default\" is used for one-line like \"log\" and \"shortlog\", \"double\"\n+is used for two-line like \"commit\", \"commitdiff\" or \"tag\").  If the\n+default font sizes or lineheights are changed (e.g. via adding extra\n+CSS stylesheet in `@stylesheets`), it may be appropriate to change\n+these values.\n+\n+highlight::\n+\tServer-side syntax hightlight support in \"blob\" view.  It requires\n+\t`$highlight_bin` program available (see description of this variable\n+\tin \"Configuration variables\" section above), and therefore is\n+\tdisabled by default.\n++\n+This feature can be configured on a per-repository basis via\n+repository's `gitweb.highlight` configuration variable (boolean).\n+\n+remote_heads::\n+\tEnable displaying remote heads (remote-tracking branches) in the \"heads\"\n+\tlist.  In most cases it is unnecessary internal private detail, and it\n+\tis therefore disabled by default.  linkgit:git-instaweb[1], which is\n+\tusually used to browse local repositories, enables and uses this\n+\tfeature.\n++\n+This feature can be configured on a per-repository basis via\n+repository's `gitweb.remote_heads` configuration variable (boolean).\n+\n+\n+The list below presents features that do not allow project specific\n+overrides.\n+\n+search::\n+\tEnable text search, which will list the commits which match author,\n+\tcommitter or commit text to a given string; see description of\n+\t`--author`, `--committer` and `--grep` options in linkgit:git-log[1]\n+\tmanpage.  Enabled by default.\n++\n+Project specific override is not supported.\n+\n+forks::\n+\tMake gitweb consider projects in subdirectories of project root\n+\t(basename) to be forks of existing projects.  Given project\n+\t`$projname.git`, projects matching `$projname/*.git` will not be\n+\tshown in the main projects list, instead a \\'+' mark will be added\n+\tto `$projname` there and a \"forks\" view will be enabled for the\n+\tproject, listing all the forks.  If project list is taken from a\n+\tfile, forks have to be listed after the main project.\n++\n+Project specific override is not supported.\n+\n+actions::\n+\tInsert custom links to the action bar of all project pages.  This\n+\tenables you to link to third-party scripts integrating into gitweb.\n++\n+The \"default\" value consists of a list of triplets in the form\n+`(\"<label>\", \"<link>\", \"<position>\")` where \"position\" is the label\n+after which to insert the link, \"link\" is a format string where `%n`\n+expands to the project name, `%f` to the project path within the\n+filesystem, `%h` to the current hash (\\'h' gitweb parameter) and\n+`%b` to the current hash base (\\'hb' gitweb parameter); `%%` expands\n+to \\'%'.\n++\n+For example http://repo.or.cz git hosting site sets it to the\n+following to enable graphical log (via third party tool\n+*git-browser*):\n++\n+----------------------------------------------------------------------\n+$feature{'actions'}{'default'} =\n+\t[ ('graphiclog', '/git-browser/by-commit.html?r=%n', 'summary')];\n+----------------------------------------------------------------------\n++\n+This adds link titled \"graphiclog\" after \"summary\" link, leading to\n+`git-browser` script, passing `r=<project>` as a query parameter.\n++\n+Project specific override is not supported.\n+\n+timed::\n+\tEnable displaying how much time and how many git commands it took to\n+\tgenerate and display page in the page footer (at the bottom of\n+\tpage).  For example it might be: \"This page took 6.53325 seconds and\n+\t13 git commands to generate.\"  Disabled by default.\n++\n+Project specific override is not supported.\n+\n+javascript-timezone::\n+\tEnable and configure ability to change common timezone for dates in\n+\tgitweb output via JavaScript.  Dates in gitweb output include\n+\tauthordate and comitterdate in \"commit\", \"commitdiff\" and \"log\"\n+\tviews, and taggerdate in \"tag\" view.  Enabled by default.\n++\n+Value is list of three values: default timezone (if client didn't\n+select other timezone and saved it in a cookie), name of cookie\n+where to store selected timezone, and CSS class used to mark up\n+dates for manipulation.  If you want to turn it off, set \"default\"\n+to empty list: `[]`.\n++\n+In most case you would want to change only default timezone:\n++\n+---------------------------------------------------------------------------\n+$feature{'javascript-timezone'}{'default'}[0] = \"utc\";\n+---------------------------------------------------------------------------\n++\n+Timezone value can be \"local\" (for local timezone that browser uses), \"utc\"\n+(what gitweb uses when JavaScript or this feature is disabled), or numerical\n+timezone in the form of \"+/-HHMM\" for example \"+0200\".  This way is\n+guaranteed to be backward compatibile.\n++\n+Project specific override is not supported.\n+\n+\n+EXAMPLES\n+--------\n+\n+To enable blame, pickaxe search, and snapshot support (allowing \"tar.gz\" and\n+\"zip\" snapshots), while allowing individual projects to turn them off, put\n+the following in your GITWEB_CONFIG file:\n+\n+        $feature{'blame'}{'default'} = [1];\n+        $feature{'blame'}{'override'} = 1;\n+\n+        $feature{'pickaxe'}{'default'} = [1];\n+        $feature{'pickaxe'}{'override'} = 1;\n+\n+        $feature{'snapshot'}{'default'} = ['zip', 'tgz'];\n+        $feature{'snapshot'}{'override'} = 1;\n+\n+If you allow overriding for the snapshot feature, you can specify which\n+snapshot formats are globally disabled. You can also add any command line\n+options you want (such as setting the compression level). For instance, you\n+can disable Zip compressed snapshots and set *gzip*(1) to run at level 6 by\n+adding the following lines to your gitweb configuration file:\n+\n+        $known_snapshot_formats{'zip'}{'disabled'} = 1;\n+        $known_snapshot_formats{'tgz'}{'compressor'} = ['gzip','-6'];\n+\n+ENVIRONMENT\n+-----------\n+The location of per-instance and system-wide configuration files can be set\n+using the following environment variables:\n+\n+GITWEB_CONFIG::\n+\tSets location of per-instance configuration file.\n+GITWEB_CONFIG_SYSTEM::\n+\tSets location of fallback system-wide configuration file.\n+\tThis file is read only if per-instance one does not exist.\n+GITWEB_CONFIG_COMMON::\n+\tSets location of common system-wide configuration file.\n+\n+\n+FILES\n+-----\n+gitweb_config.perl::\n+\tThis is default value for per-instance configuration file.  The\n+\tformat of this file is described above.\n+/etc/gitweb.conf::\n+\tThis is default value for fallback system-wide configuration\n+\tfile.  This file is used only if per-instance configuration\n+\tvariable is not found.\n+/etc/gitweb-common.conf::\n+\tThis is default value for common system-wide configuration\n+\tfile.\n+\n+\n+SEE ALSO\n+--------\n+linkgit:gitweb[1], linkgit:git-instaweb[1]\n+\n+'gitweb/README', 'gitweb/INSTALL'\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/gitweb/README b/gitweb/README\nindex a998820..cf528d3 100644\n--- a/gitweb/README\n+++ b/gitweb/README\n@@ -41,139 +41,8 @@ Ultimate description on how to reconfigure the default features setting\n in your `GITWEB_CONFIG` or per-project in `project.git/config` can be found\n as comments inside 'gitweb.cgi'.\n \n-See also the \"Gitweb config file\" (with an example of config file), and\n-the \"Gitweb repositories\" sections in INSTALL file for gitweb.\n-\n-\n-The gitweb config file is a fragment of perl code. You can set variables\n-using \"our $variable = value\"; text from \"#\" character until the end\n-of a line is ignored. See perlsyn(1) man page for details.\n-\n-Below is the list of variables which you might want to set in gitweb config.\n-See the top of 'gitweb.cgi' for the full list of variables and their\n-descriptions.\n-\n-Gitweb config file variables\n-~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n-\n-You can set, among others, the following variables in gitweb config files\n-(with the exception of $projectroot and $projects_list this list does\n-not include variables usually directly set during build):\n- * $GIT\n-   Core git executable to use.  By default set to \"$GIT_BINDIR/git\", which\n-   in turn is by default set to \"$(bindir)/git\".  If you use git from binary\n-   package, set this to \"/usr/bin/git\".  This can just be \"git\" if your\n-   webserver has a sensible PATH.  If you have multiple git versions\n-   installed it can be used to choose which one to use.\n- * $version\n-   Gitweb version, set automatically when creating gitweb.cgi from\n-   gitweb.perl. You might want to modify it if you are running modified\n-   gitweb.\n- * $projectroot\n-   Absolute filesystem path which will be prepended to project path;\n-   the path to repository is $projectroot/$project.  Set to\n-   $GITWEB_PROJECTROOT during installation.  This variable have to be\n-   set correctly for gitweb to find repositories.\n- * $projects_list\n-   Source of projects list, either directory to scan, or text file\n-   with list of repositories (in the \"<URI-encoded repository path> SP\n-   <URI-encoded repository owner>\" line format; actually there can be\n-   any sequence of whitespace in place of space (SP)).  Set to\n-   $GITWEB_LIST during installation.  If empty, $projectroot is used\n-   to scan for repositories.\n- * $my_url, $my_uri\n-   Full URL and absolute URL of gitweb script;\n-   in earlier versions of gitweb you might have need to set those\n-   variables, now there should be no need to do it.  See\n-   $per_request_config if you need to set them still.\n- * $base_url\n-   Base URL for relative URLs in pages generated by gitweb,\n-   (e.g. $logo, $favicon, @stylesheets if they are relative URLs),\n-   needed and used only for URLs with nonempty PATH_INFO via\n-   <base href=\"$base_url\">.  Usually gitweb sets its value correctly,\n-   and there is no need to set this variable, e.g. to $my_uri or \"/\".\n-   See $per_request_config if you need to set it anyway.\n- * $home_link\n-   Target of the home link on top of all pages (the first part of view\n-   \"breadcrumbs\").  By default set to absolute URI of a page ($my_uri).\n- * @stylesheets\n-   List of URIs of stylesheets (relative to base URI of a page). You\n-   might specify more than one stylesheet, for example use gitweb.css\n-   as base, with site specific modifications in separate stylesheet\n-   to make it easier to upgrade gitweb. You can add 'site' stylesheet\n-   for example by using\n-      push @stylesheets, \"gitweb-site.css\";\n-   in the gitweb config file.\n- * $logo_url, $logo_label\n-   URI and label (title) of GIT logo link (or your site logo, if you choose\n-   to use different logo image). By default they point to git homepage;\n-   in the past they pointed to git documentation at www.kernel.org.\n- * $projects_list_description_width\n-   The width (in characters) of the projects list \"Description\" column.\n-   Longer descriptions will be cut (trying to cut at word boundary);\n-   full description is available as 'title' attribute (usually shown on\n-   mouseover).  By default set to 25, which might be too small if you\n-   use long project descriptions.\n- * $projects_list_group_categories\n-   Enables the grouping of projects by category on the project list page.\n-   The category of a project is determined by the $GIT_DIR/category\n-   file or the 'gitweb.category' variable in its repository configuration.\n-   Disabled by default.\n- * $project_list_default_category\n-   Default category for projects for which none is specified.  If set\n-   to the empty string, such projects will remain uncategorized and\n-   listed at the top, above categorized projects.\n- * @git_base_url_list\n-   List of git base URLs used for URL to where fetch project from, shown\n-   in project summary page.  Full URL is \"$git_base_url/$project\".\n-   You can setup multiple base URLs (for example one for  git:// protocol\n-   access, and one for http:// \"dumb\" protocol access).  Note that per\n-   repository configuration in 'cloneurl' file, or as values of gitweb.url\n-   project config.\n- * $default_blob_plain_mimetype\n-   Default mimetype for blob_plain (raw) view, if mimetype checking\n-   doesn't result in some other type; by default 'text/plain'.\n- * $default_text_plain_charset\n-   Default charset for text files. If not set, web server configuration\n-   would be used.\n- * $mimetypes_file\n-   File to use for (filename extension based) guessing of MIME types before\n-   trying /etc/mime.types. Path, if relative, is taken currently as\n-   relative to the current git repository.\n- * $fallback_encoding\n-   Gitweb assumes this charset if line contains non-UTF-8 characters.\n-   Fallback decoding is used without error checking, so it can be even\n-   'utf-8'. Value must be valid encoding; see Encoding::Supported(3pm) man\n-   page for a list.   By default 'latin1', aka. 'iso-8859-1'.\n- * @diff_opts\n-   Rename detection options for git-diff and git-diff-tree. By default\n-   ('-M'); set it to ('-C') or ('-C', '-C') to also detect copies, or\n-   set it to () if you don't want to have renames detection.\n- * $prevent_xss\n-   If true, some gitweb features are disabled to prevent content in\n-   repositories from launching cross-site scripting (XSS) attacks.  Set this\n-   to true if you don't trust the content of your repositories. The default\n-   is false.\n- * $maxload\n-   Used to set the maximum load that we will still respond to gitweb queries.\n-   If server load exceed this value then return \"503 Service Unavailable\" error.\n-   Server load is taken to be 0 if gitweb cannot determine its value.  Set it to\n-   undefined value to turn it off.  The default is 300.\n- * $highlight_bin\n-   Path to the highlight executable to use (must be the one from\n-   http://www.andre-simon.de due to assumptions about parameters and output).\n-   Useful if highlight is not installed on your webserver's PATH.\n-   [Default: highlight]\n- * $per_request_config\n-   If set to code reference, it would be run once per each request.  You can\n-   set parts of configuration that change per session, e.g. by setting it to\n-     sub { $ENV{GL_USER} = $cgi->remote_user || \"gitweb\"; }\n-   Otherwise it is treated as boolean value: if true gitweb would process\n-   config file once per request, if false it would process config file only\n-   once.  Note: $my_url, $my_uri, and $base_url are overwritten with\n-   their default values before every request, so if you want to change\n-   them, be sure to set this variable to true or a code reference effecting\n-   the desired changes.  The default is true.\n+See also gitweb.conf(5) manpage.\n+\n \n Projects list file format\n ~~~~~~~~~~~~~~~~~~~~~~~~~\n-- \n1.7.6\n"},{"id":"175717","messageId":"1316352884-26193-4-git-send-email-jnareb@gmail.com","threadId":"28418","inReplyTo":"1316352884-26193-1-git-send-email-jnareb@gmail.com","subject":"[PATCH/RFCv4 3/4] gitweb: Add manpage for gitweb","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2011-09-18T13:34:43Z","receivedAt":"2011-09-18T13:34:43Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Most of what is in gitweb.txt it has been pulled directly from the\nREADME and INSTALL files of gitweb.\n\nCurrent version is somewhat based on structure of SVN::Web manpage\n(one of web interfaces for Subversion).\n\ngitweb.conf(5) i.e. gitweb configuration manpage now refers to\nappropriate sections in gitweb(1).  gitweb/README now refers to\ngitweb/INSTALL and gitweb(1) manpage.  gitweb/INSTALL now refers to\ngitweb.conf(5) and gitweb(1).\n\nInspired-by: Drew Northup <drew.northup@maine.edu>\nSigned-off-by: Jakub Narebski <jnareb@gmail.com>\n---\nChanges from v3 version include:\n* Force URLs in SYNOPSIS into hyperlinks in HTML output\n* Fixed formatting of continued description list\n\n Documentation/Makefile        |    2 +-\n Documentation/gitweb.conf.txt |    8 +\n Documentation/gitweb.txt      |  703 +++++++++++++++++++++++++++++++++++++++++\n gitweb/INSTALL                |   96 +-----\n gitweb/README                 |  278 ++---------------\n 5 files changed, 741 insertions(+), 346 deletions(-)\n create mode 100644 Documentation/gitweb.txt\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 6d71943..aebab11 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -1,7 +1,7 @@\n MAN1_TXT= \\\n \t$(filter-out $(addsuffix .txt, $(ARTICLES) $(SP_ARTICLES)), \\\n \t\t$(wildcard git-*.txt)) \\\n-\tgitk.txt git.txt\n+\tgitk.txt gitweb.txt git.txt\n MAN5_TXT=gitattributes.txt gitignore.txt gitmodules.txt githooks.txt \\\n \tgitrepository-layout.txt gitweb.conf.txt\n MAN7_TXT=gitcli.txt gittutorial.txt gittutorial-2.txt \\\ndiff --git a/Documentation/gitweb.conf.txt b/Documentation/gitweb.conf.txt\nindex 2769302..1b276dd 100644\n--- a/Documentation/gitweb.conf.txt\n+++ b/Documentation/gitweb.conf.txt\n@@ -35,6 +35,10 @@ CGI script with the default name 'gitweb_config.perl' -- allowing\n one to have multiple gitweb instances with different configurations by\n the use of symlinks.\n \n+Note that some configuration can be controlled on per-repository rather than\n+gitweb-wide basis: see \"Per-repository gitweb configuration\" subsection on\n+linkgit:gitweb[1] manpage.\n+\n \n DISCUSSION\n ----------\n@@ -106,6 +110,8 @@ Location of repositories\n Configuration variables described below control finding git repositories by\n gitweb, and control display and access to repositories.\n \n+See also \"Repositories\" and later subsections in linkgit:gitweb[1] manpage.\n+\n $projectroot::\n \tAbsolute filesystem path which will be prepended to project path;\n \tthe path to repository is `$projectroot/$project`.  Set to\n@@ -172,6 +178,8 @@ though the above might be done by using `$export_ok` instead\n ----------------------------------------------------------------------------\n our $export_ok = \"git-daemon-export-ok\";\n ----------------------------------------------------------------------------\n+See also more involved example in \"Controlling access to git repositories\"\n+subsection on linkgit:gitweb[1] manpage.\n \n $strict_export::\n \tOnly allow viewing of repositories also shown on the overview page.\ndiff --git a/Documentation/gitweb.txt b/Documentation/gitweb.txt\nnew file mode 100644\nindex 0000000..4de6de3\n--- /dev/null\n+++ b/Documentation/gitweb.txt\n@@ -0,0 +1,703 @@\n+gitweb(1)\n+=========\n+\n+NAME\n+----\n+gitweb - Git web interface (web frontend to Git repositories)\n+\n+SYNOPSIS\n+--------\n+To get started with gitweb, run linkgit:git-instaweb[1] from a git repository.\n+This would configure and start your web server, and run web browser pointing to\n+gitweb page.\n+\n+See http://git.kernel.org/?p=git/git.git;a=tree;f=gitweb[] or\n+http://repo.or.cz/w/git.git/tree/HEAD:/gitweb/[] for gitweb source code,\n+browsed using gitweb itself.\n+\n+\n+DESCRIPTION\n+-----------\n+Gitweb provides a web interface to git repositories.  It's features include:\n+\n+* Viewing multiple Git repositories with common root.\n+* Browsing every revision of the repository.\n+* Viewing the contents of files in the repository at any revision.\n+* Viewing the revision log of branches, history of files and directories,\n+  see what was changed when, by who.\n+* Viewing the blame/annotation details of any file (if enabled).\n+* Generating RSS and Atom feeds of commits, for any branch.\n+  The feeds are auto-discoverable in modern web browsers.\n+* Viewing everything that was changed in a revision, and step through\n+  revisions one at a time, viewing the history of the repository.\n+* Finding commits which commit messages matches given search term.\n+\n+CONFIGURATION\n+-------------\n+Various aspects of gitweb's behavior can be controlled through the configuration\n+file 'gitweb_config.perl' or '/etc/gitweb.conf'.  See the linkgit:gitweb.conf[5]\n+for details.\n+\n+Repositories\n+~~~~~~~~~~~~\n+Gitweb can show information from one or more Git repositories.  These\n+repositories have to be all on local filesystem, and have to share common\n+repository root, i.e. be all under a single parent repository (but see also\n+\"Advanced web server setup\" section, \"Webserver configuration with multiple\n+projects' root\" subsection).\n+\n+-----------------------------------------------------------------------\n+our $projectroot = '/path/to/parent/directory';\n+-----------------------------------------------------------------------\n+\n+The default value for `$projectroot` is '/pub/git'.  You can change it during\n+building gitweb via `GITWEB_PROJECTROOT` build configuration variable.\n+\n+By default all git repositories under `$projectroot` are visible and available\n+to gitweb.  The list of projects is generated by default by scanning the\n+`$projectroot` directory for git repositories (for object databases to be\n+more exact; gitweb is not interested in a working area, and is best suited\n+to showing \"bare\" repositories).\n+\n+The name of repository in gitweb is path to it's `$GIT_DIR` (it's object\n+database) relative to `$projectroot`.  Therefore the repository $repo can be\n+found at \"$projectroot/$repo\".\n+\n+\n+Projects list file format\n+~~~~~~~~~~~~~~~~~~~~~~~~~\n+Instead of having gitweb find repositories by scanning filesystem\n+starting from $projectroot, you can provide a pre-generated list of\n+visible projects by setting `$projects_list` to point to a plain text\n+file with a list of projects (with some additional info).\n+\n+This file uses the following format:\n+\n+* One record (for project / repository) per line; does not support line\n+continuation (newline escaping).\n+\n+* Leading and trailing whitespace are ignored.\n+\n+* Whitespace separated fields; any run of whitespace can be used as field\n+separator (rules for Perl's \"`split(\" \", $line)`\").\n+\n+* Fields use modified URI encoding, defined in RFC 3986, section 2.1\n+(Percent-Encoding), or rather \"Query string encoding\" (see\n+link:http://en.wikipedia.org/wiki/Query_string#URL_encoding[]), the difference\n+being that SP (\" \") can be encoded as \"{plus}\" (and therefore \"{plus}\" has to be\n+also percent-encoded).\n++\n+Reserved characters are: \"%\" (used for encoding), \"{plus}\" (can be used to\n+encode SPACE), all whitespace characters as defined in Perl, including SP,\n+TAB and LF, (used to separate fields in a record).\n+\n+* Currently recognized fields are:\n+<repository path>::\n+\tpath to repository GIT_DIR, relative to `$projectroot`\n+<repository owner>::\n+\tdisplayed as repository owner, preferably full name, or email,\n+\tor both\n+\n+You can generate the projects list index file using the project_index action\n+(the 'TXT' link on projects list page) directly from gitweb; see also\n+\"Generating projects list using gitweb\" section below.\n+\n+Example contents:\n+-----------------------------------------------------------------------\n+foo.git       Joe+R+Hacker+<joe@example.com>\n+foo/bar.git   O+W+Ner+<owner@example.org>\n+-----------------------------------------------------------------------\n+\n+\n+By default this file controls only which projects are *visible* on projects\n+list page (note that entries that do not point to correctly recognized git\n+repositories won't be displayed by gitweb).  Even if a project is not\n+visible on projects list page, you can view it nevertheless by hand-crafting\n+a gitweb URL.  By setting `$strict_export` configuration variable (see\n+linkgit:gitweb.conf[5]) to true value you can allow viewing only of\n+repositories also shown on the overview page (i.e. only projects explicitely\n+listed in projects list file will be accessible).\n+\n+\n+Generating projects list using gitweb\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+We assume that GITWEB_CONFIG has its default Makefile value, namely\n+'gitweb_config.perl'. Put the following in 'gitweb_make_index.perl' file:\n+----------------------------------------------------------------------------\n+read_config_file(\"gitweb_config.perl\");\n+$projects_list = $projectroot;\n+----------------------------------------------------------------------------\n+\n+Then create the following script to get list of project in the format\n+suitable for GITWEB_LIST build configuration variable (or\n+`$projects_list` variable in gitweb config):\n+\n+----------------------------------------------------------------------------\n+#!/bin/sh\n+\n+export GITWEB_CONFIG=\"gitweb_make_index.perl\"\n+export GATEWAY_INTERFACE=\"CGI/1.1\"\n+export HTTP_ACCEPT=\"*/*\"\n+export REQUEST_METHOD=\"GET\"\n+export QUERY_STRING=\"a=project_index\"\n+\n+perl -- /var/www/cgi-bin/gitweb.cgi\n+----------------------------------------------------------------------------\n+\n+Run this script and save its output to a file.  This file could then be used\n+as projects list file, which means that you can set `$projects_list` to its\n+filename.\n+\n+\n+Controlling access to git repositories\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+By default all git repositories under `$projectroot` are visible and\n+available to gitweb.  You can however configure how gitweb controls access\n+to repositories.\n+\n+* As described in \"Projects list file format\" section, you can control which\n+projects are *visible* by selectively including repositories in projects\n+list file, and setting `$projects_list` gitweb configuration variable to\n+point to it.  With `$strict_export` set, projects list file can be used to\n+control which repositories are *available* as well.\n+\n+* You can configure gitweb to only list and allow viewing of the explicitly\n+exported repositories, via `$export_ok` variable in gitweb config file; see\n+linkgit:gitweb.conf[5] manpage.  If it evaluates to true, gitweb shows\n+repositories only if this file named by `$export_ok` exists in its object\n+database (if directory has the magic file named `$export_ok`).\n++\n+For example linkgit:git-daemon[1] by default (unless `--export-all` option\n+is used) allows pulling only for those repositories that have\n+'git-daemon-export-ok' file.  Adding\n++\n+--------------------------------------------------------------------------\n+our $export_ok = \"git-daemon-export-ok\";\n+--------------------------------------------------------------------------\n++\n+makes gitweb show and allow access only to those repositories that can be\n+fetched from via `git://` protocol.\n+\n+* Finally, it is possible to specify an arbitrary perl subroutine that will\n+be called for each repository to determine if it can be exported.  The\n+subroutine receives an absolute path to the project (repository) as its only\n+parameter (i.e. \"$projectroot/$project\").\n++\n+For example, if you use mod_perl to run the script, and have dumb\n+http protocol authentication configured for your repositories, you\n+can use the following hook to allow access only if the user is\n+authorized to read the files:\n++\n+--------------------------------------------------------------------------\n+$export_auth_hook = sub {\n+\tuse Apache2::SubRequest ();\n+\tuse Apache2::Const -compile => qw(HTTP_OK);\n+\tmy $path = \"$_[0]/HEAD\";\n+\tmy $r    = Apache2::RequestUtil->request;\n+\tmy $sub  = $r->lookup_file($path);\n+\treturn $sub->filename eq $path\n+\t    && $sub->status == Apache2::Const::HTTP_OK;\n+};\n+--------------------------------------------------------------------------\n+\n+\n+Per-repository gitweb configuration\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+You can configure individual repositories shown in gitweb by creating file\n+in the 'GIT_DIR' of git repository, or by setting some repo configuration\n+variable (in 'GIT_DIR/config', see linkgit:git-config[1]).\n+\n+You can use the following files in repository:\n+\n+README.html::\n+\tA html file (HTML fragment) which is included on the gitweb project\n+\t\"summary\" page inside `<div>` block element. You can use it for longer\n+\tdescription of a project, to provide links (for example to project's\n+\thomepage), etc. This is recognized only if XSS prevention is off\n+\t(`$prevent_xss` is false, see linkgit:gitweb.conf[5]); a way to include\n+\ta README safely when XSS prevention is on may be worked out in the\n+\tfuture.\n+\n+description (or `gitweb.description`)::\n+\tShort (shortened to `$projects_list_description_width` in the projects\n+\tlist page, which is 25 characters by default; see\n+\tlinkgit:gitweb.conf[5]) single line description of a project (of a\n+\trepository).  Plain text file; HTML will be escaped.  By default set to\n++\n+-------------------------------------------------------------------------------\n+Unnamed repository; edit this file to name it for gitweb.\n+-------------------------------------------------------------------------------\n++\n+from the template during repository creation, usually installed in\n+'/usr/share/git-core/templates/'.  You can use the `gitweb.description` repo\n+configuration variable, but the file takes precedence.\n+\n+category (or `gitweb.category`)::\n+\tSinge line category of a project, used to group projects if\n+\t`$projects_list_group_categories` is enabled.  By default (file and\n+\tconfiguration variable absent), uncategorized projects are put in the\n+\t`$project_list_default_category` category.  You can use the\n+\t`gitweb.category` repo configuration variable, but the file takes\n+\tprecedence.\n++\n+The configuration variables `$projects_list_group_categories` and\n+`$project_list_default_category` are described in linkgit:gitweb.conf[5]\n+\n+cloneurl (or multiple-valued `gitweb.url`)::\n+\tFile with repository URL (used for clone and fetch), one per line.\n+\tDisplayed in the project summary page. You can use multiple-valued\n+\t`gitweb.url` repository configuration variable for that, but the file\n+\ttakes precedence.\n++\n+This is per-repository enhancement / version of global prefix-based\n+`@git_base_url_list` gitweb configuration variable (see\n+linkgit:gitweb.conf[5]).\n+\n+gitweb.owner::\n+\tYou can use the `gitweb.owner` repository configuration variable to set\n+\trepository's owner.  It is displayed in the project list and summary\n+\tpage.\n++\n+If it's not set, filesystem directory's owner is used (via GECOS field,\n+i.e. real name field from *getpwuid*(3)) if `$projects_list` is unset\n+(gitweb scans `$projectroot` for repositories); if `$projects_list`\n+points to file with list of repositories, then project owner defaults to\n+value from this file for given repository.\n+\n+various `gitweb.*` config variables (in config)::\n+\tRead description of `%feature` hash for detailed list, and descriptions.\n+\tSee also \"Configuring gitweb features\" section in linkgit:gitweb.conf[5]\n+\n+\n+ACTIONS, AND URLS\n+-----------------\n+Gitweb can use path_info (component) based URLs, or it can pass all necessary\n+information via query parameters.  The typical gitweb URLs are broken down in to\n+five components:\n+\n+-----------------------------------------------------------------------\n+.../gitweb.cgi/<repo>/<action>/<revision>:/<path>?<arguments>\n+-----------------------------------------------------------------------\n+\n+repo::\n+\tThe repository the action will be performed on.\n++\n+All actions except for those that list all available projects,\n+in whatever form, require this parameter.\n+\n+action::\n+\tThe action that will be run.  Defaults to 'projects_list' if repo\n+\tis not set, and to 'summary' otherwise.\n+\n+revision::\n+\tRevision shown.  Defaults to HEAD.\n+\n+path::\n+\tThe path within the <repository> that the action is performed on,\n+\tfor those actions that require it.\n+\n+arguments::\n+\tAny arguments that control the behaviour of the action.\n+\n+Some actions require or allow to specify two revisions, and sometimes even two\n+pathnames.  In most general form such path_info (component) based gitweb URL\n+looks like this:\n+\n+-----------------------------------------------------------------------\n+.../gitweb.cgi/<repo>/<action>/<revision_from>:/<path_from>..<revision_to>:/<path_to>?<arguments>\n+-----------------------------------------------------------------------\n+\n+\n+Each action is implemented as a subroutine, and must be present in %actions\n+hash.  Some actions are disabled by default, and must be turned on via feature\n+mechanism.  For example to enable 'blame' view add the following to gitweb\n+configuration file:\n+\n+-----------------------------------------------------------------------\n+$feature{'blame'}{'default'} = [1];\n+-----------------------------------------------------------------------\n+\n+\n+Actions:\n+~~~~~~~~\n+The standard actions are:\n+\n+project_list::\n+\tLists the available Git repositories.  This is the default command if no\n+\trepository is specified in the URL.\n+\n+summary::\n+\tDisplays summary about given repository.  This is the default command if\n+\tno action is specified in URL, and only repository is specified.\n+\n+heads::\n+remotes::\n+\tLists all local or all remote-tracking branches in given repository.\n++\n+The latter is not available by default, unless configured.\n+\n+tags::\n+\tList all tags (lightweight and annotated) in given repository.\n+\n+blob::\n+tree::\n+\tShows the files and directories in a given repository path, at given\n+\trevision.  This is default command if no action is specified in the URL,\n+\tand path is given.\n+\n+blob_plain::\n+\tReturns the raw data for the file in given repository, at given path and\n+\trevision.  Links to this action are marked 'raw'.\n+\n+blobdiff::\n+\tShows the difference between two revisions of the same file.\n+\n+blame::\n+blame_incremental::\n+\tShows the blame (also called annotation) information for a file. On a\n+\tper line basis it shows the revision in which that line was last changed\n+\tand the user that committed the change.  The incremental version (which\n+\tif configured is used automatically when JavaScript is enabled) uses\n+\tAjax to incrementally add blame info to the contents of given file.\n++\n+This action is disabled by default for performance reasons.\n+\n+commit::\n+commitdiff::\n+\tShows information about a specific commit in a repository.  The 'commit'\n+\tview shows information about commit in more detail, the 'commitdiff'\n+\taction shows changeset for given commit.\n+\n+patch:: \n+\tReturns the commit in plain text mail format, suitable for applying with\n+\tlinkgit:git-am[1].\n+\n+tag::\n+\tDisplay specific annotated tag (tag object).\t\n+\n+log::\n+shortlog::\n+\tShows log information (commit message or just commit subject) for a\n+\tgiven branch (starting from given revision).\n++\n+The 'shortlog' view is more compact; it shows one commit per line.\n+\n+history::\n+\tShows history of the file or directory in a given repository path,\n+\tstarting from given revision (defaults to HEAD, i.e. default branch).\n++\n+This view is similar to 'shortlog' view.\n+\n+rss::\n+atom::\n+\tGenerates an RSS (or Atom) feed of changes to repository.\n+\n+\n+WEBSERVER CONFIGURATION\n+-----------------------\n+This section explains how to configure some common webservers to run gitweb. In\n+all cases, `/path/to/gitweb` in the examples is the directory you ran installed\n+gitweb in, and contains `gitweb_config.perl`.\n+\n+If you've configured a web server that isn't listed here for gitweb, please send\n+in the instructions so they can be included in a future release.\n+\n+Apache as CGI\n+~~~~~~~~~~~~~\n+Apache must be configured to support CGI scripts in the directory in\n+which gitweb is installed.  Let's assume that it is '/var/www/cgi-bin'\n+directory.\n+\n+-----------------------------------------------------------------------\n+ScriptAlias /cgi-bin/ \"/var/www/cgi-bin/\"\n+\n+<Directory \"/var/www/cgi-bin\">\n+    Options Indexes FollowSymlinks ExecCGI\n+    AllowOverride None\n+    Order allow,deny\n+    Allow from all\n+</Directory>\n+-----------------------------------------------------------------------\n+\n+With that configuration the full path to browse repositories would be:\n+\n+  http://server/cgi-bin/gitweb.cgi\n+\n+Apache with mod_perl, via ModPerl::Registry\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+You can use mod_perl with gitweb.  You must install Apache::Registry\n+(for mod_perl 1.x) or ModPerl::Registry (for mod_perl 2.x) to enable\n+this support.\n+\n+Assuming that gitweb is installed to '/var/www/perl', the following\n+Apache configuration (for mod_perl 2.x) is suitable.\n+\n+-----------------------------------------------------------------------\n+Alias /perl \"/var/www/perl\"\n+\n+<Directory \"/var/www/perl\">\n+    SetHandler perl-script\n+    PerlResponseHandler ModPerl::Registry\n+    PerlOptions +ParseHeaders\n+    Options Indexes FollowSymlinks +ExecCGI\n+    AllowOverride None\n+    Order allow,deny\n+    Allow from all\n+</Directory>\n+-----------------------------------------------------------------------\n+\n+With that configuration the full path to browse repositories would be:\n+\n+  http://server/perl/gitweb.cgi\n+\n+Apache with FastCGI\n+~~~~~~~~~~~~~~~~~~~\n+Gitweb works with Apache and FastCGI.  First you need to rename, copy\n+or symlink gitweb.cgi to gitweb.fcgi.  Let's assume that gitweb is\n+installed in '/usr/share/gitweb' directory.  The following Apache\n+configuration is suitable (UNTESTED!)\n+\n+-----------------------------------------------------------------------\n+FastCgiServer /usr/share/gitweb/gitweb.cgi\n+ScriptAlias /gitweb /usr/share/gitweb/gitweb.cgi\n+\n+Alias /gitweb/static /usr/share/gitweb/static\n+<Directory /usr/share/gitweb/static>\n+    SetHandler default-handler\n+</Directory>\n+-----------------------------------------------------------------------\n+\n+With that configuration the full path to browse repositories would be:\n+\n+  http://server/gitweb\n+\n+\n+ADVANCED WEB SERVER SETUP\n+-------------------------\n+All of those examples use request rewriting, and need `mod_rewrite`\n+(or equivalent; examples below are written for Apache).\n+\n+Single URL for gitweb and for fetching\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+If you want to have one URL for both gitweb and your `http://`\n+repositories, you can configure Apache like this:\n+\n+-----------------------------------------------------------------------\n+<VirtualHost *:80>\n+    ServerName    git.example.org\n+    DocumentRoot  /pub/git\n+    SetEnv        GITWEB_CONFIG   /etc/gitweb.conf\n+\n+    # turning on mod rewrite\n+    RewriteEngine on\n+\n+    # make the front page an internal rewrite to the gitweb script\n+    RewriteRule ^/$  /cgi-bin/gitweb.cgi\n+\n+    # make access for \"dumb clients\" work\n+    RewriteRule ^/(.*\\.git/(?!/?(HEAD|info|objects|refs)).*)?$ \\\n+                /cgi-bin/gitweb.cgi%{REQUEST_URI}  [L,PT]\n+</VirtualHost>\n+-----------------------------------------------------------------------\n+\n+The above configuration expects your public repositories to live under\n+'/pub/git' and will serve them as `http://git.domain.org/dir-under-pub-git`,\n+both as cloneable GIT URL and as browseable gitweb interface.  If you then\n+start your linkgit:git-daemon[1] with `--base-path=/pub/git --export-all`\n+then you can even use the `git://` URL with exactly the same path.\n+\n+Setting the environment variable `GITWEB_CONFIG` will tell gitweb to use the\n+named file (i.e. in this example '/etc/gitweb.conf') as a configuration for\n+gitweb.  You don't really need it in above example; it is required only if\n+your configuration file is in different place than built-in (during\n+compiling gitweb) 'gitweb_config.perl' or '/etc/gitweb.conf'.  See\n+linkgit:gitweb.conf[5] for details, especially information about precedence\n+rules.\n+\n+If you use the rewrite rules from the example you *might* also need\n+something like the following in your gitweb configuration file\n+('/etc/gitweb.conf' following example):\n+----------------------------------------------------------------------------\n+@stylesheets = (\"/some/absolute/path/gitweb.css\");\n+$my_uri    = \"/\";\n+$home_link = \"/\";\n+$per_request_config = 1;\n+----------------------------------------------------------------------------\n+Nowadays though gitweb should create HTML base tag when needed (to set base\n+URI for relative links), so it should work automatically.\n+\n+\n+Webserver configuration with multiple projects' root\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+If you want to use gitweb with several project roots you can edit your\n+Apache virtual host and gitweb configuration files in the following way.\n+\n+The virtual host configuration (in Apache configuration file) should look\n+like this:\n+--------------------------------------------------------------------------\n+<VirtualHost *:80>\n+    ServerName    git.example.org\n+    DocumentRoot  /pub/git\n+    SetEnv        GITWEB_CONFIG  /etc/gitweb.conf\n+\n+    # turning on mod rewrite\n+    RewriteEngine on\n+\n+    # make the front page an internal rewrite to the gitweb script\n+    RewriteRule ^/$  /cgi-bin/gitweb.cgi  [QSA,L,PT]\n+\n+    # look for a public_git folder in unix users' home\n+    # http://git.example.org/~<user>/\n+    RewriteRule ^/\\~([^\\/]+)(/|/gitweb.cgi)?$\t/cgi-bin/gitweb.cgi \\\n+                [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT]\n+\n+    # http://git.example.org/+<user>/\n+    #RewriteRule ^/\\+([^\\/]+)(/|/gitweb.cgi)?$\t/cgi-bin/gitweb.cgi \\\n+                 [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT]\n+\n+    # http://git.example.org/user/<user>/\n+    #RewriteRule ^/user/([^\\/]+)/(gitweb.cgi)?$\t/cgi-bin/gitweb.cgi \\\n+                 [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT]\n+\n+    # defined list of project roots\n+    RewriteRule ^/scm(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi \\\n+                [QSA,E=GITWEB_PROJECTROOT:/pub/scm/,L,PT]\n+    RewriteRule ^/var(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi \\\n+                [QSA,E=GITWEB_PROJECTROOT:/var/git/,L,PT]\n+\n+    # make access for \"dumb clients\" work\n+    RewriteRule ^/(.*\\.git/(?!/?(HEAD|info|objects|refs)).*)?$ \\\n+                /cgi-bin/gitweb.cgi%{REQUEST_URI}  [L,PT]\n+</VirtualHost>\n+--------------------------------------------------------------------------\n+\n+Here actual project root is passed to gitweb via `GITWEB_PROJECT_ROOT`\n+environment variable from a web server, so you need to put the following\n+line in gitweb configuration file ('/etc/gitweb.conf' in above example):\n+--------------------------------------------------------------------------\n+$projectroot = $ENV{'GITWEB_PROJECTROOT'} || \"/pub/git\";\n+--------------------------------------------------------------------------\n+*Note* that this requires to be set for each request, so either\n+`$per_request_config` must be false, or the above must be put in code\n+referenced by `$per_request_config`;\n+\n+These configurations enable two things. First, each unix user (`<user>`) of\n+the server will be able to browse through gitweb git repositories found in\n+'~/public_git/' with the following url:\n+\n+  http://git.example.org/~<user>/\n+\n+If you do not want this feature on your server just remove the second\n+rewrite rule.\n+\n+If you already use `mod_userdir` in your virtual host or you don't want to\n+use the \\'~' as first character, just comment or remove the second rewrite\n+rule, and uncomment one of the following according to what you want.\n+\n+Second, repositories found in '/pub/scm/' and '/var/git/' will be accesible\n+through `http://git.example.org/scm/` and `http://git.example.org/var/`.\n+You can add as many project roots as you want by adding rewrite rules like\n+the third and the fourth.\n+\n+\n+PATH_INFO usage\n+~~~~~~~~~~~~~~~\n+If you enable PATH_INFO usage in gitweb by putting\n+----------------------------------------------------------------------------\n+$feature{'pathinfo'}{'default'} = [1];\n+----------------------------------------------------------------------------\n+in your gitweb configuration file, it is possible to set up your server so\n+that it consumes and produces URLs in the form\n+\n+  http://git.example.com/project.git/shortlog/sometag\n+\n+i.e. without 'gitweb.cgi' part, by using a configuration such as the\n+following.  This configuration assumes that '/var/www/gitweb' is the\n+DocumentRoot of your webserver, contains the gitweb.cgi script and\n+complementary static files (stylesheet, favicon, JavaScript):\n+\n+----------------------------------------------------------------------------\n+<VirtualHost *:80>\n+\tServerAlias git.example.com\n+\n+\tDocumentRoot /var/www/gitweb\n+\n+\t<Directory /var/www/gitweb>\n+\t\tOptions ExecCGI\n+\t\tAddHandler cgi-script cgi\n+\n+\t\tDirectoryIndex gitweb.cgi\n+\n+\t\tRewriteEngine On\n+\t\tRewriteCond %{REQUEST_FILENAME} !-f\n+\t\tRewriteCond %{REQUEST_FILENAME} !-d\n+\t\tRewriteRule ^.* /gitweb.cgi/$0 [L,PT]\n+\t</Directory>\n+</VirtualHost>\n+----------------------------------------------------------------------------\n+The rewrite rule guarantees that existing static files will be properly\n+served, whereas any other URL will be passed to gitweb as PATH_INFO\n+parameter.\n+\n+*Notice* that in this case you don't need special settings for\n+`@stylesheets`, `$my_uri` and `$home_link`, but you lose \"dumb client\"\n+access to your project .git dirs (described in \"Single URL for gitweb and\n+for fetching\" section).  A possible workaround for the latter is the\n+following: in your project root dir (e.g. '/pub/git') have the projects\n+named *without* a .git extension (e.g. '/pub/git/project' instead of\n+'/pub/git/project.git') and configure Apache as follows:\n+----------------------------------------------------------------------------\n+<VirtualHost *:80>\n+\tServerAlias git.example.com\n+\n+\tDocumentRoot /var/www/gitweb\n+\n+\tAliasMatch ^(/.*?)(\\.git)(/.*)?$ /pub/git$1$3\n+\t<Directory /var/www/gitweb>\n+\t\tOptions ExecCGI\n+\t\tAddHandler cgi-script cgi\n+\n+\t\tDirectoryIndex gitweb.cgi\n+\n+\t\tRewriteEngine On\n+\t\tRewriteCond %{REQUEST_FILENAME} !-f\n+\t\tRewriteCond %{REQUEST_FILENAME} !-d\n+\t\tRewriteRule ^.* /gitweb.cgi/$0 [L,PT]\n+\t</Directory>\n+</VirtualHost>\n+----------------------------------------------------------------------------\n+\n+The additional AliasMatch makes it so that\n+\n+  http://git.example.com/project.git\n+\n+will give raw access to the project's git dir (so that the project can be\n+cloned), while\n+\n+  http://git.example.com/project\n+\n+will provide human-friendly gitweb access.\n+\n+This solution is not 100% bulletproof, in the sense that if some project has\n+a named ref (branch, tag) starting with 'git/', then paths such as\n+\n+  http://git.example.com/project/command/abranch..git/abranch\n+\n+will fail with a 404 error.\n+\n+\n+BUGS\n+----\n+Please report any bugs or feature requests to git@vger.kernel.org,\n+putting \"gitweb\" in the subject of email.\n+\n+SEE ALSO\n+--------\n+linkgit:gitweb.conf[5], linkgit:git-instaweb[1]\n+\n+'gitweb/README', 'gitweb/INSTALL'\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/gitweb/INSTALL b/gitweb/INSTALL\nindex f5efe74..d134ffe 100644\n--- a/gitweb/INSTALL\n+++ b/gitweb/INSTALL\n@@ -229,7 +229,7 @@ Gitweb config file\n ------------------\n \n See also \"Runtime gitweb configuration\" section in README file\n-for gitweb (in gitweb/README).\n+for gitweb (in gitweb/README), and gitweb.conf(5) manpage.\n \n - You can configure gitweb further using the per-instance gitweb configuration file;\n   by default this is a file named gitweb_config.perl in the same place as\n@@ -287,97 +287,19 @@ adding the following lines to your $GITWEB_CONFIG:\n Gitweb repositories\n -------------------\n \n-- By default all git repositories under projectroot are visible and\n-  available to gitweb. The list of projects is generated by default by\n-  scanning the projectroot directory for git repositories (for object\n-  databases to be more exact).\n-\n-  You can provide a pre-generated list of [visible] repositories,\n-  together with information about their owners (the project ownership\n-  defaults to the owner of the repository directory otherwise), by setting\n-  the GITWEB_LIST build configuration variable (or the $projects_list\n-  variable in the gitweb config file) to point to a plain file.\n-\n-  Each line of the projects list file should consist of the url-encoded path\n-  to the project repository database (relative to projectroot), followed\n-  by the url-encoded project owner on the same line (separated by a space).\n-  Spaces in both project path and project owner have to be encoded as either\n-  '%20' or '+'.\n-\n-  Other characters that have to be url-encoded, i.e. replaced by '%'\n-  followed by two-digit character number in octal, are: other whitespace\n-  characters (because they are field separator in a record), plus sign '+'\n-  (because it can be used as replacement for spaces), and percent sign '%'\n-  (which is used for encoding / escaping).\n-\n-  You can generate the projects list index file using the project_index\n-  action (the 'TXT' link on projects list page) directly from gitweb.\n-\n-- By default, even if a project is not visible on projects list page, you\n-  can view it nevertheless by hand-crafting a gitweb URL. You can set the\n-  GITWEB_STRICT_EXPORT build configuration variable (or the $strict_export\n-  variable in the gitweb config file) to only allow viewing of\n-  repositories also shown on the overview page.\n-\n-- Alternatively, you can configure gitweb to only list and allow\n-  viewing of the explicitly exported repositories, via the\n-  GITWEB_EXPORT_OK build configuration variable (or the $export_ok\n-  variable in gitweb config file). If it evaluates to true, gitweb\n-  shows repositories only if this file exists in its object database\n-  (if directory has the magic file named $export_ok).\n-\n-- Finally, it is possible to specify an arbitrary perl subroutine that\n-  will be called for each project to determine if it can be exported.\n-  The subroutine receives an absolute path to the project as its only\n-  parameter.\n-\n-  For example, if you use mod_perl to run the script, and have dumb\n-  http protocol authentication configured for your repositories, you\n-  can use the following hook to allow access only if the user is\n-  authorized to read the files:\n-\n-    $export_auth_hook = sub {\n-        use Apache2::SubRequest ();\n-        use Apache2::Const -compile => qw(HTTP_OK);\n-        my $path = \"$_[0]/HEAD\";\n-        my $r    = Apache2::RequestUtil->request;\n-        my $sub  = $r->lookup_file($path);\n-        return $sub->filename eq $path\n-            && $sub->status == Apache2::Const::HTTP_OK;\n-    };\n-\n-\n-Generating projects list using gitweb\n-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n-\n-We assume that GITWEB_CONFIG has its default Makefile value, namely\n-gitweb_config.perl. Put the following in gitweb_make_index.perl file:\n-\n-\t$GITWEB_CONFIG = \"gitweb_config.perl\";\n-\tdo $GITWEB_CONFIG if -e $GITWEB_CONFIG;\n-\n-\t$projects_list = $projectroot;\n-\n-Then create the following script to get list of project in the format\n-suitable for GITWEB_LIST build configuration variable (or\n-$projects_list variable in gitweb config):\n-\n-\t#!/bin/sh\n-\n-\texport GITWEB_CONFIG=\"gitweb_make_index.perl\"\n-\texport GATEWAY_INTERFACE=\"CGI/1.1\"\n-\texport HTTP_ACCEPT=\"*/*\"\n-\texport REQUEST_METHOD=\"GET\"\n-\texport QUERY_STRING=\"a=project_index\"\n-\n-\tperl -- /var/www/cgi-bin/gitweb.cgi\n+By default gitweb shows all git repositories under single common repository\n+root on a local filesystem; see description of GITWEB_PROJECTROOT build-time\n+configuration variable above (and also of GITWEB_LIST).\n+\n+More advanced usage, like limiting access or visibility of repositories and\n+managing multiple roots are described on gitweb manpage.\n \n \n Example web server configuration\n ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n \n-See also \"Webserver configuration\" section in README file for gitweb\n-(in gitweb/README).\n+See also \"Webserver configuration\" and \"Advanced web server setup\" sections\n+in gitweb(1) manpage.\n \n \n - Apache2, gitweb installed as CGI script,\ndiff --git a/gitweb/README b/gitweb/README\nindex cf528d3..6da4778 100644\n--- a/gitweb/README\n+++ b/gitweb/README\n@@ -7,9 +7,18 @@ The one working on:\n From the git version 1.4.0 gitweb is bundled with git.\n \n \n+Build time gitweb configuration\n+-------------------------------\n+There are many configuration variables which affect building gitweb (among\n+others creating gitweb.cgi out of gitweb.perl by replacing placeholders such\n+as `++GIT_BINDIR++` by their build-time values).\n+\n+Building and installing gitweb is described in gitweb's INSTALL file\n+(in 'gitweb/INSTALL').\n+\n+\n Runtime gitweb configuration\n ----------------------------\n-\n Gitweb obtains configuration data from the following sources in the\n following order:\n \n@@ -44,266 +53,19 @@ as comments inside 'gitweb.cgi'.\n See also gitweb.conf(5) manpage.\n \n \n-Projects list file format\n-~~~~~~~~~~~~~~~~~~~~~~~~~\n-\n-Instead of having gitweb find repositories by scanning filesystem starting\n-from $projectroot (or $projects_list, if it points to directory), you can\n-provide list of projects by setting $projects_list to a text file with list\n-of projects (and some additional info).  This file uses the following\n-format:\n-\n-One record (for project / repository) per line, whitespace separated fields;\n-does not support (at least for now) lines continuation (newline escaping).\n-Leading and trailing whitespace are ignored, any run of whitespace can be\n-used as field separator (rules for Perl's \"split(' ', $line)\").  Keyed by\n-the first field, which is project name, i.e. path to repository GIT_DIR\n-relative to $projectroot.  Fields use modified URI encoding, defined in\n-RFC 3986, section 2.1 (Percent-Encoding), or rather \"Query string encoding\"\n-(see http://en.wikipedia.org/wiki/Query_string#URL_encoding), the difference\n-being that SP (' ') can be encoded as '+' (and therefore '+' has to be also\n-percent-encoded).  Reserved characters are: '%' (used for encoding), '+'\n-(can be used to encode SPACE), all whitespace characters as defined in Perl,\n-including SP, TAB and LF, (used to separate fields in a record).\n-\n-Currently list of fields is\n- * <repository path>  - path to repository GIT_DIR, relative to $projectroot\n- * <repository owner> - displayed as repository owner, preferably full name,\n-                        or email, or both\n-\n-You can additionally use $projects_list file to limit which repositories\n-are visible, and together with $strict_export to limit access to\n-repositories (see \"Gitweb repositories\" section in gitweb/INSTALL).\n-\n-\n-Per-repository gitweb configuration\n-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n-\n-You can also configure individual repositories shown in gitweb by creating\n-file in the GIT_DIR of git repository, or by setting some repo configuration\n-variable (in GIT_DIR/config).\n-\n-You can use the following files in repository:\n- * README.html\n-   A .html file (HTML fragment) which is included on the gitweb project\n-   summary page inside <div> block element. You can use it for longer\n-   description of a project, to provide links (for example to project's\n-   homepage), etc. This is recognized only if XSS prevention is off\n-   ($prevent_xss is false); a way to include a readme safely when XSS\n-   prevention is on may be worked out in the future.\n- * description (or gitweb.description)\n-   Short (shortened by default to 25 characters in the projects list page)\n-   single line description of a project (of a repository). Plain text file;\n-   HTML will be escaped. By default set to\n-     Unnamed repository; edit this file to name it for gitweb.\n-   from the template during repository creation. You can use the\n-   gitweb.description repo configuration variable, but the file takes\n-   precedence.\n- * category (or gitweb.category)\n-   Singe line category of a project, used to group projects if\n-   $projects_list_group_categories is enabled. By default (file and\n-   configuration variable absent), uncategorized projects are put in\n-   the $project_list_default_category category. You can use the\n-   gitweb.category repo configuration variable, but the file takes\n-   precedence.\n- * cloneurl (or multiple-valued gitweb.url)\n-   File with repository URL (used for clone and fetch), one per line.\n-   Displayed in the project summary page. You can use multiple-valued\n-   gitweb.url repository configuration variable for that, but the file\n-   takes precedence.\n- * gitweb.owner\n-   You can use the gitweb.owner repository configuration variable to set\n-   repository's owner. It is displayed in the project list and summary\n-   page. If it's not set, filesystem directory's owner is used\n-   (via GECOS field / real name field from getpwiud(3)).\n- * various gitweb.* config variables (in config)\n-   Read description of %feature hash for detailed list, and some\n-   descriptions.\n-\n-\n-Webserver configuration\n------------------------\n-\n-If you want to have one URL for both gitweb and your http://\n-repositories, you can configure apache like this:\n-\n-<VirtualHost *:80>\n-    ServerName\t\tgit.example.org\n-    DocumentRoot\t/pub/git\n-    SetEnv\t\t\tGITWEB_CONFIG\t/etc/gitweb.conf\n-\n-    # turning on mod rewrite\n-    RewriteEngine on\n-\n-    # make the front page an internal rewrite to the gitweb script\n-    RewriteRule ^/$  /cgi-bin/gitweb.cgi\n-\n-    # make access for \"dumb clients\" work\n-    RewriteRule ^/(.*\\.git/(?!/?(HEAD|info|objects|refs)).*)?$ /cgi-bin/gitweb.cgi%{REQUEST_URI}  [L,PT]\n-</VirtualHost>\n-\n-The above configuration expects your public repositories to live under\n-/pub/git and will serve them as http://git.domain.org/dir-under-pub-git,\n-both as cloneable GIT URL and as browseable gitweb interface.\n-If you then start your git-daemon with --base-path=/pub/git --export-all\n-then you can even use the git:// URL with exactly the same path.\n-\n-Setting the environment variable GITWEB_CONFIG will tell gitweb to use\n-the named file (i.e. in this example /etc/gitweb.conf) as a\n-configuration for gitweb.  Perl variables defined in here will\n-override the defaults given at the head of the gitweb.perl (or\n-gitweb.cgi).  Look at the comments in that file for information on\n-which variables and what they mean.\n-\n-If you use the rewrite rules from the example you'll likely also need\n-something like the following in your gitweb.conf (or gitweb_config.perl) file:\n-\n-  @stylesheets = (\"/some/absolute/path/gitweb.css\");\n-  $my_uri = \"/\";\n-  $home_link = \"/\";\n-\n-\n-Webserver configuration with multiple projects' root\n-----------------------------------------------------\n-\n-If you want to use gitweb with several project roots you can edit your apache\n-virtual host and gitweb.conf configuration files like this :\n-\n-virtual host configuration :\n-\n-<VirtualHost *:80>\n-    ServerName\t\t\tgit.example.org\n-    DocumentRoot\t\t/pub/git\n-    SetEnv\t\t\t\tGITWEB_CONFIG\t/etc/gitweb.conf\n-\n-    # turning on mod rewrite\n-    RewriteEngine on\n-\n-    # make the front page an internal rewrite to the gitweb script\n-    RewriteRule ^/$ \t\t/cgi-bin/gitweb.cgi [QSA,L,PT]\n-\n-    # look for a public_git folder in unix users' home\n-    # http://git.example.org/~<user>/\n-    RewriteRule ^/\\~([^\\/]+)(/|/gitweb.cgi)?$\t/cgi-bin/gitweb.cgi [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT]\n-\n-    # http://git.example.org/+<user>/\n-    #RewriteRule ^/\\+([^\\/]+)(/|/gitweb.cgi)?$\t/cgi-bin/gitweb.cgi [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT]\n-\n-    # http://git.example.org/user/<user>/\n-    #RewriteRule ^/user/([^\\/]+)/(gitweb.cgi)?$\t/cgi-bin/gitweb.cgi [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT]\n-\n-    # defined list of project roots\n-    RewriteRule ^/scm(/|/gitweb.cgi)?$\t\t/cgi-bin/gitweb.cgi [QSA,E=GITWEB_PROJECTROOT:/pub/scm/,L,PT]\n-    RewriteRule ^/var(/|/gitweb.cgi)?$\t\t/cgi-bin/gitweb.cgi [QSA,E=GITWEB_PROJECTROOT:/var/git/,L,PT]\n-\n-    # make access for \"dumb clients\" work\n-    RewriteRule ^/(.*\\.git/(?!/?(HEAD|info|objects|refs)).*)?$ /cgi-bin/gitweb.cgi%{REQUEST_URI}  [L,PT]\n-</VirtualHost>\n-\n-gitweb.conf configuration :\n-\n-$projectroot = $ENV{'GITWEB_PROJECTROOT'} || \"/pub/git\";\n-\n-These configurations enable two things. First, each unix user (<user>) of the\n-server will be able to browse through gitweb git repositories found in\n-~/public_git/ with the following url : http://git.example.org/~<user>/\n-\n-If you do not want this feature on your server just remove the second rewrite rule.\n-\n-If you already use mod_userdir in your virtual host or you don't want to use\n-the '~' as first character just comment or remove the second rewrite rule and\n-uncomment one of the following according to what you want.\n-\n-Second, repositories found in /pub/scm/ and /var/git/ will be accesible\n-through http://git.example.org/scm/ and http://git.example.org/var/.\n-You can add as many project roots as you want by adding rewrite rules like the\n-third and the fourth.\n-\n-\n-PATH_INFO usage\n------------------------\n-If you enable PATH_INFO usage in gitweb by putting\n-\n-   $feature{'pathinfo'}{'default'} = [1];\n-\n-in your gitweb.conf, it is possible to set up your server so that it\n-consumes and produces URLs in the form\n-\n-http://git.example.com/project.git/shortlog/sometag\n-\n-by using a configuration such as the following, that assumes that\n-/var/www/gitweb is the DocumentRoot of your webserver, and that it\n-contains the gitweb.cgi script and complementary static files\n-(stylesheet, favicon):\n-\n-<VirtualHost *:80>\n-\tServerAlias git.example.com\n-\n-\tDocumentRoot /var/www/gitweb\n-\n-\t<Directory /var/www/gitweb>\n-\t\tOptions ExecCGI\n-\t\tAddHandler cgi-script cgi\n-\n-\t\tDirectoryIndex gitweb.cgi\n-\n-\t\tRewriteEngine On\n-\t\tRewriteCond %{REQUEST_FILENAME} !-f\n-\t\tRewriteCond %{REQUEST_FILENAME} !-d\n-\t\tRewriteRule ^.* /gitweb.cgi/$0 [L,PT]\n-\t</Directory>\n-</VirtualHost>\n-\n-The rewrite rule guarantees that existing static files will be properly\n-served, whereas any other URL will be passed to gitweb as PATH_INFO\n-parameter.\n-\n-Notice that in this case you don't need special settings for\n-@stylesheets, $my_uri and $home_link, but you lose \"dumb client\" access\n-to your project .git dirs. A possible workaround for the latter is the\n-following: in your project root dir (e.g. /pub/git) have the projects\n-named without a .git extension (e.g. /pub/git/project instead of\n-/pub/git/project.git) and configure Apache as follows:\n-\n-<VirtualHost *:80>\n-\tServerAlias git.example.com\n-\n-\tDocumentRoot /var/www/gitweb\n-\n-\tAliasMatch ^(/.*?)(\\.git)(/.*)?$ /pub/git$1$3\n-\t<Directory /var/www/gitweb>\n-\t\tOptions ExecCGI\n-\t\tAddHandler cgi-script cgi\n-\n-\t\tDirectoryIndex gitweb.cgi\n-\n-\t\tRewriteEngine On\n-\t\tRewriteCond %{REQUEST_FILENAME} !-f\n-\t\tRewriteCond %{REQUEST_FILENAME} !-d\n-\t\tRewriteRule ^.* /gitweb.cgi/$0 [L,PT]\n-\t</Directory>\n-</VirtualHost>\n-\n-The additional AliasMatch makes it so that\n-\n-http://git.example.com/project.git\n-\n-will give raw access to the project's git dir (so that the project can\n-be cloned), while\n-\n-http://git.example.com/project\n-\n-will provide human-friendly gitweb access.\n-\n-This solution is not 100% bulletproof, in the sense that if some project\n-has a named ref (branch, tag) starting with 'git/', then paths such as\n-\n-http://git.example.com/project/command/abranch..git/abranch\n-\n-will fail with a 404 error.\n+Web server configuration\n+------------------------\n+Gitweb can be run as CGI script, as legacy mod_perl application (using\n+ModPerl::Registry), and as FastCGI script.  You can find some simple examples\n+in \"Example web server configuration\" section in INSTALL file for gitweb (in\n+gitweb/INSTALL).\n \n+See \"Webserver configuration\" and \"Advanced web server setup\" sections in\n+gitweb(1) manpage.\n \n \n+AUTHORS\n+-------\n Originally written by:\n   Kay Sievers <kay.sievers@vrfy.org>\n \n-- \n1.7.6\n"},{"id":"175718","messageId":"1316352884-26193-5-git-send-email-jnareb@gmail.com","threadId":"28418","inReplyTo":"1316352884-26193-1-git-send-email-jnareb@gmail.com","subject":"[PATCH/RFCv4 4/4] gitweb: Add gitweb manpages to 'gitweb' package in git.spec","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2011-09-18T13:34:44Z","receivedAt":"2011-09-18T13:34:44Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"This patch follows similar lines in %files section for 'gitk' and\n'git-gui' subpackages.\n\nSigned-off-by: Jakub Narebski <jnareb@gmail.com>\n---\nNew in this version of series... though IIRC this change was present\nin some version of those patches (probably not as separate patch,\nthough).\n\n git.spec.in |    7 +++++++\n 1 files changed, 7 insertions(+), 0 deletions(-)\n\ndiff --git a/git.spec.in b/git.spec.in\nindex 91c8462..dfc5093 100644\n--- a/git.spec.in\n+++ b/git.spec.in\n@@ -199,7 +199,11 @@ rm -rf $RPM_BUILD_ROOT\n \n %files -n gitweb\n %defattr(-,root,root)\n+%doc Documentation/*gitweb*.txt\n %{_datadir}/gitweb\n+%{!?_without_docs: %{_mandir}/man1/*gitweb*.1*}\n+%{!?_without_docs: %{_mandir}/man5/*gitweb*.5*}\n+%{!?_without_docs: %doc Documentation/*gitweb*.html }\n \n %files -n perl-Git -f perl-files\n %defattr(-,root,root)\n@@ -208,6 +212,9 @@ rm -rf $RPM_BUILD_ROOT\n # No files for you!\n \n %changelog\n+* Sun Sep 18 2011 Jakub Narebski <jnareb@gmail.com>\n+- Add gitweb manpages to 'gitweb' subpackage\n+\n * Wed Jun 30 2010 Junio C Hamano <gitster@pobox.com>\n - Add 'gitweb' subpackage.\n \n-- \n1.7.6\n"},{"id":"175824","messageId":"20110919233703.GF6343@elie","threadId":"28418","inReplyTo":"1316352884-26193-2-git-send-email-jnareb@gmail.com","subject":"Re: [PATCH/RFCv4 1/4] Documentation: Preparation for gitweb manpages","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2011-09-19T23:37:03Z","receivedAt":"2011-09-19T23:37:03Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Jakub Narebski wrote:\n\n> Gitweb documentation currently consist of gitweb/README, gitweb/INSTALL\n> and comments in gitweb source code.  This is harder to find, use and\n> browse that manpages (\"man gitweb\" or \"git help gitweb\") and HTML\n> documentation (\"git help --web gitweb\").\n\nLanguage nits: s/consist/consists/; s/that manpages/than manpages/.  I\ncompletely agree.\n\n> The goal is to move documentation out of gitweb/README to gitweb.txt and\n> gitweb.conf.txt manpages, reducing its size 10x from around 500 to\n> around 50 lines (two pages), and move information not related drectly to\n> building and installing gitweb out of gitweb/INSTALL there.\n\nI guess you mean this patch prepares for or is part of a larger\nproject or series with that goal?  Wording nits: s/and move\ninformation/and to move information/; s/drectly/directly/; s/ there//.\n \n> The idea is to have gitweb manpage sources reside in AsciiDoc format\n> in Documentation/ directory, like for gitk and git-gui.  Alternate\n> solution would be to have gitweb documentation in gitweb/ directory,\n> perhaps in POD format (see perlpod(1)).\n\nLanguage nits: missing \"the\" before \"Documentation/ directory\" and\n\"gitweb manpage sources\"; missing \"An\" before \"Alternate solution\".\nI guess this is the most controversial aspect of the patch; your idea\nseems sane enough to me.\n\n> This patch adds infrastructure for easy generating gitweb-related\n> manpages.  It adds currently empty 'gitweb-doc' target to\n> Documentation/Makefile, and 'doc' proxy target to gitweb's Makefile.\n\nLanguage nits: s/easy/easily/; missing \"a\" before \"currently empty\n'gitweb-doc' target\" and \"'doc' proxy target\".\n\n> This way to build gitweb documentation one can use\n>\n>   make -C gitweb doc\n>\n> or\n>\n>   cd gitweb; make doc\n\nLanguage nit: a comma after \"This way\" would disambiguate.\n\nDoes \"make -CDocumentation man html\" build the gitweb documentation,\ntoo (and \"make install-doc\" install it)?\n\n[...]\n> --- a/Documentation/Makefile\n> +++ b/Documentation/Makefile\n> @@ -170,6 +170,9 @@ info: git.info gitman.info\n>  \n>  pdf: user-manual.pdf\n>  \n> +GITWEB_DOC = $(filter gitweb.%,$(DOC_HTML) $(DOC_MAN1) $(DOC_MAN5) $(DOC_MAN7))\n> +gitweb-doc: $(GITWEB_DOC)\n\nLooks like no, alas.\n\nExcept for that detail, this looks good.\n\nThanks,\nJonathan\n"},{"id":"175826","messageId":"201109200210.13772.jnareb@gmail.com","threadId":"28418","inReplyTo":"20110919233703.GF6343@elie","subject":"Re: [PATCH/RFCv4 1/4] Documentation: Preparation for gitweb manpages","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2011-09-20T00:10:12Z","receivedAt":"2011-09-20T00:10:12Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Thanks a lot for all language fixes.\n\nNb. I'll respond to other comments separately.\n\nOn Tue, 20 Sep 2011, Jonathan Nieder wrote:\n> Jakub Narebski wrote:\n\n> > This way to build gitweb documentation one can use\n> >\n> >   make -C gitweb doc\n> >\n> > or\n> >\n> >   cd gitweb; make doc\n\nActually it should read \"to build only gitweb documentation\"...\n\n> Does \"make -CDocumentation man html\" build the gitweb documentation,\n> too (and \"make install-doc\" install it)?\n> \n> [...]\n> > --- a/Documentation/Makefile\n> > +++ b/Documentation/Makefile\n> > @@ -170,6 +170,9 @@ info: git.info gitman.info\n> >  \n> >  pdf: user-manual.pdf\n> >  \n> > +GITWEB_DOC = $(filter gitweb.%,$(DOC_HTML) $(DOC_MAN1) $(DOC_MAN5) $(DOC_MAN7))\n> > +gitweb-doc: $(GITWEB_DOC)\n> \n> Looks like no, alas.\n\n... because of the fact that gitweb.txt is in DOC_MAN1, and gitweb.conf.txt\nis in DOC_MAN5, then 'make doc' would among others build gitweb\ndocumentation.  'make -C Documentation gitweb-doc' / 'make -C gitweb doc'\njust builds a _subset_ of said documentation.\n\n> \n> Except for that detail, this looks good.\n\n\nNb. what is also missing is having links to gitweb(1) and gitweb.conf(5)\nin git(1) manpages together with the rest.\n\n-- \nJakub Narebski\nPoland\n"},{"id":"175835","messageId":"20110920044118.GI6343@elie","threadId":"28418","inReplyTo":"1316352884-26193-3-git-send-email-jnareb@gmail.com","subject":"Re: [PATCH/RFCv4 2/4] gitweb: Add manpage for /etc/gitweb.conf (for gitweb documentation)","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2011-09-20T04:41:18Z","receivedAt":"2011-09-20T04:41:18Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Jakub Narebski wrote:\n\n> [jn: Improved, extended, removed duplicate info from README]\n\nHoorah!  I have very little to add to what's already been done ---\nmostly I can just lend my ear as a native English speaker.\n\n[...]\n> --- a/Documentation/Makefile\n> +++ b/Documentation/Makefile\n> @@ -3,7 +3,7 @@ MAN1_TXT= \\\n>  \t\t$(wildcard git-*.txt)) \\\n>  \tgitk.txt git.txt\n>  MAN5_TXT=gitattributes.txt gitignore.txt gitmodules.txt githooks.txt \\\n> -\tgitrepository-layout.txt\n> +\tgitrepository-layout.txt gitweb.conf.txt\n\nI take back what I wrote about patch 1.  Maybe its commit message could\nbe clarified to mention that the new targets build a subset of the pages\nbuilt by the ordinary \"make doc\" et al targets.\n\n[...]\n> +++ b/Documentation/gitweb.conf.txt\n> @@ -0,0 +1,781 @@\n[...]\n> +The configuration file is used to override the default settings that\n> +were built into gitweb at the time 'gitweb.cgi' script was generated.\n> +\n> +While one could just alter the configuration settings in the gitweb\n> +CGI itself, those changes would be lost upon upgrade.  Configuration\n> +settings might also be placed into a file in the same directory as the\n> +CGI script with the default name 'gitweb_config.perl' -- allowing\n> +one to have multiple gitweb instances with different configurations by\n> +the use of symlinks.\n\nThis reads nicely now.  Language nit: missing \"the\" before\n\"'gitweb.cgi' script\".\n\n[...]\n> +DISCUSSION\n> +----------\n> +Gitweb obtains configuration data from the following sources in the\n> +following order:\n> +\n> + * built-in values (some set during build stage),\n> +\n> + * common system-wide configuration file (defaults to\n> +   '/etc/gitweb-common.conf'),\n> +\n> + * either per-instance configuration file (defaults to 'gitweb_config.perl'\n> +   in the same directory as the installed gitweb), or if it does not exists\n> +   then system-wide configuration file (defaults to '/etc/gitweb.conf').\n\nUsage nit: in the first sentence, \"reads\" would be more natural than\n\"obtains\".\n\nIn the third item, I'd suggest the phrase \"the fallback system-wide\nconfiguration file\" to emphasize how it differs from\ngitweb-common.conf.\n\n> +\n> +Values obtained in later configuration files override values obtained earlier\n> +in above sequence.\n\nLanguage nit: missing \"the\" before \"above sequence\".\n\n> +\n> +The location of common system-wide configuration file, of fallback system-wide\n> +configuration file and of per-instance configuration file is defined at compile\n> +time using the build-time Makefile configuration variables, respectively\n> +`GITWEB_CONFIG_COMMON`, `GITWEB_CONFIG_SYSTEM` and `GITWEB_CONFIG`.  \n\nLanguage nits: missing \"the\" before \"common system-wide configuration\nfile\", \"fallback system-wide configuration file\", and \"per-instance\nconfiguration files\".  The subject (\"The location\") and verb should be\nplural because we are talking about multiple locations.  Would sound a\nbit more natural in English (unlike French) if the preposition \"of\"\nwere used once instead of repeated.\n\nAnother language nit: it sounds a little better without the \"the\"\nbefore \"build-time Makefile configuration variables\", like so:\n\n\t... are defined at compile time using build-time Makefile\n\tvariables, namely `GITWEB_CONFIG_COMMON`, `GITWEB_CONFIG_SYSTEM`,\n\tand `GITWEB_CONFIG`.\n\n> +\n> +You can override location of gitweb configuration files during runtime\n> +by setting respective environment variables: `GITWEB_CONFIG_COMMON`,\n> +`GITWEB_CONFIG_SYSTEM` and `GITWEB_CONFIG` to non-empty value.\n\nLanguage nit: missing \"the\" before \"location\" and \"gitweb\nconfiguration files\".  \"location\" should probably be plural.  In place\nof \"respective\", \"the following\" sounds a little more natural.  Might\nbe nice to add an \"also\" after 'can' to emphasize the relationship to\nthe previous paragraph --- in addition to being able to override the\ndefault locations at compile time, you can override them at run time\nby setting environment variables.\n\n> +\n> +\n> +The syntax of the configuration files is that of Perl, as these files are\n> +indeed handled as fragments of Perl code (the language that gitweb itself is\n> +written in). Variables may be set using \"`our $variable = value`\"; text from\n> +\"#\" character until the end of a line is ignored. See the *perlsyn*(1) man\n> +page for more information.\n> +\n> +Actually using `our` qualifier in `our $variable = <value>;` is a safety\n> +check: if newer gitweb does no longer use given variable, by using `our` we\n> +won't get syntax errors.\n\nLanguage nit: for \"indeed\", something like \"internally\" might be more\nnatural.\n\nThe syntax and the typical idiom were already described in the\nDESCRIPTION section, so the emphasis should be somehow different here\nto avoid boring the reader.  One way might be to plunge directly into\nwhat the second paragraph above says:\n\n The syntax of the configuration files is that of Perl, since these files are\n handled by sourcing them as fragments of Perl code (the language that\n gitweb itself is written in). Variables are typically set using the\n `our` qualifier (as in \"`our $variable = <value>;`\") to avoid syntax\n errors if a new version of gitweb no longer uses a variable and therefore\n stops declaring it.\n\n> +\n> +You can include other configuration file using read_config_file()\n> +subroutine.  For example, you can read defaults in fallback\n> +system-wide GITWEB_CONFIG_SYSTEM from GITWEB_CONFIG by adding\n> +\n> +  read_config_file($GITWEB_CONFIG_SYSTEM);\n> +\n> +at very beginning of per-instance GITWEB_CONFIG file.  In this case\n> +settings in said per-instance file will override settings from\n> +system-wide configuration file.  Note that read_config_file checks\n> +itself that the file it reads exists.\n\nLanguage nits: missing \"the\" before \"fallback systemwide\n$GITWEB_CONFIG_SYSTEM file\" and \"very beginning\"; missing \"a\" before\n\"per-instance $GITWEB_CONFIG file\"; \"case\" should perhaps be \"example\"\nand followed by a comma.\n\nThe reader wonders: After checking that the file exists, what does\nread_config_file do (does it silently skip it or error out)?  And why\nwould I use this trick instead of just writing a gitweb-common.conf\nfile?  (Was read_config_file introduced before gitweb-common.conf,\nmaking this useful when creating a configuration that should be usable\nwith older versions of gitweb?)\n\n[...]\n> +CONFIGURATION VARIABLES\n> +-----------------------\n> +Some of configuration variables have their default values (embedded in CGI\n> +file) set during building gitweb -- if that is the case, it is put in their\n> +description.  See gitweb's 'INSTALL' file for instructions on building and\n> +installing gitweb.\n\nLanguage nit: \"Some of configuration variables\" should be \"Some\nconfiguration variables\"; missing \"the\" before \"CGI script\"; \"it is\"\nshould be \"they are\" to agree with 'variables'.\n\n> +\n> +\n> +Location of repositories\n> +~~~~~~~~~~~~~~~~~~~~~~~~\n> +Configuration variables described below control finding git repositories by\n> +gitweb, and control display and access to repositories.\n\nLanguage nits: missing \"The\" before \"Configuration variables described\nbelow\"; \"finding git repositories by gitweb\" sounds more natural when\nparaphrased as \"how gitweb finds git repositories\" and \"display and\naccess to repositories\" paraphrased as \"how repositories are displayed\nand accessed\"; it seems that the sentence scans a little better when\nnot repeating the verb \"control\".\n\n[...]\n> +For example if `$projectroot` is set to \"/srv/git\" by putting the following\n> +in gitweb config file:\n> ++\n> +----------------------------------------------------------------------------\n> +our $projectroot = \"/srv/git\";\n> +----------------------------------------------------------------------------\n> ++\n> +then\n> ++\n> +------------------------------------------------\n> +http://git.example.com/gitweb.cgi?p=foo/bar.git\n> +------------------------------------------------\n> ++\n> +or its path_info based equivalent\n> ++\n> +------------------------------------------------\n> +http://git.example.com/gitweb.cgi/foo/bar.git\n> +------------------------------------------------\n> ++\n> +will map to path '/srv/git/foo/bar.git' on filesystem.\n\nLanguage nits: missing comma after \"For example\"; \"or\" should be\n\"and\"; missing \"the\" before \"path '/srv/git/foo/bar.git'\" and\n\"filesystem\".\n\n> +\n> +$project_maxdepth::\n> +\tFilesystem traversing depth limit for recursively scanning for git\n> +\trepositories, used if `$projects_list` (below) is unset.  The default\n> +\tvalue of this variable is determined by build-time configuration\n> +\tvariable `GITWEB_PROJECT_MAXDEPTH`, which defaults to 2007.\n\n\"Filesystem traversing depth limit\" is quite a long stack of nouns :),\nand unfortunately I don't know what it means.  Is this the depth of\nnested subdirectories below $project_root that gitweb will look at\nwhen discovering repositories?  If I have no subdirectories in the\nprojectroot except the repositories themselves, should I set this to 1\nor 0?  What happens with forks?  Is this just a convenience feature or\ncan it be used for security or to create performance gaurantees?\n\nBy the way, what happens if projectroot contains a symlink to some\ndirectory elsewhere in the filesystem containing repositories --- will\ngitweb traverse it?\n\nWhat if I want this to be infinite (i.e., to disable the feature) ---\nwould I be crazy?\n\nLanguage nit: missing \"the\" before \"`GITWEB_PROJECT_MAXDEPTH` Makefile\nvariable used at build time, which defaults to 2007\".\n\n> +\n> +$projects_list::\n> +\tPlain text file listing projects or name of directory\n> +\tto be scanned for projects.\n> ++\n> +Project list files should list one project per line, with each line\n> +having the following format\n> ++\n> +-----------------------------------------------------------------------------\n> +<URI-encoded filesystem path to repository> SP <URI-encoded repository owner>\n> +-----------------------------------------------------------------------------\n> ++\n> +The default value of this variable is determined by the `GITWEB_LIST`\n> +makefile variable at installation time.  If this variable is empty, gitweb\n> +will fall back to scanning the `$projectroot` directory for repositories.\n\nLanguage nit: missing \"Path to a\" or \"Name of a\" before \"Plain text\nfile\".\n\nWhen this is a relative path, what is it taken relative to?\n\n> +\n> +$export_ok::\n> +\tShow repository only if this file exists (in repository).  Only\n> +\teffective if this variable evaluates to true.  Can be set during\n> +\tbuilding gitweb via `GITWEB_EXPORT_OK`.  [No default / Not set]\n\nThis is always a relative path, right?  What is it relative to ---\n$GIT_DIR, I guess?\n\nUsage nits: the phrase starting with \"during\" reads more naturally if\n\"during\" is replaced with \"when\" and \"via\" replaced with \"by setting\".\nIf there were no default, that would mean that gitweb errors out when\ngitweb.conf does not set this variable; instead, the default seems to\nbe \"undef\" (or 'false') if I understand correctly.\n\n> +\n> +$export_auth_hook::\n> +\tShow repository only if this subroutine returns true, when given as\n> +\tthe only parameter the full path to the project.  Example:\n> ++\n> +----------------------------------------------------------------------------\n> +our $export_auth_hook = sub { return -e \"$_[0]/git-daemon-export-ok\"; };\n> +----------------------------------------------------------------------------\n> ++\n> +though the above might be done by using `$export_ok` instead\n> ++\n> +----------------------------------------------------------------------------\n> +our $export_ok = \"git-daemon-export-ok\";\n> +----------------------------------------------------------------------------\n\nStyle nit: commands in this kind of documentation should be directed to\nthe reader, not gitweb, so it would be nicer to explain this in terms of\nwhat the $export_auth_hook is.  That is, something like the following:\n\n $export_auth_hook::\n\tFunction used to determine which repositories should be shown.\n\tThis subroutine should take one parameter, the full path to\n\ta project, and if it returns true, that project will be included\n\tin the projects list and can be accessed through gitweb as long\n\tas it fulfills the other requirements described by $export_ok,\n\t$projects_list, and $projects_maxdepth.  Example:\n\nIs \"our $export_auth_hook = undef;\" a valid configuration?  What is the\ndefault?\n\n> +\n> +$strict_export::\n> +\tOnly allow viewing of repositories also shown on the overview page.\n> +\tThis for example makes `$gitweb_export_ok` file decide if repository is\n> +\tavailable and not only if it is shown.  If `$gitweb_list` points to\n> +\tfile with list of project, only those repositories listed would be\n> +\tavailable for gitweb.  Can be set during building gitweb via\n> +\t`GITWEB_STRICT_EXPORT`.  [No default / Not set]\n\nIs the default behavior as though this were true or false?\n\n> +Finding files\n> +~~~~~~~~~~~~~\n> +Those configuration variables tell gitweb where to find files.  Values of\n> +those variables are paths on filesystem.  Of those only `$GIT` is required\n> +to be (correctly) set for gitweb to be able to work; all the rest are\n> +required only for extra configuration or extra features.\n\nLanguage nit: \"Those\" should be \"The following\" in the first sentence and\n\"these\" in remaining sentences; missing \"The\" before \"Values of those\nvariables\" and \"filesystem\"; missing comma after \"Of these\".\n\nWhen you say the remainder are only required in special cases, does\nthat mean that they are ignored unless some other enabling variable is\nset or that they can be set to \"undef\" to disable the relevant\nfeature?\n\n> +\n> +$GIT::\n> +\tCore git executable to use.  By default set to `$GIT_BINDIR/git`, which\n> +\tin turn is by default set to `$(bindir)/git`.  If you use git from binary\n> +\tpackage, set this to \"/usr/bin/git\".  This can just be \"git\" if your\n> +\twebserver has a sensible PATH.  If you have multiple git versions installed\n> +\tit can be used to choose which one to use.\n\nLanguage nit: missing \"a\" or \"your operating system distributor's\" before\n\"binary package\".\n\n> +\n> +$mimetypes_file::\n> +\tFile to use for (filename extension based) guessing of MIME types before\n> +\ttrying '/etc/mime.types'.  Path, if relative, is taken currently as\n> +\trelative to the current git repository.  [Unset by default]\n\nLanguage nit: missing \"The\" before \"Path\".\n\nThe use of \"currently\" sounds like an apology.  Does that mean that\ngitweb ought to be rejecting relative paths for this variable?\n\n> +\n> +$highlight_bin::\n> +\tPath to the highlight executable to use (must be the one from\n> +\thttp://www.andre-simon.de due to assumptions about parameters and output).\n> +\tUseful if 'highlight' is not installed on your webserver's PATH.\n> +        [Default: 'highlight']\n> ++\n> +*NOTE*: if you want to add support for new syntax (supported by\n> +\"highlight\" but not used by gitweb), you need to modify `%highlight_ext`\n> +or `%highlight_basename`, depending on whether you detect type of file\n> +based on extension (for example \"*.sh\") or on its basename (for example\n> +\"Makefile\").  Keys of those hashes are extension or basename,\n> +respectively, and value for given key is name of syntax to be passed via\n> +`--syntax <syntax>` to highlighter.\n\nLanguage nits: missing \"it\" before \"must be the one\"; \"new syntax\"\nshould probably be \"a new file type\" or something like that; missing\n\"The\" before \"Keys of those hashes\"; \"those\" should be \"these\"; \"or\"\nshould be \"and\".\n\nIs \"*.sh\" actually an example of an extension?  I.e., do I write the\nfollowing?\n\n\tour %highlight_ext;\n\t$highlight_ext{\"*.sh\"} = \"sh\";\n\n> +\n> +\n> +Links and their targets\n> +~~~~~~~~~~~~~~~~~~~~~~~\n> +Configuration variables described below configure some of gitweb links:\n> +their target and their look (text or image), and where to find page\n> +prerequisites (stylesheet, favicon, images, scripts).  Usually they are left\n> +at their default values, with the possible exception of `@stylesheets`\n> +variable.\n\nLanguage nits: missing \"The\" before \"Configuration variables described\nbelow\"; missing \"some\" before \"supporting files\".\n\n> +\n> +@stylesheets::\n> +\tList of URIs of stylesheets (relative to base URI of a page). You\n> +\tmight specify more than one stylesheet, for example use gitweb.css\n> +\tas base, with site specific modifications in separate stylesheet\n> +\tto make it easier to upgrade gitweb. You can add a `site` stylesheet\n> +\tfor example by putting\n> ++\n> +----------------------------------------------------------------------------\n> +push @stylesheets, \"gitweb-site.css\";\n> +----------------------------------------------------------------------------\n> ++\n> +in the gitweb config file.  Those values that are relative paths, are\n> +relative to base URI of gitweb.\n\nLanguage nits: missing \"the\" before \"base URI\".  What is a base URI ---\nis it set by another variable?  Missing \"to\" before \"use gitweb.css as\na base\"; there should not be a comma before \"with site-specific\nmodifications\" or before \"are relative\"; missing \"a\" before \"separate\nstylesheet\"; missing commas surrounding \"for example\" (or even better,\n\"For example,\" could move to the start of the sentence).\n\n> ++\n> +This list should contain URI of gitweb's stylesheet.  The URI of gitweb\n> +stylesheet is set during build time via `GITWEB_CSS` variable.  It's default\n> +value is 'static/gitweb.css' (or 'static/gitweb.min.css' if the `CSSMIN`\n> +variable is defined, i.e. if CSS minifier is used during build).\n> ++\n> +*Note*: there is also legacy `$stylesheet` configuration variable, which was\n> +used by older gitweb.\n\nLanguage nits: missing \"the\" before \"URI of gitweb's standard stylesheet\";\nmissing \"default\" before \"URI of the gitweb stylesheet\"; \"is set\nduring\" should be \"can be set at\"; \"via `GITWEB_CSS` variable\" should be\n\"using the `GITWEB_CSS` makefile variable\"; extra apostrophe in \"It's\";\nmissing \"a\" before \"legacy `$stylesheet` configuration variable\".\n\nIf I am new on the job and find the $stylesheet variable set, what\nshould I interpret it to mean?  How can it be translated to the newer\n@stylesheets style?  What happens if both variables are set --- does\none override the other, or are they combined somehow?\n\n> +\n> +$logo::\n> +\tPoints to the location where you put 'git-logo.png' on your web\n> +\tserver, or to be more generic URI of logo, 72x27 size).  This image\n> +\tis displayed in top right corner of each gitweb page, and used as\n> +\tlogo for Atom feed.  Relative to base URI of gitweb (as a path).\n> +\tCan be adjusted during building gitweb using `GITWEB_LOGO` variable\n> +        [Default: 'static/git-logo.png']\n\nLanguage nits: missing \"the\" before \"generic URI\", \"top-right corner\",\n\"Atom feed\", and \"base URI of gitweb\"; missing \"a\" before \"logo\";\nthere should not be a comma before \"and used\"; \"during\" sounds more\nnatural when it is replaced with \"when\".\n\n> +\n> +$favicon::\n> +\tPoints to the location where you put 'git-favicon.png' on your web\n> +\tserver, or to be more generic URI of favicon, assumed to be\n> +\t\"image/png\" type; web browsers that support favicons (website icons)\n> +\tmay display them in the browser's URL bar and next to site name in\n> +\tbookmarks.  Relative to base URI of gitweb.  Can be adjusted during\n> +\tbuild time using `GITWEB_FAVICON` variable.\n> +        [Default: 'static/git-favicon.png']\n\nLanguage nits: missing \"the\" before \"generic URI\", \"site name\", and\n\"base URI\"; missing \"your chosen\" before \"favicon\"; \"assumed to be\"\nshould be \"which will be served as\" or something like that; would be\neasier to read with the semicolon before \"web browsers\" replaced by a\nfull stop; \"may\" should be \"will\"; \"during\" sounds more natural when\nit is replaced with \"at\".\n\n> +\n> +$javascript::\n> +\tPoints to the location where you put 'gitweb.js' on your web server,\n> +\tor to be more generic URI of JavaScript code used by gitweb.\n> +\tRelative to base URI of gitweb.  Set during build time using\n> +\t`GITWEB_JS` build-time configuration variable.\n> ++\n> +Default value is either 'static/gitweb.js', or 'static/gitweb.min.js' if\n> +`JSMIN` build variable is defined, i.e. if JavaScript minifier is used\n> +during build.  *Note* that this single file is build (composed) of\n> +individual JavaScript \"modules\".\n\nLanguage nits: missing \"the\" before \"URI\", \"Javascript library\", \"base\nURI\", \"`GITWEB_JS`\" makefile variable\", \"Default value\", and \"`JSMIN`\nmakefile variable\"; \"Set during\" sounds more natural when it is\nreplaced by \"Can be set at\"; \"is defined\" and \"is used\" should be \"was\ndefined\" and \"was used\" to reflect installation probably already\nhaving occured; \"during build\" sounds more natural when it is replaced\nby \"at build time\"; \"build of\" should be \"built from\" or \"generated\nfrom multiple\".\n\n> +\n> +$home_link::\n> +\tTarget of the home link on top of all pages (the first part of view\n> +\t\"breadcrumbs\").  By default set to absolute URI of a page ($my_uri).\n\nLanguage nit: missing \"the\" before \"top\" and \"absolute URI\".\n\nWhich page does \"a page\" refer to here (doesn't $my_uri change from\nrequest to request)?\n\n> +\n> +$home_link_str::\n> +\tDescription of the home link on top of all pages, leading to $home_link\n> +\t(usually main gitweb page, which means projects list).  Used as first\n> +\tpart of gitweb view \"breadcrumb trail\": `<home> / <project> / <view>`.\n> +\tCan be set during build time using `GITWEB_HOME_LINK_STR` variable.\n> +\t[Default: \"projects\"]\n\nLanguage nits: \"Description of\" means \"Label for\", I suppose; \"home\nlink\" should be \"home page link\" (?); \"on top\" is \"at the top\";\nmissing \"the\" before \"main gitweb page\"; \"which means projects list\"\nis more friendly if paraphrased as \"which contains the projects list\";\n\"part of gitweb view\" could be paraphrased as \"component of gitweb's\";\n\"during\" sounds more natural if replaced by \"at\"; missing \"the\" before\n\"`GITWEB_HOME_LINK_STR` makefile variable\".\n\n> +\n> +$logo_url::\n> +$logo_label::\n> +\tURI and label (title) of GIT logo link (or your site logo, if you choose\n> +\tto use different logo image). By default they point to git homepage;\n> +\tin the past they pointed to git documentation at www.kernel.org.\n\nLanguage nits: \"of GIT logo link\" should probably be \"for the Git logo\nlink\"; \"choose\" should be \"chose\" since that's in the past when the\nadmin is setting this variable; missing comma after \"By default\" and\n\"in the past\"; the first \"they\" should be \"these both\".\n\n> +\n> +\n> +Changing gitweb look\n> +~~~~~~~~~~~~~~~~~~~~\n> +You can adjust how pages generated by gitweb look using variables described\n> +below.  You can change site name, add common headers and footers for all\n> +pages, and add description of gitweb installation on its main page (which is\n> +projects list page), etc.\n\nLanguage nits: missing \"'s\" in \"Changing gitweb's look\"; missing \"the\"\nbefore \"variables described below\", \"site name\", and \"project list\npage\"; missing \"a\" before \"description\"; missing \"this\" before \"gitweb\ninstallation\".\n\n> +\n> +$site_name::\n> +\tName of your site or organization to appear in page titles.  Set it\n> +\tto something descriptive for clearer bookmarks etc.  If not set (if\n> +\tempty) then gitweb uses value of `SERVER_NAME` CGI environment\n> +\tvariable setting prefix of each page title to \"$SERVER_NAME Git\", or\n> +\t\"Untitled Git\" if this variable is not set (e.g. if running gitweb\n> +\tas standalone script).\n> ++\n> +Can be set using `GITWEB_SITENAME` during building.  [No default]\n\nLanguage nits: missing comma after \"organization\" and before \"for use\nin page titles\"; missing \"the\" before \"the value\", \"`SERVER_NAME`\nenvironment variable\", and \"`GITWEB_SITENAME` makefile variable\";\n\"If not set\" is missing a subject --- \"If this variable is unset or\nempty, then gitweb will ...\"; \"during building\" sounds more natural\nwhen replaced by \"at build time\".\n\n> +\n> +$site_header::\n> +\tFilename of html text to include at top of each page.  Relative to\n> +\t'gitweb.cgi' script.  Can be set using `GITWEB_SITE_HEADER` during\n> +\tbuilding.  [No default]\n\nLanguage nits: \"Filename of html text to include\" should be \"Name of a\nfile with HTML to be included\" (or \"Path to ...\"); \"'gitweb.cgi'\nscript\" should be \"the directory containing the 'gitweb.cgi' script\";\n\"during building\" sounds more natural when replaced by \"at build\ntime\".\n\n> +\n> +$site_footer::\n> +\tFilename of html text to include at bottom of each page.  Relative to\n> +\tgitweb.cgi script.  Can be set using `GITWEB_SITE_FOOTER` during\n> +\tbuilding.  [No default]\n\nLikewise.\n\n> +\n> +$home_text::\n> +\tPoints to an HTML file which, if it exists, is included on the\n> +\tgitweb projects overview page (\"projects_list\" view).  Relative to\n> +\tgitweb.cgi script.  Default value can be adjusted using during build\n> +\tvia `GITWEB_HOMETEXT` variable.\n> +\t[Default: 'indextext.html']\n\nLikewise.\n\n> +\n> +$projects_list_description_width::\n> +\tThe width (in characters) of the projects list \"Description\" column.\n> +\tLonger descriptions will be cut (trying to cut at word boundary);\n> +\tfull description is available as 'title' attribute (usually shown on\n> +\tmouseover).  By default set to 25, which might be too small if you\n> +\tuse long project descriptions.\n\nLanguage nit: 'project list \"Description\" column' sounds more natural when\nrearranged to 'the \"Description\" column of the project list'; \"cut\" should\nbe \"truncated\"; missing \"the\" before \"full description\"; \"as 'title'\nattribute\" sounds better as \"in the 'title' attribute\"; instead of \"By\ndefault set to\", it is clearer to say \"The default is\".\n\n> +\n> +$default_projects_order::\n> +\tDefault value of ordering of projects on projects list page.  Valid\n> +\tvalues are \"none\" (unsorted), \"project\" (by project name, i.e. path\n> +\tto repository relative to `$projectroot`), \"descr\" (project\n> +\tdescription), \"owner\", and \"age\" (by date of most current commit).\n> ++\n> +Default value is \"project\".  Unknown value means unsorted.\n\nWhat does \"Default\" mean here (i.e., what overrides it)?\n\n> +\n> +\n> +Changing gitweb behavior\n> +~~~~~~~~~~~~~~~~~~~~~~~~\n> +Those configuration variables control _internal_ gitweb behavior.\n\nLanguage nits: missing \"'s\" in \"gitweb's behavior\"; \"Those\" should be\n\"These\".  Does internal behavior mean \"functionality as opposed to\nappearance and input location\" or something like that?\n\n> +\n> +$default_blob_plain_mimetype::\n> +\tDefault mimetype for blob_plain (raw) view, if mimetype checking\n> +\tdoesn't result in some other type; by default \"text/plain\".\n\nLanguage nit: missing \"the\" before \"blob_plain (raw) view\".\n\nWhere can I look to read more about mimetype autodetection?\n\n> +\n> +$default_text_plain_charset::\n> +\tDefault charset for text files. If not set, web server configuration\n> +\twould be used.\n\nLanguage nits: to make clear that it is not the web server\nconfiguration that is not set, \"If not set\" could be paraphrased to\n\"If this is unset\"; \"would\" should be \"will\" (yes, conditionals in\nEnglish are weird); missing \"the\" before \"web server's usual\nconfiguration\".\n\n> +\n> +$fallback_encoding::\n> +\tGitweb assumes this charset if line contains non-UTF-8 characters.\n> +\tFallback decoding is used without error checking, so it can be even\n> +\t\"utf-8\". Value must be valid encoding; see *Encoding::Supported*(3pm)\n> +\tman page for a list.  By default \"latin1\", aka. \"iso-8859-1\".\n\nLanguage nits: \"if\" should be \"when\"; missing \"a\" before \"line\" and\n\"valid encoding\"; missing \"The\" before \"Fallback encoding\", \"Value\",\nand \"Encoding::Supported(3pm) manpage\"; \"By default\" sounds a little\nbetter as \"The default is\" or \"Default:\".\n\n> +\n> +@diff_opts::\n> +\tRename detection options for git-diff and git-diff-tree. By default\n> +\t(\\'-M'); set it to (\\'-C') or (\\'-C', \\'-C') to also detect copies,\n> +\tor set it to () i.e. empty list if you don't want to have renames\n> +\tdetection.\n\nLanguage nit: \"By default\" sounds a little better as \"The default is\".\n\nProbably worth mentioning that GNU patch still has problems with some\nrename patches, especially when they involve file copies ['-C'] or\ncriss-cross renames ['-B'] (see [1] and [2], for example).\n\n[1] http://savannah.gnu.org/bugs/?31058\n[2] http://thread.gmane.org/gmane.linux.ports.sh.devel/8697/focus=8773\n\n> +\n> +Extra features, administrative\n> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n> +Most of features are configured via `%feature` hash; however some of extra\n> +gitweb features can be turned on and configured using variables described\n> +below.  This list beside configuration variables that control how gitweb\n> +looks does contain variables configuring administrative side of gitweb\n> +(e.g. cross-site scripting prevention; admittedly this as side effect\n> +affects how \"summary\" pages look like, or load limiting).\n\nLanguage nit: the title sounds like these are going to be extra\nadministrative features --- might be best to spell it out (\"Some\noptional features and policies\" or something like that).\n\n> +\n> +@git_base_url_list::\n> +\tList of git base URLs used for URL to where fetch project from, shown\n> +\tin project summary page.  Full URL is \"`$git_base_url/$project`\".  You\n> +\tcan setup multiple base URLs (for example one for `git://` protocol\n> +\taccess, and one for `http://` \"dumb\" protocol access).  Note that per\n> +\trepository configuration can be set in '$GIT_DIR/cloneurl' file, or as\n> +\tvalues of multi-value `gitweb.url` configuration variable in project\n> +\tconfig.\n> ++\n> +You can setup one single value (single entry/item in this list) during\n> +building by using `GITWEB_BASE_URL` built-time configuration variable.\n> +[No default]\n\nLanguage nits: \"git base URLs used for URL to where fetch project from\"\nmeans something like \"Git URLs relative to which projects can be\nfetched\"; missing \"The\" before and 'for the `\"$projectroot/$project\"`\nrepository' after \"Full URL\"; \"setup\" as a verb is spelled \"set up\" or\n\"set\" (2x); \"http://\" access is not necessarily passive; \"during\nbuilding\" sounds better as \"at build time\"; \"using\" should be \"setting\nthe\"; \"built-time configuration variable\" is spelled as \"build-time\nconfigu...\" or even better as \"makefile variable\"; \"No default\" does\nnot seem quite right --- I think the default is \"Default: ()\" (i.e.,\nit defaults to the empty list).\n\nIs the per repository cloneurl added to this list, or does it override\nit?\n\n> +\n> +$projects_list_group_categories::\n> +\tEnables the grouping of projects by category on the project list page.\n> +\tThe category of a project is determined by the `$GIT_DIR/category` file\n> +\tor the `gitweb.category` variable in its repository configuration.\n> +\t[Disabled by default].\n\nLanguage nits: \"its repository configuration\" probably means \"each\nrepository's configuration\"; \"Enables\" can be rephrased more clearly\nas \"Whether to enable\" (assuming this is boolean).\n\n> +\n> +$project_list_default_category::\n> +\tDefault category for projects for which none is specified.  If set to\n> +\tthe empty string, such projects will remain uncategorized and listed at\n> +\tthe top, above categorized projects.  Used only if project cateories are\n> +\tenabled, which means if `$projects_list_group_categories` is true.\n> +\t[Default: \"\" (empty string)]\n\nLanguage nit: \"If set to the empty string\" is clearer as \"If this is\nset to the empty string\" since it is not the projects but this\nvariable that is being set to the empty string.\n\n> +\n> +$prevent_xss::\n> +\tIf true, some gitweb features are disabled to prevent content in\n> +\trepositories from launching cross-site scripting (XSS) attacks.  Set this\n> +\tto true if you don't trust the content of your repositories.\n> +\t[Default: false].\n\nNice.\n\n> +\n> +$maxload::\n> +\tUsed to set the maximum load that we will still respond to gitweb queries.\n> +\tIf server load exceed this value then return \"503 Service Unavailable\"\n> +\terror. Server load is taken to be 0 if gitweb cannot determine its value.\n> +\tSet it to undefined value to turn it off. [Default: 300]\n\nProbably worth spelling out that this is a \"load average\" (as shown by uptime(1)).\n\nLanguage nits: missing \"the\" before \"server load\" (2x); instead of\n\"exceed\", use \"exceeds\" (singular); missing subject \"gitweb\" before\n\"will return the\"; clearer to say it is \"this feature\" rather than\n\"it\" that can be turned off by setting this var to undef.\n\n> +\n> +$per_request_config::\n> +\tIf set to code reference, it would be run once per each request.  You can\n> +\tset parts of configuration that change per session, e.g. by adding\n> +\tthe following code to gitweb configuration file\n> ++\n> +--------------------------------------------------------------------------------\n> +our $per_request_config = sub {\n> +\t$ENV{GL_USER} = $cgi->remote_user || \"gitweb\";\n> +};\n> +--------------------------------------------------------------------------------\n\nLanguage nits: missing \"this is\" before \"set to a code reference\";\n\"would\" should be \"will\" (those crazy English conditionals again); the\nappropriate preposition before \"each request\" is \"for\", not \"per\";\nmissing \"this way\" after \"change per session\"; would be clearer with a\nfull stop before the example, and with the example made into a full\nsentence (\"For example, one might use the following code in a gitweb\nconfiguration file:\").\n\n> ++\n> +Otherwise it is treated as boolean value: if true gitweb would process\n> +config file once per request, if false it would process config file only\n> +once.  [Default: true]\n> ++\n> +*NOTE*: `$my_url`, `$my_uri`, and `$base_url` are overwritten with their default\n> +values before every request, so if you want to change them, be sure to set\n> +this variable to true or a code reference effecting the desired changes.\n\nAt this point, I've forgotten what the \"Otherwise\" is contrasting with;\nprobably best to repeat it (\"If $per_request_config is not a code\nreference, it is interpreted as a boolean value.\"); \"would\" should be\n\"will\" again (2x); missing \"the\" or \"each\" before \"config file\" (2x);\nmissing \"and\" before \"if it is false\"; \"it\" could be \"gitweb\" to\navoid confusion in this pronoun-heavy sentence; missing \"each time it\nis executed\" after \"process the config file only once\".\n\nProbably worth mentioning that this variable starts to shine when one\ngitweb instance is used to serve multiple requests, with CGI\nreplacements like mod_perl, fastcgi, plackup, and so on.\n\n> +\n> +\n> +Other variables\n> +~~~~~~~~~~~~~~~\n> +Usually you should not need to change (adjust) any of configuration\n> +variables described below; they should be automatically set by gitweb to\n> +correct value.\n> +\n> +\n> +$version::\n> +\tGitweb version, set automatically when creating gitweb.cgi from\n> +\tgitweb.perl. You might want to modify it if you are running modified\n> +\tgitweb, for example \n> ++\n> +---------------------------------------------------\n> +our $version .= \" with caching\";\n> +---------------------------------------------------\n\nMight be worth mentioning this is only used in HTML comments and the\n\"generator\" metadata field, nothing more special than that.\n\n> +\n> +$my_url::\n> +$my_uri::\n> +\tFull URL and absolute URL of gitweb script;\n> +\tin earlier versions of gitweb you might have need to set those\n> +\tvariables, now there should be no need to do it.  See\n> +\t`$per_request_config` if you need to set them still.\n\nLanguage nits: missing \"the\" before \"gitweb script\" and \"but\" before\n\"now\".\n\nWhat is the difference between a full URL and an absolute URL?\n\n> +\n> +$base_url::\n> +\tBase URL for relative URLs in pages generated by gitweb,\n> +\t(e.g. `$logo`, `$favicon`, `@stylesheets` if they are relative URLs),\n> +\tneeded and used only for URLs with nonempty PATH_INFO via\n> +\t'<base href=\"$base_url\">'.  Usually gitweb sets its value correctly,\n> +\tand there is no need to set this variable, e.g. to $my_uri or \"/\".\n> +\tSee `$per_request_config` if you need to set it anyway.\n\nLanguage nits: clearer with \"via '<base ...>'\" moved before \"only for\nURLs with nonempty PATH_INFO\"; \"no need to set\" could be \"no need to\noverride\".\n\n> +\n> +\n> +CONFIGURING GITWEB FEATURES\n> +---------------------------\n> +Many gitweb features can be enabled (or disabled) and configured using the\n> +`%feature` hash.  Names of gitweb features are keys of this hash.\n> +\n> +Each `%feature` hash element is a hash reference and has the following\n> +structure:\n> +----------------------------------------------------------------------\n> +\"<feature_name>\" => {\n> +\t\"sub\" => <feature-sub (subroutine)>,\n> +\t\"override\" => <allow-override (boolean)>,\n> +\t\"default\" => [ <options>... ]\n> +},\n> +----------------------------------------------------------------------\n\nNice.\n\n> +Some of features does not support project specific override.  For those\n> +features the structure of appropriate `%feature` hash element has a simpler\n> +form:\n> +----------------------------------------------------------------------\n> +\"<feature_name>\" => {\n> +\t\"override\" => 0,\n> +\t\"default\" => [ <options>... ]\n> +},\n> +----------------------------------------------------------------------\n> +As one can see it lacks \\'sub' element.\n\nLanguage nits: the \"of\" in \"Some of features\" is extraneous; \"does\" should\nbe \"do\" (plural) because we are talking about multiple features,\nor, better, be replaced by \"cannot be overriden per project\" (so:\n\"Some features cannot be overridden per project\"); missing \"the\"\nbefore \"'sub' field\".\n\n> +\n> +The meaning of respective parts of feature configuration are described\n> +below:\n\nLanguage nit: \"respective parts\" should be \"each part\", \"each field\",\nor something like that; \"are\" needs to be \"is\" to agree with the\nsubject ('meaning').\n\n> +\n> +default::\n> +\tList (array reference) of feature parameters (if there are any),\n> +\tused also to toggle (enable or disable) given feature.\n> ++\n> +Note that it is currently *always* an array reference, even if\n> +feature doesn't accept any configuration parameters, and \\'default'\n> +is used only to turn it on or off.  In such case you turn feature on\n> +by setting this element to `[1]`, and torn it off by setting it to\n> +`[0]`.  See also part about \"blame\" feature in the \"Examples\"\n> +section.\n> ++\n> +To disable feature that accepts parameters (is configurable), you\n> +need to set this element to empty list i.e. `[]`.\n\nNits: \"part\" means \"passage\" here; missing \"the\" before \"passage\" and\n'\"blame\" feature'; \"feature\" should be \"features\", \"accepts\" should\nbe \"accept\", and \"is configurable\" should be \"are configurable\".\n\n> +\n> +override::\n> +\tIf it has a true value then given feature is overridable, which\n> +\tmeans that it can be configured (or enabled/disabled) on\n> +\tper-repository basis.\n> ++\n> +Usually given \"<feature>\" is configurable via `gitweb.<feature>`\n> +config variable in per-repository git configuration file.\n> ++\n> +*Note* that no feature is overridable by default.\n\nNits: better to spell out what \"it\" is (\"this field\", I guess);\nmissing \"the\" before \"given feature\", \"`gitweb.<feature>`\nconfiguration variable\", and \"per-repository Git configuration file\".\n\n> +\n> +sub::\n> +\tSubroutine that will be called with default options as parameters to\n> +\texamine per-repository configuration, but only if feature is\n> +\toverridable (\\'override' is set to true).  If not present then\n> +\tper-repository override for given feature is not supported.\n> ++\n> +You wouldn't need to ever change it in gitweb config file.\n\nLanguage nits: \"default options as parameters\" means \"the array\nreferred to by the 'default' field as parameter list\", I guess.\nMissing \"the\" before \"feature is overridable\" and \"gitweb\nconfiguration files\".  \"given feature\" -> \"this feature\".  \"not\nsupported\" -> \"not enabled\", maybe.\n\nActually, I'm not sure I understand this one.  Are users supposed to\nset this field?  Where can they look to find out what features have it\nset by default?  Who calls this function, and what does that person or\ncode path do with the return value?  If it is not part of the gitweb\nconfiguration that an administrator might modify (the subject of this\nmanpage), why not just say that (\"subroutine used internally; present\nif and only if this feature can be made overridable with the\n\"override\" field; you should not change it\") and leave it at that?\n\n> +\n> +\n> +Features in `%feature`\n> +~~~~~~~~~~~~~~~~~~~~~~\n> +Below there are described gitweb features that are configurable via\n> +`%feature` hash.  For a complete list please consult gitweb sources.\n\nLanguage nit: \"Below there are described gitweb features ...\" -> \"The\ngitweb features ... are listed below\".  The second sentence could\nprobably be more apologetic, something like \"Currently the only\nauthoritative and complete list is in the comments in the gitweb.cgi\nsource code.\"\n\n> +\n> +blame::\n> +\tEnable the \"blame\" and \"blame_incremental\" blob views, showing for\n> +\teach line the last commit that modified it; see linkgit:git-blame[1].\n> +\tThis can be very CPU-intensive and is therefore disabled by default.\n> ++\n> +This feature can be configured on a per-repository basis via\n> +repository's `gitweb.blame` configuration variable (boolean).\n\nNice.\n\n> +\n> +snapshot::\n> +\tEnable and configure \"snapshot\" action, providing a compressed\n> +\tarchive of any tree or commit; see also linkgit:git-archive[1].\n> +\tThis can potentally generate high traffic if you have large project.\n> ++\n> +The value (of \\'default') is a list of names of snapshot formats\n> +defined in `%known_snapshot_formats` hash, that you wish to offer.\n> +Among supported formats are \"tgz\", \"tbz2\", \"txz\" (gzip/bzip2/xz\n> +compressed tar archive) and \"zip\"; please consult gitweb sources for\n> +a definitive list.  By default only \"tgz\" is offered.\n> ++\n> +This feature can be configured on a per-repository basis via\n> +repository's `gitweb.blame` configuration variable, which contains\n> +a comma separated list of formats, or \"none\" to disable snapshots.\n> +Unknown values will be ignored.\n\nLanguage nits: missing \"the\" before \"snapshot action\"; \"providing\"\nwould be clearer if replaced by \"which allows users to download\" or\n\"which serves\" or something like that; instead of \"see also\" it might\nbe nice to say \"as produced by\" because more precise; would be clearer\nwithout parentheses around \"of 'default'\"; missing comma before\n\"defined in the %known_snapshot_formats hash\"; \"Among supported\nformats are\" is clearer as \"Supported formats include\"; comma before\n\"or 'none' to disable snapshots\" is extraneous; \"will be ignored\"\nshould be \"are ignored\".\n\n> +\n> +grep::\n> +\tEnable grep search, which will list the files in currently selected\n> +\ttree (directory) containing the given string; see linkgit:git-grep[1].\n> +\tThis can be potentially CPU-intensive, of course.  Enabled by default.\n> ++\n> +This feature can be configured on a per-repository basis via\n> +repository's `gitweb.grep` configuration variable (boolean).\n\nLanguage nit: \"will list\" should be \"lists\".  Nice.\n\n> +\n> +pickaxe::\n> +\tEnable the so called pickaxe search, which will list the commits\n> +\tthat modified a given string in a file.  This can be practical and\n> +\tquite faster alternative to \"blame\" action, but still potentially\n> +\tCPU-intensive.  Enabled by default.\n> ++\n> +The pickaxe search is described in linkgit:git-log[1] (the\n> +description of `-S<string>` option, which refers to pickaxe entry in\n> +linkgit:gitdiffcore[7] for more details).\n> ++\n> +This feature can be configured on a per-repository basis via\n> +repository's `gitweb.pickaxe` configuration variable (boolean).\n\nI think \"modified\" means \"introduced or removed\" (as an approximation to\n\"changes the number of occurences of\").  Missing \"it is\" before \"still\npotentially CPU-intensive\".  \"via\" seems to mean \"using the\".\n\n(By the way, is there any way for the the very paranoid to limit the\nlength of regexes used or CPU time used per request, to get some\nreasonable cap on this sort of thing?  I guess that's more in the\nrealm of web server configuration than something gitweb should be\nresponsible for --- but if there's some common practice or well known\nreference on the topic, it could be worth mentioning at the top of\nthis GITWEB FEATURES section some day.)\n\n> +\n> +show-sizes::\n> +\tEnable showing size of blobs (ordinary files) in a \"tree\" view, in a\n> +\tseparate column, similar to what `ls -l` does; see description of\n> +\t`-l` option in linkgit:git-ls-tree[1] manpage.  This cost a bit of\n> +\tI/O.  Enabled by default.\n> ++\n> +This feature can be configured on a per-repository basis via\n> +repository's `gitweb.showsizes` configuration variable (boolean).\n\nNit: \"cost\" -> \"costs\".  Interesting (I guess packv4 will help with\nthe CPU [decompression] cost of this when it comes).\n\n> +\n> +patches::\n> +\tConfigure \"patches\" view, which displays list of commits in email\n> +\t(plain text) output format; see also linkgit:git-format-patch[1].\n> +\tThe value is the maximum number of patches in a patchset generated\n> +\tin \"patches\" view.  Set this to 0 or undef to disable patch view, or\n> +\tto a negative number to remove any limit.  Default value is 16.\n> ++\n> +This feature can be configured on a per-repository basis via\n> +repository's `gitweb.patches` configuration variable (integer).\n\n\"Configure\" -> \"Enable and configure\" and \"Set this to ...\" -> \"Set\nthe 'default' field to a list containing the single item ...\", I\nguess.  \n\n> +\n> +avatar::\n> +\tAvatar support.  When this feature is enabled, views such as\n> +\t\"shortlog\" or \"commit\" will display an avatar associated with\n> +\tthe email of the committer(s) and/or author(s).\n> ++\n> +Currently available providers are *\"gravatar\"* and *\"picon\"*.\n> +If an unknown provider is specified, the feature is disabled.\n> +*Note* that some provides might require extra Perl packages to be\n> +installed; see 'gitweb/INSTALL' for more details.\n\n\"commiter(s) and/or author(s)\" -> \"each committer and author\".\n\nIf I set 'default' to [\"gravator\", \"picon\", \"unknown\"], will that\nreally disable the feature?\n\n> ++\n> +This feature can be configured on a per-repository basis via\n> +repository's `gitweb.avatar` configuration variable.\n> ++\n> +See also `%avatar_size` with pixel sizes for icons and avatars\n> +(\"default\" is used for one-line like \"log\" and \"shortlog\", \"double\"\n> +is used for two-line like \"commit\", \"commitdiff\" or \"tag\").  If the\n> +default font sizes or lineheights are changed (e.g. via adding extra\n> +CSS stylesheet in `@stylesheets`), it may be appropriate to change\n> +these values.\n\nWhat is the syntax of the \"[gitweb] avatar\" value --- space delimited?\ncomma delimited?\n\n> +\n> +highlight::\n> +\tServer-side syntax hightlight support in \"blob\" view.  It requires\n> +\t`$highlight_bin` program available (see description of this variable\n> +\tin \"Configuration variables\" section above), and therefore is\n> +\tdisabled by default.\n> ++\n> +This feature can be configured on a per-repository basis via\n> +repository's `gitweb.highlight` configuration variable (boolean).\n\nLanguage nit: missing \"to be\" before \"available\", \"the\" before\n\"description\" and '\"Configuration variables\" section'; the comma\nbefore \"and\" is extraneous.\n\n> +\n> +remote_heads::\n> +\tEnable displaying remote heads (remote-tracking branches) in the \"heads\"\n> +\tlist.  In most cases it is unnecessary internal private detail, and it\n> +\tis therefore disabled by default.  linkgit:git-instaweb[1], which is\n> +\tusually used to browse local repositories, enables and uses this\n> +\tfeature.\n> ++\n> +This feature can be configured on a per-repository basis via\n> +repository's `gitweb.remote_heads` configuration variable (boolean).\n\nCould clarify that \"it\" means \"the list of remote-tracking branches\"\nfirst and then \"this feature\".  Missing \"an\" before \"irrelevant,\nprivate detail\".\n\n> +\n> +\n> +The list below presents features that do not allow project specific\n> +overrides.\n\nIf we consider it one list: \"The remaining features cannot be\noverridden on a per project basis\".\n\n> +\n> +search::\n> +\tEnable text search, which will list the commits which match author,\n> +\tcommitter or commit text to a given string; see description of\n> +\t`--author`, `--committer` and `--grep` options in linkgit:git-log[1]\n> +\tmanpage.  Enabled by default.\n> ++\n> +Project specific override is not supported.\n\nNice.  I prefer \"Enables\" over \"Enable\" so commands can be directed at\nthe reader only, but the current text is clear enough.  Missing \"the\"\nbefore \"descriptions\".\n\n> +\n> +forks::\n> +\tMake gitweb consider projects in subdirectories of project root\n> +\t(basename) to be forks of existing projects.  Given project\n> +\t`$projname.git`, projects matching `$projname/*.git` will not be\n> +\tshown in the main projects list, instead a \\'+' mark will be added\n> +\tto `$projname` there and a \"forks\" view will be enabled for the\n> +\tproject, listing all the forks.  If project list is taken from a\n> +\tfile, forks have to be listed after the main project.\n> ++\n> +Project specific override is not supported.\n\nTo avoid questions of who made it happen: \"If this feature is enabled,\ngitweb considers projects in subdirectories ...\".\n\nIf I understand correctly, \"Given project `$projname.git`, projects\nmatching `$projname/*.git`\" can be written as \"If the project\n`$projname.git` exists, projects in the `$projname/` directory\".  Is\nit just projects in that directory, or are subdirectories included, as\nin the following example?\n\n\tproject.git\n\tproject/foo/bar/baz/qux.git\n\nReplacing the comma before \"instead\" with a full stop, adding a\ncomma after \"instead\", and putting the sentence in the present tense\n(\"Instead, a '+' mark is shown next to `$projname` and links to a\n\"forks\" view that lists projects in the $projname/ subdirectory)\nseems to make it clearer.\n\nMissing \"the\" before \"project list\"; missing \"in that file\" after\n\"after the main project\"; \"have to be\" probably means \"are only\nrecognized if\".\n\n> +\n> +actions::\n> +\tInsert custom links to the action bar of all project pages.  This\n> +\tenables you to link to third-party scripts integrating into gitweb.\n> ++\n> +The \"default\" value consists of a list of triplets in the form\n> +`(\"<label>\", \"<link>\", \"<position>\")` where \"position\" is the label\n> +after which to insert the link, \"link\" is a format string where `%n`\n> +expands to the project name, `%f` to the project path within the\n> +filesystem, `%h` to the current hash (\\'h' gitweb parameter) and\n> +`%b` to the current hash base (\\'hb' gitweb parameter); `%%` expands\n> +to \\'%'.\n\nInteresting.  \"enables\" should be \"allows\" here.\n\nIs %f an absolute path (i.e., starting with '/')?\n\n> ++\n> +For example http://repo.or.cz git hosting site sets it to the\n> +following to enable graphical log (via third party tool\n> +*git-browser*):\n> ++\n> +----------------------------------------------------------------------\n> +$feature{'actions'}{'default'} =\n> +\t[ ('graphiclog', '/git-browser/by-commit.html?r=%n', 'summary')];\n> +----------------------------------------------------------------------\n> ++\n> +This adds link titled \"graphiclog\" after \"summary\" link, leading to\n> +`git-browser` script, passing `r=<project>` as a query parameter.\n\nMissing \", at the time this page was written, the\" after \"For\nexample\" (with \"sets\" replaced by \"set\" to match); \"via\" sounds\nmore natural when replaced by \"using the\"; missing \"a\" before \"link\";\nmissing \"the\" before \"summary link on the project listing and project\npages\".\n\n> ++\n> +Project specific override is not supported.\n> +\n> +timed::\n> +\tEnable displaying how much time and how many git commands it took to\n> +\tgenerate and display page in the page footer (at the bottom of\n> +\tpage).  For example it might be: \"This page took 6.53325 seconds and\n> +\t13 git commands to generate.\"  Disabled by default.\n> ++\n> +Project specific override is not supported.\n\nMissing \"each\" between \"display\" and \"page\".  \"it might be\" -> \"the\nfooter might contain\".\n\n> +\n> +javascript-timezone::\n> +\tEnable and configure ability to change common timezone for dates in\n> +\tgitweb output via JavaScript.  Dates in gitweb output include\n> +\tauthordate and comitterdate in \"commit\", \"commitdiff\" and \"log\"\n> +\tviews, and taggerdate in \"tag\" view.  Enabled by default.\n> ++\n> +Value is list of three values: default timezone (if client didn't\n> +select other timezone and saved it in a cookie), name of cookie\n> +where to store selected timezone, and CSS class used to mark up\n> +dates for manipulation.  If you want to turn it off, set \"default\"\n> +to empty list: `[]`.\n> ++\n\nLanguage nits: missing \"the\" before \"ability\", \"client\", and \"Value\";\nmissing \"a\" before \"common timezone\", \"list of three values\", \"default\ntimezone\", \"cookie name\", and \"HTML class name\" (why is this last one\nconfigurable?); \"change\" should probably be \"choose\"; missing \"for\nusers\" before \"to choose\"; \"didn't select other timezone\" -> \"hasn't\nselected some other timezone\"; missing \"for\" before \"if the client\nhasn't selected\"; \"turn it off\" would be clearer as \"turn this feature\noff\".\n\n> +In most case you would want to change only default timezone:\n> ++\n> +---------------------------------------------------------------------------\n> +$feature{'javascript-timezone'}{'default'}[0] = \"utc\";\n> +---------------------------------------------------------------------------\n\nNice.  \"In most case you would want to change only\" -> \"Typical gitweb\nconfig files will only change\" can take the desires of an admin that\nis implementing someone else's will out of the equation.\n\n> ++\n> +Timezone value can be \"local\" (for local timezone that browser uses), \"utc\"\n> +(what gitweb uses when JavaScript or this feature is disabled), or numerical\n> +timezone in the form of \"+/-HHMM\" for example \"+0200\".  This way is\n> +guaranteed to be backward compatibile.\n> ++\n> +Project specific override is not supported.\n\nLanguage nits: when we are talking about supported values in general,\nit sounds better for some reason with \"value\" -> values\"; \"numerical\ntimezone\" -> \"numerical timezones\"; \"for example\" -> \"such as\".\n\nWhat is \"This way\", and what other way should people be avoiding to\nprevent forward compatibility gotchas?\n\n> +\n> +\n> +EXAMPLES\n> +--------\n\nHoorah!\n\n[...]\n> +ENVIRONMENT\n> +-----------\n> +The location of per-instance and system-wide configuration files can be set\n> +using the following environment variables:\n\nClearer to say \"overridden\" to emphasize that these replace rather\nthan supplementing the locations described under FILES.\n\n[...]\n> +GITWEB_CONFIG::\n> +\tSets location of per-instance configuration file.\n[...]\n> +FILES\n> +-----\n> +gitweb_config.perl::\n> +\tThis is default value for per-instance configuration file.  The\n> +\tformat of this file is described above.\n> +/etc/gitweb.conf::\n> +\tThis is default value for fallback system-wide configuration\n> +\tfile.  This file is used only if per-instance configuration\n> +\tvariable is not found.\n> +/etc/gitweb-common.conf::\n> +\tThis is default value for common system-wide configuration\n> +\tfile.\n\n\"default value\" sounds strange here --- I guess I would have expected\nsomething more like\n\n ENVIRONMENT\n -----------\n ...\n GITWEB_CONFIG::\n\tPath to use to find the per-instance configuration file,\n\tinstead of gitweb_config.perl.  If relative, this is relative\n\tto $GITWEBDIR.\n\n FILES\n -----\n /etc/gitweb-common.conf::\n\tOptions to be shared by all gitweb instances.  The format is\n\tdescribed above.\n $GITWEBDIR/gitweb_config.perl::\n\tAdditional settings for a particular gitweb instance (in\n\tthe same format).\n /etc/gitweb.conf::\n\tFallback configuration file with settings for gitweb instances\n\tthat do not contain a gitweb_config.perl file.\n \n[...]\n> gitweb/README                 |  133 +-------\n[...]\n> +++ b/gitweb/README\n> @@ -41,139 +41,8 @@ Ultimate description on how to reconfigure the default features setting\n>  in your `GITWEB_CONFIG` or per-project in `project.git/config` can be found\n>  as comments inside 'gitweb.cgi'.\n>  \n> -See also the \"Gitweb config file\" (with an example of config file), and\n[...]\n> +See also gitweb.conf(5) manpage.\n> +\n\nThanks very much for this.\n"},{"id":"175889","messageId":"201109202211.06899.jnareb@gmail.com","threadId":"28418","inReplyTo":"20110919233703.GF6343@elie","subject":"Re: [PATCH/RFCv4 1/4] Documentation: Preparation for gitweb manpages","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2011-09-20T20:11:05Z","receivedAt":"2011-09-20T20:11:05Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Thanks again for all language fixes.  English is my secondary language...\n\nJonathan Nieder wrote:\n> Jakub Narebski wrote:\n\n> > The goal is to move documentation out of gitweb/README to gitweb.txt and\n> > gitweb.conf.txt manpages, reducing its size 10x from around 500 to\n> > around 50 lines (two pages), and move information not related drectly to\n> > building and installing gitweb out of gitweb/INSTALL there.\n> \n> I guess you mean this patch prepares for or is part of a larger\n> project or series with that goal? [...]\n\n[...]\n> > This way to build gitweb documentation one can use\n> >\n> >   make -C gitweb doc\n> >\n> > or\n> >\n> >   cd gitweb; make doc\n> \n> Language nit: a comma after \"This way\" would disambiguate.\n> \n> Does \"make -CDocumentation man html\" build the gitweb documentation,\n> too (and \"make install-doc\" install it)?\n\nJonathan Nieder wrote:\n\n>                                         Maybe its commit message could\n> be clarified to mention that the new targets build a subset of the pages\n> built by the ordinary \"make doc\" et al targets.\n\nI hope that this version is more clear:\n\n-- >8 --\nFrom: Jakub Narebski <jnareb@gmail.com>\nSubject: [PATCH/RFCv5 1/4] Documentation: Preparation for gitweb manpages\n\nGitweb documentation currently consists of gitweb/README, gitweb/INSTALL\nand comments in gitweb source code.  This is harder to find, use and\nbrowse than manpages (\"man gitweb\" or \"git help gitweb\") and HTML\ndocumentation (\"git help --web gitweb\").\n\nThe goal of the next two commits is to move documentation out of\ngitweb/README to gitweb.txt and gitweb.conf.txt manpages, reducing its\nsize 10x from around 500 to around 50 lines (two pages), and to move\ninformation not related directly to building and installing gitweb out\nof gitweb/INSTALL.\n\nThe idea is to have the gitweb manpage sources reside in AsciiDoc\nformat in the Documentation/ directory, like for gitk and git-gui.\nThis means that building git documentation (with \"make doc\") would\nalso build gitweb manpages.\n\nAn alternate solution would be to have gitweb documentation in the\ngitweb/ directory, perhaps in POD format (see perlpod(1)).\n\n\nThis patch adds infrastructure for easy generation of only\ngitweb-related manpages.  It adds a currently empty 'gitweb-doc'\ntarget to Documentation/Makefile, and a 'doc' proxy target to\ngitweb/Makefile.\n\nThis way to build only gitweb documentation in both 'man' and 'html'\nformats one can use\n\n  make -C gitweb doc\n\nor\n\n  cd gitweb; make doc\n\nThis somewhat follows the idea of 'full-svn-test' and 'gitweb-test' in\nt/Makefile.  Note also that with alternate solution, where source of\ngitweb manpages would reside in the gitweb/ directory, \"make doc\"\nwould invoke \"make -C gitweb doc\" to generate formatted docs.\n\nThe gitweb.conf(5) and gitweb(1) manpages will be added in subsequent\ncommits.\n\nSigned-off-by: Jakub Narebski <jnareb@gmail.com>\n---\n Documentation/Makefile |    3 +++\n gitweb/Makefile        |    7 ++++++-\n 2 files changed, 9 insertions(+), 1 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 6346a75..44be67b 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -170,6 +170,9 @@ info: git.info gitman.info\n \n pdf: user-manual.pdf\n \n+GITWEB_DOC = $(filter gitweb.%,$(DOC_HTML) $(DOC_MAN1) $(DOC_MAN5) $(DOC_MAN7))\n+gitweb-doc: $(GITWEB_DOC)\n+\n install: install-man\n \n install-man: man\ndiff --git a/gitweb/Makefile b/gitweb/Makefile\nindex 1c85b5f..3014d80 100644\n--- a/gitweb/Makefile\n+++ b/gitweb/Makefile\n@@ -174,6 +174,11 @@ test-installed:\n \tGITWEB_TEST_INSTALLED='$(DESTDIR_SQ)$(gitwebdir_SQ)' \\\n \t\t$(MAKE) -C ../t gitweb-test\n \n+### Documentation\n+\n+doc:\n+\t$(MAKE) -C ../Documentation gitweb-doc\n+\n ### Installation rules\n \n install: all\n@@ -187,5 +192,5 @@ install: all\n clean:\n \t$(RM) gitweb.cgi static/gitweb.min.js static/gitweb.min.css GITWEB-BUILD-OPTIONS\n \n-.PHONY: all clean install test test-installed .FORCE-GIT-VERSION-FILE FORCE\n+.PHONY: all clean install test test-installed doc .FORCE-GIT-VERSION-FILE FORCE\n \n-- \n1.7.6\n"},{"id":"175893","messageId":"20110920201953.GA11464@elie","threadId":"28418","inReplyTo":"201109202211.06899.jnareb@gmail.com","subject":"Re: [PATCH/RFCv4 1/4] Documentation: Preparation for gitweb manpages","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2011-09-20T20:19:53Z","receivedAt":"2011-09-20T20:19:53Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Jakub Narebski wrote:\n\n> I hope that this version is more clear:\n\nYep, it doesn't leave me confused any more.  Thanks, this looks good\n(and sorry for my carelessness in reading the patch before).\n"},{"id":"175895","messageId":"201109202233.58923.jnareb@gmail.com","threadId":"28418","inReplyTo":"20110920201953.GA11464@elie","subject":"Re: [PATCH/RFCv4 1/4] Documentation: Preparation for gitweb manpages","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2011-09-20T20:33:58Z","receivedAt":"2011-09-20T20:33:58Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Jonathan Nieder wrote:\n> Jakub Narebski wrote:\n> \n> > I hope that this version is more clear:\n> \n> Yep, it doesn't leave me confused any more.  Thanks, this looks good\n> (and sorry for my carelessness in reading the patch before).\n\nNo, your concern was valid.\n\nIt's better to be more explicit. \n\n-- \nJakub Narebski\nPoland\n"},{"id":"175995","messageId":"201109221541.49474.jnareb@gmail.com","threadId":"28418","inReplyTo":"20110920044118.GI6343@elie","subject":"Re: [PATCH/RFCv4 2/4] gitweb: Add manpage for /etc/gitweb.conf (for gitweb documentation)","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2011-09-22T13:41:48Z","receivedAt":"2011-09-22T13:41:48Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"On Tue, 20 Sep 2011, Jonathan Nieder wrote:\n> Jakub Narebski wrote:\n> \n> > [jn: Improved, extended, removed duplicate info from README]\n> \n> Hoorah!  I have very little to add to what's already been done ---\n> mostly I can just lend my ear as a native English speaker.\n\nThanks, that is a lot of help; English is not my primary language.\n\n> > +The syntax of the configuration files is that of Perl, as these files are\n> > +indeed handled as fragments of Perl code (the language that gitweb itself is\n> > +written in). Variables may be set using \"`our $variable = value`\"; text from\n> > +\"#\" character until the end of a line is ignored. See the *perlsyn*(1) man\n> > +page for more information.\n> > +\n> > +Actually using `our` qualifier in `our $variable = <value>;` is a safety\n> > +check: if newer gitweb does no longer use given variable, by using `our` we\n> > +won't get syntax errors.\n> \n> Language nit: for \"indeed\", something like \"internally\" might be more\n> natural.\n> \n> The syntax and the typical idiom were already described in the\n> DESCRIPTION section, so the emphasis should be somehow different here\n> to avoid boring the reader.  One way might be to plunge directly into\n> what the second paragraph above says:\n> \n>  The syntax of the configuration files is that of Perl, since these files are\n>  handled by sourcing them as fragments of Perl code (the language that\n>  gitweb itself is written in). Variables are typically set using the\n>  `our` qualifier (as in \"`our $variable = <value>;`\") to avoid syntax\n>  errors if a new version of gitweb no longer uses a variable and therefore\n>  stops declaring it.\n\nThanks, I used your proposal.  It reduces duplication, and reads better.\n \n> > +\n> > +You can include other configuration file using read_config_file()\n> > +subroutine.  For example, you can read defaults in fallback\n> > +system-wide GITWEB_CONFIG_SYSTEM from GITWEB_CONFIG by adding\n> > +\n> > +  read_config_file($GITWEB_CONFIG_SYSTEM);\n> > +\n> > +at very beginning of per-instance GITWEB_CONFIG file.  In this case\n> > +settings in said per-instance file will override settings from\n> > +system-wide configuration file.  Note that read_config_file checks\n> > +itself that the file it reads exists.\n[...]\n\n> The reader wonders: After checking that the file exists, what does\n> read_config_file do (does it silently skip it or error out)?  And why\n> would I use this trick instead of just writing a gitweb-common.conf\n> file?  (Was read_config_file introduced before gitweb-common.conf,\n> making this useful when creating a configuration that should be usable\n> with older versions of gitweb?)\n\nI have replaced it now with the following:\n\n  You can include other configuration file using read_config_file()\n  subroutine.  For example, one might want to put gitweb configuration\n  related to access control for viewing repositories via Gitolite (one\n  of git repository management tools) in a separate file, e.g. in\n  '/etc/gitweb-gitolite.conf'.  To include it, put\n  \n  --------------------------------------------------\n  read_config_file(\"/etc/gitweb-gitolite.conf\");\n  --------------------------------------------------\n  \n  somewhere in gitweb configuration file used, e.g. in per-installation\n  gitweb configuration file.  Note that read_config_file() checks itself\n  that the file it reads exists, and does nothing if it is not found.\n  It also handles errors in included file.\n\n> > +$project_maxdepth::\n> > +\tFilesystem traversing depth limit for recursively scanning for git\n> > +\trepositories, used if `$projects_list` (below) is unset.  The default\n> > +\tvalue of this variable is determined by build-time configuration\n> > +\tvariable `GITWEB_PROJECT_MAXDEPTH`, which defaults to 2007.\n> \n> \"Filesystem traversing depth limit\" is quite a long stack of nouns :),\n> and unfortunately I don't know what it means.  Is this the depth of\n> nested subdirectories below $project_root that gitweb will look at\n> when discovering repositories?  If I have no subdirectories in the\n> projectroot except the repositories themselves, should I set this to 1\n> or 0?  What happens with forks?  Is this just a convenience feature or\n> can it be used for security or to create performance gaurantees?\n> \n> By the way, what happens if projectroot contains a symlink to some\n> directory elsewhere in the filesystem containing repositories --- will\n> gitweb traverse it?\n\nI have changed order of describing variables, putting $projects_list\nbefore $project_maxdepth - this way we don't have to refer to following\ntext.\n\nI have replaced the description of $project_maxdepth with the following\n\n  $project_maxdepth::\n  \tIf `$projects_list` variable is unset, gitweb will recursively\n  \tscan filesystem for git repositories.  The `$project_maxdepth`\n  \tis used to limit traversing depth, relative to `$projectroot`\n  \t(starting point); it means that directories which are further\n  \tfrom `$projectroot` than `$project_maxdepth` will be skipped.\n  +\n  It is purely performance optimization, originally intended for MacOS X,\n  where recursive directory traversal is slow.  Gitweb follows symbolic\n  links, but it detects cycles, ignoring any duplicate files and directories.\n  +\n  The default value of this variable is determined by the build-time\n  configuration variable `GITWEB_PROJECT_MAXDEPTH`, which defaults to\n  2007.\n \nI hope that it makes meaning and use of this variable more clear.\n\n> What if I want this to be infinite (i.e., to disable the feature) ---\n> would I be crazy?\n\nIt is currently not possible to disable this feature.  The value of 2007\nshould be enough in most cases (read: all sane cases).\n \n> > +$projects_list::\n> > +\tPlain text file listing projects or name of directory\n> > +\tto be scanned for projects.\n[...]\n\n> When this is a relative path, what is it taken relative to?\n\nAs with all relative paths to files, it is relative to where CGI script\nis.  I probably should write about this somewhere...\n\n> > +\n> > +$export_ok::\n> > +\tShow repository only if this file exists (in repository).  Only\n> > +\teffective if this variable evaluates to true.  Can be set during\n> > +\tbuilding gitweb via `GITWEB_EXPORT_OK`.  [No default / Not set]\n> \n> This is always a relative path, right?  What is it relative to ---\n> $GIT_DIR, I guess?\n> \n> Usage nits: the phrase starting with \"during\" reads more naturally if\n> \"during\" is replaced with \"when\" and \"via\" replaced with \"by setting\".\n> If there were no default, that would mean that gitweb errors out when\n> gitweb.conf does not set this variable; instead, the default seems to\n> be \"undef\" (or 'false') if I understand correctly.\n\nDescription of $export_ok got replaced by the following:\n\n  $export_ok::\n  \tShow repository only if this file exists (in repository).  Only\n  \teffective if this variable evaluates to true.  Can be set when\n  \tbuilding gitweb by setting `GITWEB_EXPORT_OK`.  This path is\n  \trelative to `GIT_DIR`.  git-daemon[1] uses 'git-daemon-export-ok',\n  \tunless started with `--export-all`.  [No default / Not set\n  \t(this feature is turned off)]\n\n> > +\n> > +$export_auth_hook::\n> > +\tShow repository only if this subroutine returns true, when given as\n> > +\tthe only parameter the full path to the project.  Example:\n> > ++\n> > +----------------------------------------------------------------------------\n> > +our $export_auth_hook = sub { return -e \"$_[0]/git-daemon-export-ok\"; };\n> > +----------------------------------------------------------------------------\n> > ++\n> > +though the above might be done by using `$export_ok` instead\n> > ++\n> > +----------------------------------------------------------------------------\n> > +our $export_ok = \"git-daemon-export-ok\";\n> > +----------------------------------------------------------------------------\n> \n> Style nit: commands in this kind of documentation should be directed to\n> the reader, not gitweb, so it would be nicer to explain this in terms of\n> what the $export_auth_hook is.\n\nThanks.  I should probably rewrite description of $export_ok in the same\nway, isn't it?\n\n>                                 That is, something like the following: \n> \n>  $export_auth_hook::\n> \tFunction used to determine which repositories should be shown.\n> \tThis subroutine should take one parameter, the full path to\n> \ta project, and if it returns true, that project will be included\n> \tin the projects list and can be accessed through gitweb as long\n> \tas it fulfills the other requirements described by $export_ok,\n> \t$projects_list, and $projects_maxdepth.  Example:\n\nThanks, I have used your description.\n \n> Is \"our $export_auth_hook = undef;\" a valid configuration?  What is the\n> default?\n\nI have added the following line at the end of description of this\nvariable:\n\n  If not set (default), it means that this feature is disabled.\n\n> > +\n> > +$strict_export::\n> > +\tOnly allow viewing of repositories also shown on the overview page.\n> > +\tThis for example makes `$gitweb_export_ok` file decide if repository is\n> > +\tavailable and not only if it is shown.  If `$gitweb_list` points to\n> > +\tfile with list of project, only those repositories listed would be\n> > +\tavailable for gitweb.  Can be set during building gitweb via\n> > +\t`GITWEB_STRICT_EXPORT`.  [No default / Not set]\n> \n> Is the default behavior as though this were true or false?\n\nLast sentence now reads:\n\n  [No default / Not set (you can access\trepositories hidden from projects\n  list page)]\n\n> > +Finding files\n> > +~~~~~~~~~~~~~\n> > +Those configuration variables tell gitweb where to find files.  Values of\n> > +those variables are paths on filesystem.  Of those only `$GIT` is required\n> > +to be (correctly) set for gitweb to be able to work; all the rest are\n> > +required only for extra configuration or extra features.\n[...]\n> When you say the remainder are only required in special cases, does\n> that mean that they are ignored unless some other enabling variable is\n> set or that they can be set to \"undef\" to disable the relevant\n> feature?\n\nI have removed this sequence, and extended description of each variable\ninstead.\n \n> > +$mimetypes_file::\n> > +\tFile to use for (filename extension based) guessing of MIME types before\n> > +\ttrying '/etc/mime.types'.  Path, if relative, is taken currently as\n> > +\trelative to the current git repository.  [Unset by default]\n\n> The use of \"currently\" sounds like an apology.  Does that mean that\n> gitweb ought to be rejecting relative paths for this variable?\n\nI think it was originally intended as note that this resolution of relative\npath is subject to change in future versions of gitweb.  But I think it\nis not true (backward compatibility), and it is more important that this\nresolution of relative path is untypical.\n\nI have reformulated this description to read:\n\n  $mimetypes_file::\n  \tFile to use for (filename extension based) guessing of MIME types before\n  \ttrying '/etc/mime.types'.  *NOTE* that this path, if relative, is taken\n  \tas relative to the current git repository, not to CGI script.  If unset,\n  \tonly '/etc/mime.types' is used (if present on filesystem).  If no mimetypes\n  \tfile is found, mimetype guessing bassed on extension of file is disabled.\n  \t[Unset by default]\n \n> > +\n> > +$highlight_bin::\n> > +\tPath to the highlight executable to use (must be the one from\n> > +\thttp://www.andre-simon.de due to assumptions about parameters and output).\n> > +\tUseful if 'highlight' is not installed on your webserver's PATH.\n> > +        [Default: 'highlight']\n> > ++\n> > +*NOTE*: if you want to add support for new syntax (supported by\n> > +\"highlight\" but not used by gitweb), you need to modify `%highlight_ext`\n> > +or `%highlight_basename`, depending on whether you detect type of file\n> > +based on extension (for example \"*.sh\") or on its basename (for example\n> > +\"Makefile\").  Keys of those hashes are extension or basename,\n> > +respectively, and value for given key is name of syntax to be passed via\n> > +`--syntax <syntax>` to highlighter.\n[...]\n\n> Is \"*.sh\" actually an example of an extension?  I.e., do I write the\n> following?\n> \n> \tour %highlight_ext;\n> \t$highlight_ext{\"*.sh\"} = \"sh\";\n\nYou are right, it should be \"sh\", not \"*.sh\".  Fixed, and added example\n(about \"phtml\", which usually means PHP, but might mean embedded Perl\n(ePerl)).\n\n> > +Links and their targets\n> > +~~~~~~~~~~~~~~~~~~~~~~~\n> > +Configuration variables described below configure some of gitweb links:\n> > +their target and their look (text or image), and where to find page\n> > +prerequisites (stylesheet, favicon, images, scripts).  Usually they are left\n> > +at their default values, with the possible exception of `@stylesheets`\n> > +variable.\n> \n> Language nits: missing \"The\" before \"Configuration variables described\n> below\"; missing \"some\" before \"supporting files\".\n                                ^^^^^^^^^^^^^^^^^^---???  \n \n> > +\n> > +@stylesheets::\n> > +\tList of URIs of stylesheets (relative to base URI of a page). You\n> > +\tmight specify more than one stylesheet, for example use gitweb.css\n> > +\tas base, with site specific modifications in separate stylesheet\n> > +\tto make it easier to upgrade gitweb. You can add a `site` stylesheet\n> > +\tfor example by putting\n> > ++\n> > +----------------------------------------------------------------------------\n> > +push @stylesheets, \"gitweb-site.css\";\n> > +----------------------------------------------------------------------------\n> > ++\n> > +in the gitweb config file.  Those values that are relative paths, are\n> > +relative to base URI of gitweb.\n> \n> [...]  What is a base URI --- is it set by another variable?\n\nBase URI is a concept defined in HTML / XHTML specification (or in URI\ndefinition), so I'd rather not explain it here.\n\n\n> > +This list should contain URI of gitweb's stylesheet.  The URI of gitweb\n> > +stylesheet is set during build time via `GITWEB_CSS` variable.  It's default\n> > +value is 'static/gitweb.css' (or 'static/gitweb.min.css' if the `CSSMIN`\n> > +variable is defined, i.e. if CSS minifier is used during build).\n> > ++\n> > +*Note*: there is also legacy `$stylesheet` configuration variable, which was\n> > +used by older gitweb.\n[...]\n> If I am new on the job and find the $stylesheet variable set, what\n> should I interpret it to mean?  How can it be translated to the newer\n> @stylesheets style?  What happens if both variables are set --- does\n> one override the other, or are they combined somehow?\n\nAdded\n\n  If `$stylesheet` variable is defined, only CSS stylesheet\n  given by this variable is used by gitweb.\n\nI hope that old config files that define this variable are rare.\n\n> > +$home_link::\n> > +\tTarget of the home link on top of all pages (the first part of view\n> > +\t\"breadcrumbs\").  By default set to absolute URI of a page ($my_uri).\n\n> Which page does \"a page\" refer to here (doesn't $my_uri change from\n> request to request)?\n\nI have extended last sequence of this description to read:\n\n  By default it is set to the absolute URI of a current page\n  (to the value of `$my_uri` variable, or to \"/\" if `$my_uri` is undefined\n  or is an empty string).\n \n$my_uri changes from request to request, and $home_link too.\n\nBy default config is re-read on each request; if not, one should\nuse $per_request_config subroutine to set this variable if it changes\nfrom request to request.\n\n> > +$default_projects_order::\n> > +\tDefault value of ordering of projects on projects list page.  Valid\n> > +\tvalues are \"none\" (unsorted), \"project\" (by project name, i.e. path\n> > +\tto repository relative to `$projectroot`), \"descr\" (project\n> > +\tdescription), \"owner\", and \"age\" (by date of most current commit).\n> > ++\n> > +Default value is \"project\".  Unknown value means unsorted.\n> \n> What does \"Default\" mean here (i.e., what overrides it)?\n\nAdded\n\n  [...], which means the ordering used if you don't explicitly sort\n  projects list (if there is no \"o\" CGI query parameter in the URL).\n \n> > +\n> > +\n> > +Changing gitweb behavior\n> > +~~~~~~~~~~~~~~~~~~~~~~~~\n> > +Those configuration variables control _internal_ gitweb behavior.\n> \n> [...] Does internal behavior mean \"functionality as opposed to\n> appearance and input location\" or something like that?\n\nYes, it does.\n\n> > +\n> > +$default_blob_plain_mimetype::\n> > +\tDefault mimetype for blob_plain (raw) view, if mimetype checking\n> > +\tdoesn't result in some other type; by default \"text/plain\".\n[...]\n\n> Where can I look to read more about mimetype autodetection?\n\nAdded the following sentence:\n\n  \tGitweb guesses mimetype of a file to display based on extension\n  \tof its filename, using `$mimetypes_file` (if set and file exists)\n  \tand '/etc/mime.types' files (see *mime.types*(5) manpage; only\n  \tfilename extension rules are supported by gitweb).\n \n> > +@diff_opts::\n> > +\tRename detection options for git-diff and git-diff-tree. By default\n> > +\t(\\'-M'); set it to (\\'-C') or (\\'-C', \\'-C') to also detect copies,\n> > +\tor set it to () i.e. empty list if you don't want to have renames\n> > +\tdetection.\n[...]\n\n> Probably worth mentioning that GNU patch still has problems with some\n> rename patches, especially when they involve file copies ['-C'] or\n> criss-cross renames ['-B'] (see [1] and [2], for example).\n> \n> [1] http://savannah.gnu.org/bugs/?31058\n> [2] http://thread.gmane.org/gmane.linux.ports.sh.devel/8697/focus=8773\n\nI have added the following paragraph:\n\n  +\n  *Note* that rename and especially copy detection can be quite\n  CPU-intensive.  Note also that non git tools can have problems with\n  patches generated with options mentioned above, especially when they\n  involve file copies (\\'-C') or criss-cross renames (\\'-B').\n\n\n> > +@git_base_url_list::\n> > +\tList of git base URLs used for URL to where fetch project from, shown\n> > +\tin project summary page.  Full URL is \"`$git_base_url/$project`\".  You\n> > +\tcan setup multiple base URLs (for example one for `git://` protocol\n> > +\taccess, and one for `http://` \"dumb\" protocol access).  Note that per\n> > +\trepository configuration can be set in '$GIT_DIR/cloneurl' file, or as\n> > +\tvalues of multi-value `gitweb.url` configuration variable in project\n> > +\tconfig.\n> > ++\n> > +You can setup one single value (single entry/item in this list) during\n> > +building by using `GITWEB_BASE_URL` built-time configuration variable.\n> > +[No default]\n> \n> Language nits: \"git base URLs used for URL to where fetch project from\"\n> means something like \"Git URLs relative to which projects can be\n> fetched\"; [...]\n\n[...]\n> Is the per repository cloneurl added to this list, or does it override\n> it?\n\nI have rewritten it to hopefully more clear version, and added information\nabout precedence of cloneurl and the like:\n\n  @git_base_url_list::\n  \tList of git base URLs.  These URLs are used to generate URLs\n  \tdescribing from where to fetch a project, which are shown on\n  \tproject summary page.  The full fetch URL is \"`$git_base_url/$project`\",\n  \tfor each element of this list. You can set up multiple base URLs\n  \t(for example one for `git://` protocol, and one for `http://`\n  \tprotocol).\n  +\n  Note that per repository configuration can be set in '$GIT_DIR/cloneurl'\n  file, or as values of multi-value `gitweb.url` configuration variable in\n  project config.  Per-repository configuration takes precedence over value\n  composed from `@git_base_url_list` elements and project name.\n  +\n  You can setup one single value (single entry/item in this list) at build\n  time by setting the `GITWEB_BASE_URL` built-time configuration variable.\n  [Default: (), i.e. empty list]\n\n> > +$maxload::\n> > +\tUsed to set the maximum load that we will still respond to gitweb queries.\n> > +\tIf server load exceed this value then return \"503 Service Unavailable\"\n> > +\terror. Server load is taken to be 0 if gitweb cannot determine its value.\n> > +\tSet it to undefined value to turn it off. [Default: 300]\n> \n> Probably worth spelling out that this is a \"load average\" (as shown by uptime(1)).\n\nI have added the following sentence to describe it:\n\n  Currently it works only on Linux,\n  where it uses '/proc/loadavg'; the load there is the number of active\n  tasks on the system -- processes that are actually running -- averaged\n  over the last minute.\n \n\n> > +$per_request_config::\n> > +\tIf set to code reference, it would be run once per each request.  You can\n> > +\tset parts of configuration that change per session, e.g. by adding\n> > +\tthe following code to gitweb configuration file\n> > ++\n> > +--------------------------------------------------------------------------------\n> > +our $per_request_config = sub {\n> > +\t$ENV{GL_USER} = $cgi->remote_user || \"gitweb\";\n> > +};\n> > +--------------------------------------------------------------------------------\n> \n> Language nits: missing \"this is\" before \"set to a code reference\";\n> \"would\" should be \"will\" (those crazy English conditionals again); the\n> appropriate preposition before \"each request\" is \"for\", not \"per\";\n> missing \"this way\" after \"change per session\"; would be clearer with a\n> full stop before the example, and with the example made into a full\n> sentence (\"For example, one might use the following code in a gitweb\n> configuration file:\").\n> \n> > ++\n> > +Otherwise it is treated as boolean value: if true gitweb would process\n> > +config file once per request, if false it would process config file only\n> > +once.  [Default: true]\n> > ++\n> > +*NOTE*: `$my_url`, `$my_uri`, and `$base_url` are overwritten with their default\n> > +values before every request, so if you want to change them, be sure to set\n> > +this variable to true or a code reference effecting the desired changes.\n> \n> At this point, I've forgotten what the \"Otherwise\" is contrasting with;\n> probably best to repeat it (\"If $per_request_config is not a code\n> reference, it is interpreted as a boolean value.\"); \"would\" should be\n> \"will\" again (2x); missing \"the\" or \"each\" before \"config file\" (2x);\n> missing \"and\" before \"if it is false\"; \"it\" could be \"gitweb\" to\n> avoid confusion in this pronoun-heavy sentence; missing \"each time it\n> is executed\" after \"process the config file only once\".\n> \n> Probably worth mentioning that this variable starts to shine when one\n> gitweb instance is used to serve multiple requests, with CGI\n> replacements like mod_perl, fastcgi, plackup, and so on.\n\nI have rewritten and extended it as following:\n\n  If `$per_request_config` is not a code reference, it is interpreted as boolean\n  value.  If it is true gitweb will process config files once per request,\n  and if it is false gitweb will process config files only once, each time it\n  is executed.  [Default: true]\n  +\n  *NOTE*: `$my_url`, `$my_uri`, and `$base_url` are overwritten with their default\n  values before every request, so if you want to change them, be sure to set\n  this variable to true or a code reference effecting the desired changes.\n  +\n  This variable matters only when using persistent web environments that\n  serve multiple requests using single gitweb instance, like mod_perl,\n  FastCGI or Plackup.\n\n> > +$version::\n> > +\tGitweb version, set automatically when creating gitweb.cgi from\n> > +\tgitweb.perl. You might want to modify it if you are running modified\n> > +\tgitweb, for example \n> > ++\n> > +---------------------------------------------------\n> > +our $version .= \" with caching\";\n> > +---------------------------------------------------\n> \n> Might be worth mentioning this is only used in HTML comments and the\n> \"generator\" metadata field, nothing more special than that.\n\nAdded:\n\n  This variable is purely informational, used e.g. in the \"generator\"\n  meta header in HTML header.\n \n> > +\n> > +$my_url::\n> > +$my_uri::\n> > +\tFull URL and absolute URL of gitweb script;\n> > +\tin earlier versions of gitweb you might have need to set those\n> > +\tvariables, now there should be no need to do it.  See\n> > +\t`$per_request_config` if you need to set them still.\n[...]\n\n> What is the difference between a full URL and an absolute URL?\n\nFull URL is e.g. 'http://git.example.com/gitweb.cgi', while absolute URL\nis e.g. '/gitweb.cgi'.\n\n> > +sub::\n> > +\tSubroutine that will be called with default options as parameters to\n> > +\texamine per-repository configuration, but only if feature is\n> > +\toverridable (\\'override' is set to true).  If not present then\n> > +\tper-repository override for given feature is not supported.\n> > ++\n> > +You wouldn't need to ever change it in gitweb config file.\n> \n> Language nits: \"default options as parameters\" means \"the array\n> referred to by the 'default' field as parameter list\", I guess.\n> Missing \"the\" before \"feature is overridable\" and \"gitweb\n> configuration files\".  \"given feature\" -> \"this feature\".  \"not\n> supported\" -> \"not enabled\", maybe.\n> \n> Actually, I'm not sure I understand this one.  Are users supposed to\n> set this field?  Where can they look to find out what features have it\n> set by default?  Who calls this function, and what does that person or\n> code path do with the return value?  If it is not part of the gitweb\n> configuration that an administrator might modify (the subject of this\n> manpage), why not just say that (\"subroutine used internally; present\n> if and only if this feature can be made overridable with the\n> \"override\" field; you should not change it\") and leave it at that?\n\nChanged this to:\n\n  sub::\n  \tInternal detail of implementation.  What is important is that\n  \tif this field is not present then per-repository override for\n  \tgiven feature is not supported.\n  +\n  You wouldn't need to ever change it in gitweb config file.\n \n> > +\n> > +\n> > +Features in `%feature`\n> > +~~~~~~~~~~~~~~~~~~~~~~\n> > +Below there are described gitweb features that are configurable via\n> > +`%feature` hash.  For a complete list please consult gitweb sources.\n> \n> Language nit: \"Below there are described gitweb features ...\" -> \"The\n> gitweb features ... are listed below\".  The second sentence could\n> probably be more apologetic, something like \"Currently the only\n> authoritative and complete list is in the comments in the gitweb.cgi\n> source code.\"\n\nReformulated it to read:\n\n  The gitweb features that are configurable via `%feature` hash are listed\n  below.  This should be a complete list, but ultimately the authoritative\n  and complete list is in gitweb.cgi source code, with features described\n  in the comments.\n\n> > +pickaxe::\n> > +\tEnable the so called pickaxe search, which will list the commits\n> > +\tthat modified a given string in a file.  This can be practical and\n> > +\tquite faster alternative to \"blame\" action, but still potentially\n> > +\tCPU-intensive.  Enabled by default.\n> > ++\n> > +The pickaxe search is described in linkgit:git-log[1] (the\n> > +description of `-S<string>` option, which refers to pickaxe entry in\n> > +linkgit:gitdiffcore[7] for more details).\n> > ++\n> > +This feature can be configured on a per-repository basis via\n> > +repository's `gitweb.pickaxe` configuration variable (boolean).\n> \n> I think \"modified\" means \"introduced or removed\" (as an approximation to\n> \"changes the number of occurences of\").\n\nIt is even more correct with respect to mechanism behind '-S' option.\n\n> (By the way, is there any way for the the very paranoid to limit the\n> length of regexes used or CPU time used per request, to get some\n> reasonable cap on this sort of thing?  I guess that's more in the\n> realm of web server configuration than something gitweb should be\n> responsible for --- but if there's some common practice or well known\n> reference on the topic, it could be worth mentioning at the top of\n> this GITWEB FEATURES section some day.)\n\nI don't know if it is possible to limit CPU time used per request.\nI think most of time is spent in git commands; gitweb currently doesn't\noffer any way to renice or limit time of running git commands.  The\nonly load-related mechanism is $maxload.\n\n> > +show-sizes::\n> > +\tEnable showing size of blobs (ordinary files) in a \"tree\" view, in a\n> > +\tseparate column, similar to what `ls -l` does; see description of\n> > +\t`-l` option in linkgit:git-ls-tree[1] manpage.  This cost a bit of\n> > +\tI/O.  Enabled by default.\n> > ++\n> > +This feature can be configured on a per-repository basis via\n> > +repository's `gitweb.showsizes` configuration variable (boolean).\n> \n> Nit: \"cost\" -> \"costs\".  Interesting (I guess packv4 will help with\n> the CPU [decompression] cost of this when it comes).\n\nNb. the fast that directory entries ('tree' objects) do not have their\nsize displayed was result of request from people working on packv4, where\n'tree' objects would be stored decomposed, and calculating object size\nfor a 'tree' object will be quite costly.\n\nAdd to that the fact that 'tree' object size is not very interesting...\n \n> > +avatar::\n> > +\tAvatar support.  When this feature is enabled, views such as\n> > +\t\"shortlog\" or \"commit\" will display an avatar associated with\n> > +\tthe email of the committer(s) and/or author(s).\n> > ++\n> > +Currently available providers are *\"gravatar\"* and *\"picon\"*.\n> > +If an unknown provider is specified, the feature is disabled.\n> > +*Note* that some provides might require extra Perl packages to be\n> > +installed; see 'gitweb/INSTALL' for more details.\n[...]\n\n> If I set 'default' to [\"gravator\", \"picon\", \"unknown\"], will that\n> really disable the feature?\n\nOnly one provider at a time can be selected; I have added this\ninformation to description.\n \n\n> > +forks::\n> > +\tMake gitweb consider projects in subdirectories of project root\n> > +\t(basename) to be forks of existing projects.  Given project\n> > +\t`$projname.git`, projects matching `$projname/*.git` will not be\n> > +\tshown in the main projects list, instead a \\'+' mark will be added\n> > +\tto `$projname` there and a \"forks\" view will be enabled for the\n> > +\tproject, listing all the forks.  If project list is taken from a\n> > +\tfile, forks have to be listed after the main project.\n> > ++\n> > +Project specific override is not supported.\n[...]\n\n> If I understand correctly, \"Given project `$projname.git`, projects\n> matching `$projname/*.git`\" can be written as \"If the project\n> `$projname.git` exists, projects in the `$projname/` directory\".  Is\n> it just projects in that directory, or are subdirectories included, as\n> in the following example?\n> \n> \tproject.git\n> \tproject/foo/bar/baz/qux.git\n\nYes, they are.\n\nThe new improved and extended version is now:\n\n  forks::\n  \tIf this feature is enabled, gitweb considers projects in\n  \tsubdirectories of project root (basename) to be forks of existing\n  \tprojects.  For each project `$projname.git`, projects in the\n  \t`$projname/` directory and its subdirectories will not be\n  \tshown in the main projects list.  Instead, a \\'+' mark is shown\n  \tnext to `$projname`, which links to a \"forks\" view that lists all\n  \tthe forks (all projects in `$projname/` subdirectory).  Additionally\n  \ta \"forks\" view for a project is linked from project summary page.\n  +\n  If the project list is taken from a file (`$projects_list` points to a\n  file), forks are only recognized if they are listed after the main project\n  in that file.\n  +\n  Project specific override is not supported.\n\n> > +\n> > +actions::\n> > +\tInsert custom links to the action bar of all project pages.  This\n> > +\tenables you to link to third-party scripts integrating into gitweb.\n> > ++\n> > +The \"default\" value consists of a list of triplets in the form\n> > +`(\"<label>\", \"<link>\", \"<position>\")` where \"position\" is the label\n> > +after which to insert the link, \"link\" is a format string where `%n`\n> > +expands to the project name, `%f` to the project path within the\n> > +filesystem, `%h` to the current hash (\\'h' gitweb parameter) and\n> > +`%b` to the current hash base (\\'hb' gitweb parameter); `%%` expands\n> > +to \\'%'.\n> \n> Interesting.  \"enables\" should be \"allows\" here.\n\nRight.\n \n> Is %f an absolute path (i.e., starting with '/')?\n \nIt is \"$projectroot/$project\" (which I have added to this description).\n\n> > +In most case you would want to change only default timezone:\n> > ++\n> > +---------------------------------------------------------------------------\n> > +$feature{'javascript-timezone'}{'default'}[0] = \"utc\";\n> > +---------------------------------------------------------------------------\n[...]\n> > +Timezone value can be \"local\" (for local timezone that browser uses), \"utc\"\n> > +(what gitweb uses when JavaScript or this feature is disabled), or numerical\n> > +timezone in the form of \"+/-HHMM\" for example \"+0200\".  This way is\n> > +guaranteed to be backward compatibile.\n> > ++\n> > +Project specific override is not supported.\n> \n> Language nits: when we are talking about supported values in general,\n> it sounds better for some reason with \"value\" -> values\"; \"numerical\n> timezone\" -> \"numerical timezones\"; \"for example\" -> \"such as\".\n> \n> What is \"This way\", and what other way should people be avoiding to\n> prevent forward compatibility gotchas?\n \n\"This way\" refers to the example configuration.  I have reformulated\nthis description by removing last sentence, and adding\n\n  +\n  The example configuration presented here is guaranteed to be backwards\n  and forward compatible.\n\njust after example.\n\n\n> [...]\n> > +GITWEB_CONFIG::\n> > +\tSets location of per-instance configuration file.\n> [...]\n> > +FILES\n> > +-----\n> > +gitweb_config.perl::\n> > +\tThis is default value for per-instance configuration file.  The\n> > +\tformat of this file is described above.\n> > +/etc/gitweb.conf::\n> > +\tThis is default value for fallback system-wide configuration\n> > +\tfile.  This file is used only if per-instance configuration\n> > +\tvariable is not found.\n> > +/etc/gitweb-common.conf::\n> > +\tThis is default value for common system-wide configuration\n> > +\tfile.\n> \n> \"default value\" sounds strange here --- I guess I would have expected\n> something more like\n> \n>  ENVIRONMENT\n>  -----------\n>  ...\n>  GITWEB_CONFIG::\n> \tPath to use to find the per-instance configuration file,\n> \tinstead of gitweb_config.perl.  If relative, this is relative\n> \tto $GITWEBDIR.\n> \n>  FILES\n>  -----\n>  /etc/gitweb-common.conf::\n> \tOptions to be shared by all gitweb instances.  The format is\n> \tdescribed above.\n>  $GITWEBDIR/gitweb_config.perl::\n> \tAdditional settings for a particular gitweb instance (in\n> \tthe same format).\n>  /etc/gitweb.conf::\n> \tFallback configuration file with settings for gitweb instances\n> \tthat do not contain a gitweb_config.perl file.\n\nI'll think about this proposal.\n\nFor now I have just changed \"default value for ...\" to\n\"default name of ...\".\n  \n\nThank you very much for your feedback.\n\n-- \nJakub Narebski\nPoland\n"}]}