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

From: Drew Northup <drew.northup@maine.edu>
Date: May 12, 2011, 18:33 UTC
Message-ID: <1305225191.24667.101.camel@drew-northup.unet.maine.edu>
In-Reply-To: <201105122008.53322.jnareb@gmail.com>

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

> On Wed, 11 May 2011, Drew Northup wrote:

Show 11 quoted lines

> > +
> > +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...

Show 7 quoted lines

> >                                                    See the perlsyn(1) man page 
> > +for more information.
> 
> Is this how other manpages should be referenced in AsciiDoc?
> 
> 
> BTW. What is &#8211;, 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.

Show 12 quoted lines

> > +One good reason to take advantage of the system-wide and local gitweb
> > +configuration files is that not all settings may be set up directly in the CGI
> > +itself. Optional features &#8211; defined using the '%features' variable
> > +&#8211; must be set in one of the two configuration files.
> > +
> > +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.

Show 13 quoted lines

> > +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.

Show 12 quoted lines

> > +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.

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