Commits

Anonymous committed 32d0703

more documentation

Comments (0)

Files changed (1)

 
 B<Hg::Lib> is an interface to B<mercurial>'s command
 server. (B<mercurial> is a distributed version control system (DVCS)
-tool. See L</REFERENCES> for more detailed discussions of both
+tool. See L</REFERENCES> for links to  detailed discussions of both
 B<mercurial> and its the command server. )
 
 B<mercurial> officially supports two interfaces for interacting with
 it: the command line, and its built-in command server.  The command
-server runs in parallel with the controlling program; communications
-between the two are done via the server's standard input and output
-streams.  Multiple commands may be issued, reducing the overhead of
-starting up B<mercurial> for each command.  Using the command server
-is very similar to issuing commands to the B<hg> program on the
+server runs alongside the controlling program; communications between
+the two are done via the server's standard input and output streams.
+Multiple commands may be issued, reducing the overhead of starting up
+B<mercurial> for each command.  The syntax for using the command
+server is very similar to issuing commands to the B<hg> program on the
 command line.
 
 B<Hg::Lib> manages the start and stop of the server, and marshals
 interaction with the server in an B<Hg::Lib::CLient> object, whose
 methods mirror B<hg>'s commands.
 
-
 =head2 Usage
 
-There are three entry points in B<Hg::Lib>:
+There are three functions in B<Hg::Lib>:
 
 =over
 
 
 =back
 
-Due to limitations in the command server, it can only be instantiated
-on an existing repository.  B<init> and B<clone> first use B<hg> to
-create the new repository, then start the command server, operating on
-the new repository.
+Due to limitations in the command server, it only works with an
+existing repository.  The B<init> and B<clone> functions first use
+B<hg> to create the new repository, then start the command server,
+operating on the new repository.
 
-Each routine returns an B<Hg::Lib::Client> object, which is used to
+Each function returns an B<Hg::Lib::Client> object, which is used to
 control the server.  By default the server is not actually started
 until the client sends it a request.  The C<connect> attribute may be
 used to change this behavior.
 
 =over
 
-=item configs I<scalar> | I<arrayref>
+=item C<path> I<directory name>
+
+The path to the directory containing the repository.  If not specified,
+the current directory is used. I<(Optional)>.
+
+=item C<configs> I<scalar> | I<arrayref>
 
 one or more configuration options to be passed to B<hg> via its
-C<--config> option.
+C<--config> option.  See B<hg>'s documentation for more information.
+ I<(Optional)>.
 
-=item connect I<boolean>
+=item C<connect> I<boolean>
 
 If false (the default), the command server will be started when
 the first command is sent to it.  If true, the command server will
-be started immediately.
+be started immediately.  I<(Optional)>.
 
-=item encoding I<string>
+=item C<encoding> I<string>
 
-The locale to use.
+The character set encoding to use.  I<(Optional)>.
 
-=item env I<HashRef>
+=item C<env> I<HashRef>
 
 A hash containing extra environment variables for the command server's
-environment.
+environment.  I<(Optional)>.
 
-=item hg  I<scalar> | I<arrayref>
+=item C<hg> I<scalar> | I<arrayref>
 
-The command used to invoke the B<hg> executable.  If not specified, 
-the user's path is searched for the C<hg> command.
+The command used to invoke the B<hg> executable.  If not specified,
+the user's path is searched for the C<hg> command.  I<(Optional)>.
 
-=item timeout  I<Num>
+=item C<timeout> I<Num>
 
 The time (in seconds) to wait before recieving a response from the
-command server.  It defaults to 5 seconds.
+command server.  It defaults to 5 seconds.  I<(Optional)>.
 
 =back
 
 
 =over
 
-=item dest I<directory name>
+=item C<dest> I<directory name>
 
 The name of the directory which will contain the new repository.  If
-not specified, the repository is created in the current directory.
+not specified, the repository is created in the current directory.  I<(Optional)>.
 
-=item ssh I<string>
+=item C<ssh> I<string>
 
