Re: [PATCH/WIP] Starting work on a man page for /etc/gitweb.conf

On Thu, 12 May 2011, Drew Northup wrote:

On Thu, 2011-05-12 at 20:08 +0200, Jakub Narebski wrote:

quoted

On Wed, 11 May 2011, Drew Northup wrote:

quoted

quoted

+
+The syntax of the configuration files is that of PERL, as these files are
+indeed handled as fragments of PERL code (the language that gitweb itself is
+written in). Variables may be set using "'our $variable = value'"; text from
+"#" character until the end of a line is ignored.

I think it would be nice to have an example here, something like:

-----
our $site_name = 'My Gitweb'; # or 'localhost'
-----

Looks reasonable to me...

Well, this is very much off the cuff example; I hope for a better example,
though it doesn't matter much here...

quoted

quoted

                                                   See the perlsyn(1) man page 
+for more information.

Is this how other manpages should be referenced in AsciiDoc?

Shouldn't we use some 'link:perlsyn[1]' or something like that here?

quoted

BTW. What is –, and could we write it using something more readable?

That's an en dash. A lot of people write it "blah - blah," but that's
not typographically correct (and asciidoc isn't nice enough to fix it
for us, as that would likely mess something else up). It compiles
properly into both HTML and manpages. I didn't think that dropping the
UTF-8 character into the asciidoc sources would go over well.

Doesn't AsciiDoc convert '--' to en-dash?  If not, perhaps adding 
appropriate definition to Documentation/asciidoc.conf and using "{endash}"
instead of "–" would be a better solution.

quoted

quoted

+CONFIGURATION SETTINGS
+----------------------
+Standard Options
+~~~~~~~~~~~~~~~~~
+The following are not typically set or overridden at build time:

Hmmm... There are four kinds of configuration variables:

Thank you for this extraction & table.

Note that some of those variables (those below ".....") are not present
in gitweb/README and are not present in your patch.
 

quoted

quoted

+Configuration Options Often Set at Compile Time
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+These configuration variables are often specified at compile time and are
+defined by default in the gitweb CGI itself:
+
+GIT_BINDIR::
+	Points where to find the git executable.  You should set it up to
+	the place where the git binary was installed (usually /usr/bin) if you
+	don't install git from sources together with gitweb.  [Default: $(bindir)]

[...]

I think this should be left in gitweb/INSTALL, as those are important
_only_ during building gitweb.

Understood, I'll have to audit the list for values like that. 

I meant here the whole (sub)section.

quoted

quoted

+Configuration File Example
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To enable blame, pickaxe search, and snapshot support, while allowing
+individual projects to turn them off, put the following in your
+GITWEB_CONFIG file:
+
+        $feature{'blame'}{'default'} = [1];
+        $feature{'blame'}{'override'} = 1;

I think this example requires explaining upfront what does it mean to
allow feature override, i.e. about per-repository configuration.

Agreed, I was just pulling thing together in this step. I think that
there are likely other worthy additions to this portion.

Right, we need some documentation about %feature, like e.g. what does
overriding means, and why 'default' needs to be array (currently).

-- 
Jakub Narebski
Poland