Re: [PATCH/WIP] Starting work on a man page for /etc/gitweb.conf
- From
Jakub Narebski <jnareb@gmail.com>
- Date
- May 12, 2011, 19:01 UTC
- Message-ID
- <201105122101.54710.jnareb@gmail.com>
- In-Reply-To
- <1305225191.24667.101.camel@drew-northup.unet.maine.edu>
On Thu, 12 May 2011, Drew Northup wrote:
Show 16 quoted lines
> 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?
Show 8 quoted lines
>> >> 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.
Show 9 quoted lines
>>> +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.
Show 15 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.
I meant here the whole (sub)section.
Show 15 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.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