-The ssh command to use if connecting to a remote host.
+The ssh command to use if connecting to a remote host. I<(Optional)>.
 
-=item ssh I<remotecmd>
+=item C<remotecmd> I<string>
 
-The B<hg> command to run on the remote host.
+The B<hg> command to run on the remote host. I<(Optional)>.
 
-=item insecure I<boolean>
+=item C<insecure> I<boolean>
 
-If true, do not verify server certificate.
+If true, do not verify server certificate. I<(Optional)>.
 
-=item configs I<scalar> | I<arrayref>
+=item C<configs> I<scalar> | I<arrayref>
 
 one or more configuration options to be passed to B<hg> via its
-C<--config> option.
+C<--config> option. I<(Optional)>.
 
-=item connect I<boolean>
+=item C<connect> I<boolean>
 
 If false (the default), the command server will be started when
 the first command is sent to it.  If true, the command server will
-be started immediately.
+be started immediately. I<(Optional)>.
 
-=item encoding I<string>
+=item C<encoding> I<string>
 
-The locale to use.
+The locale to use. I<(Optional)>.
 
-=item env I<HashRef>
+=item C<env> I<HashRef>
 
 A hash containing extra environment variables for the command server's
-environment.
+environment. I<(Optional)>.
 
-=item hg  I<scalar> | I<arrayref>
+=item C<hg>  I<scalar> | I<arrayref>
 
 The command used to invoke the B<hg> executable.  If not specified, 
-the user's path is searched for the C<hg> command.
+the user's path is searched for the C<hg> command. I<(Optional)>.
 
-=item timeout  I<Num>
+=item C<timeout>  I<Num>
 
 The time (in seconds) to wait before recieving a response from the
-command server.  It defaults to 5 seconds.
+command server.  It defaults to 5 seconds. I<(Optional)>.
 
 =back
 
 }
 
 
+=item B<clone>
+
+  $client = Hg::Lib::clone( source => $source, %args );
+
+Clone an existing repository and create a client associated
+with the clone.
+
+The following named arguments are available:
+
+=over
+
+=item C<source> I<directory name>
+
+The name of the directory which will contain the source repository. I<(Required)>.
+
+=item C<dest> I<directory name>
+
+Optional. The name of the directory which will contain the new repository.  If
+not specified, a new directory (named after the basename of the source)
+containing the clone is created in the current directory.  I<(Optional)>.
+
+=item C<noupdate> I<boolean>
+
+If true, the clone will have an empty working copy.  It defaults to
+false.  I<(Optional)>.
+
+=item C<updaterev> I<string>
+
+The revision, tag, or branch to check out. I<(Optional)>.
+
+=item C<ssh> I<string>
+
+The ssh command to use if connecting to a remote host. I<(Optional)>.
+
+=item C<remotecmd> I<string>
+
+The B<hg> command to run on the remote host. I<(Optional)>.
+
+=item C<insecure> I<boolean>
+
+If true, do not verify server certificate. I<(Optional)>.
+
+=item C<configs> I<scalar> | I<arrayref>
+
+one or more configuration options to be passed to B<hg> via its
+C<--config> option. I<(Optional)>.
+
+=item C<connect> I<boolean>
+
+If false (the default), the command server will be started when
+the first command is sent to it.  If true, the command server will
+be started immediately. I<(Optional)>.
+
+=item C<encoding> I<string>
+
+The locale to use. I<(Optional)>.
+
+=item C<env> I<HashRef>
+
+A hash containing extra environment variables for the command server's
+environment. I<(Optional)>.
+
+=item C<hg>  I<scalar> | I<arrayref>
+
+The command used to invoke the B<hg> executable.  If not specified,
+the user's path is searched for the C<hg> command. I<(Optional)>.
+
+=item C<timeout>  I<Num>
+
+The time (in seconds) to wait before recieving a response from the
+command server.  It defaults to 5 seconds. I<(Optional)>.
+
+=back
+
+=cut
+
 sub clone {
 
     my $self = shift;
 
 =over
 
-=item mercurial
+=item B<mercurial>
 
 L<http://mercurial.selenic.com/>