gitweb: document $per_request_config better

Global variables $my_url, $my_uri and $base_url have subtle interactions
that need to be desribed, and can be influenced most cleanly by
$per_request_config.

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Acked-by: Jakub Narebski <jnareb@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/gitweb/README b/gitweb/README
index 6646fdaed01b358bf8f3212dad9638667096754e..4a673933acee475dc423007063d1300b44176a61 100644 (file)
--- a/gitweb/README
+++ b/gitweb/README
@@ -177,13 +177,15 @@ not include variables usually directly set during build):
  * $my_url, $my_uri
    Full URL and absolute URL of gitweb script;
    in earlier versions of gitweb you might have need to set those
  * $my_url, $my_uri
    Full URL and absolute URL of gitweb script;
    in earlier versions of gitweb you might have need to set those

-   variables, now there should be no need to do it.
+   variables, now there should be no need to do it.  See
+   $per_request_config if you need to set them still.

  * $base_url
    Base URL for relative URLs in pages generated by gitweb,
    (e.g. $logo, $favicon, @stylesheets if they are relative URLs),
    needed and used only for URLs with nonempty PATH_INFO via
    <base href="$base_url">.  Usually gitweb sets its value correctly,
    and there is no need to set this variable, e.g. to $my_uri or "/".
  * $base_url
    Base URL for relative URLs in pages generated by gitweb,
    (e.g. $logo, $favicon, @stylesheets if they are relative URLs),
    needed and used only for URLs with nonempty PATH_INFO via
    <base href="$base_url">.  Usually gitweb sets its value correctly,
    and there is no need to set this variable, e.g. to $my_uri or "/".

+   See $per_request_config if you need to set it anyway.

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


@@ -252,7 +254,10 @@ not include variables usually directly set during build):
      sub { $ENV{GL_USER} = $cgi->remote_user || "gitweb"; }
    Otherwise it is treated as boolean value: if true gitweb would process
    config file once per request, if false it would process config file only
      sub { $ENV{GL_USER} = $cgi->remote_user || "gitweb"; }
    Otherwise it is treated as boolean value: if true gitweb would process
    config file once per request, if false it would process config file only

-   once.  The default is true.
+   once.  Note: $my_url, $my_uri, and $base_url are overwritten with
+   their default values before every request, so if you want to change
+   them, be sure to set this variable to true or a code reference effecting
+   the desired changes.  The default is true.

 
 Projects list file format
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Projects list file format
 ~~~~~~~~~~~~~~~~~~~~~~~~~