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

[Jakub Narebski <jnareb@gmail.com>]

On Thu, 12 May 2011, Drew Northup wrote:
> On Thu, 2011-05-12 at 20:08 +0200, Jakub Narebski wrote:
>> On Wed, 11 May 2011, Drew Northup wrote:
> 
>>> +
>>> +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...

>>>                                                    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?

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

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

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