.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Apache::GopherHandler 3"
.TH Apache::GopherHandler 3 "2008-01-18" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
.Vb 1
\&  Apache::GopherHandler - Gopher protocol implementation for Apache2
.Ve
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\& # In your Apache2 configuration
\& <VirtualHost _default_:70>
\&        DocumentRoot /home/www/data/gopher
.Ve
.PP
.Vb 10
\&        <Perl>
\&                $Apache::GopherHandler::Config{doc_root} = '/home';
\&                $Apache::GopherHandler::Config{server}   = 'localhost';
\&                $Apache::GopherHandler::Config{port}     = 70;
\&                $Apache::GopherHandler::Config{handler}  =
\&                        'Gopher::Server::RequestHandler::File';
\&        </Perl>
\&        PerlModule                    Apache::GopherHandler
\&        PerlProcessConnectionHandler  Apache::GopherHandler
\& </VirtualHost>
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
One of the earliest goals stated in the Gopher Manifesto 
(<http://27.org/gopher\-manifesto/>) was to have an Apache plugin that 
would run a Gopher server.  So here it is.
.PP
This requires Apache2/mod_perl.  Sorry.  The first version of Apache 
is too HTTP\-centric.  In Apache2, the project moved twards a more generalized 
server that was modular enough to support other protocols.  Without that, 
making Gopher available on Apache servers would have been impossible, or at 
least very difficult.
.PP
For the moment, this isn't a very full-featured server.  If you want a 
stand-alone Gopher server, you're probably better off using PyGopherd 
(<http://gopher.quux.org:70/devel/gopher/Downloads/pygopherd>).  If you 
want to convert an existing Apache2 server into something that can 
support Gopher and you don't care about (or can wait for) some fancier 
features, then this will work fine.
.PP
This relies on the Gopher::Server module to take care most of the 
implementation details of the protocol.  Apache::GopherHandler provides the 
glue between that module and Apache.
.SH "CONFIGURATION"
.IX Header "CONFIGURATION"
The best way to run Apache::GopherHandler is inside an Apache <VirtualHost>.  
Actual configuration is done either inside a <Perl> directive or your 
Apache startup file.  This is done by accessing the hash 
\&\f(CW%Apache::GopherHandler::Config\fR.  Keys can be specified here that will 
be passed to the \f(CW\*(C`Gopher::Server::Requesthandler\*(C'\fR you specify in the 
\&\f(CW\*(C`handler\*(C'\fR key.  Currently, only \f(CW\*(C`Gopher::Server::RequestHandler::File\*(C'\fR 
is supported (but this will change).
.PP
At a minimum, the following keys are needed:
.Sh "handler"
.IX Subsection "handler"
The \f(CW\*(C`Gopher::Server::RequestHandler\*(C'\fR class to use.  Default: 
\&\f(CW\*(C`Gopher::Server::RequestHandler::File\*(C'\fR
.Sh "server"
.IX Subsection "server"
The hostname of the server.  Default: localhost
.Sh "port"
.IX Subsection "port"
The \s-1TCP\s0 port of the server.  Make sure your <VirtualHost> directive 
specifies this port and the Apache \f(CW\*(C`Listen\*(C'\fR option is set to listen 
on this port.  Default: 70
.Sh "doc_root"
.IX Subsection "doc_root"
The root of the Gopher server on your file system.  Default: /noexists/
.SH "BUGS"
.IX Header "BUGS"
Yes.
.SH "AUTHOR"
.IX Header "AUTHOR"
.Vb 4
\& Timm Murray
\& CPAN ID: TMURRAY
\& E-Mail: tmurray@cpan.org
\& Homepage: http://www.wumpus-cave.net
.Ve
.SH "LICENSE"
.IX Header "LICENSE"
Apache::GopherHandler
Copyright (C) 2004  Timm Murray
.PP
This program is free software; you can redistribute it and/or modify
it under the terms of the \s-1GNU\s0 General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
.PP
This program is distributed in the hope that it will be useful,
but \s-1WITHOUT\s0 \s-1ANY\s0 \s-1WARRANTY\s0; without even the implied warranty of
\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0.  See the
\&\s-1GNU\s0 General Public License for more details.
.PP
You should have received a copy of the \s-1GNU\s0 General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, \s-1MA\s0 02139, \s-1USA\s0.