comparison en/ch05-collab.xml @ 691:4ce9d0754af3

Remove the words "section", "chapter", etc from in front of xref tags.

690:b788b405e141

    <para id="x_44f">The easiest way to get started with the web interface is to
      use your web browser to visit an existing repository, such as
      the master Mercurial repository at <ulink
	url="http://www.selenic.com/repo/hg?style=gitweb">http://www.selenic.com/repo/hg?style=gitweb</ulink>.</para>

    <para id="x_450">If you're interested in providing a web interface to your
      own repositories, Mercurial provides two ways to do this.  The
      first is using the <command role="hg-cmd">hg serve</command>
      command, which is best suited to short-term
      <quote>lightweight</quote> serving.  See section <xref
	linkend="sec:collab:serve"/> below for details of how to use
      this command.  If you have a long-lived repository that you'd
      like to make permanently available, Mercurial has built-in
      support for the CGI (Common Gateway Interface) standard, which
      all common web servers support.  See section <xref
	linkend="sec:collab:cgi"/> for details of CGI
      configuration.</para>

  </sect1>
  <sect1>

	a number of people get together in a single location (a
	company's conference room, a hotel meeting room, that kind of
	place) and spend several days more or less locked in there,
	hacking intensely on a handful of projects.</para>

      <para id="x_457">A sprint is the perfect place to use the <command
	  role="hg-cmd">hg serve</command> command, since <command
	  role="hg-cmd">hg serve</command> does not require any fancy
	server infrastructure.  You can get started with <command
	  role="hg-cmd">hg serve</command> in moments, by reading
	section <xref linkend="sec:collab:serve"/> below.  Then simply
	tell
	the person next to you that you're running a server, send the
	URL to them in an instant message, and you immediately have a
	quick-turnaround way to work together.  They can type your URL
	into their web browser and quickly review your changes; or
	they can pull a bugfix from you and verify it; or they can
	clone a branch containing a new feature and try it out.</para>

      <para id="x_458">The charm, and the problem, with doing things in an ad hoc
	fashion like this is that only people who know about your
	changes, and where they are, can see them.  Such an informal
	approach simply doesn't scale beyond a handful people, because

	potential for damage, I can ask you to clone my repository
	into a temporary repository of your own and test it.  This
	lets us put off publishing the potentially unsafe change until
	it has had a little testing.</para>

      <para id="x_45c">In this kind of scenario, people usually use the
	<command>ssh</command> protocol to securely push changes to
	the central repository, as documented in section <xref
	  linkend="sec:collab:ssh"/>.  It's also
	usual to publish a read-only copy of the repository over HTTP
	using CGI, as in section <xref linkend="sec:collab:cgi"/>.
	Publishing over HTTP
	satisfies the needs of people who don't have push access, and
	those who want to use web browsers to browse the repository's
	history.</para>

    </sect2>
    <sect2>
      <title>Working with multiple branches</title>

    </sect2>
    <sect2>
      <title>Where collaboration meets branch management</title>

      <para id="x_479">Once you and your team set up some shared repositories and
	start propagating changes back and forth between local and
	shared repos, you begin to face a related, but slightly
	different challenge: that of managing the multiple directions
	in which your team may be moving at once.  Even though this
	subject is intimately related to how your team collaborates,
	it's dense enough to merit treatment of its own, in chapter
	<xref linkend="chap:branch"/>.</para>

    </sect2>
  </sect1>
  <sect1>
    <title>The technical side of sharing</title>

	  url="http://www.selenic.com/repo/hg/raw-file/tip/hgwebdir.cgi">http://www.selenic.com/repo/hg/raw-file/tip/hgwebdir.cgi</ulink>.</para>

      <para id="x_4d6">You'll need to copy this script into your <filename
	  class="directory">public_html</filename> directory, and
	ensure that it's executable.</para>
      <programlisting>cp .../hgwebdir.cgi ~/public_html
chmod 755 ~/public_html ~/public_html/hgwebdir.cgi</programlisting>
      <para id="x_4d7">With basic configuration out of the way, try to visit
	<ulink url="http://myhostname/
	  myuser/hgwebdir.cgi">http://myhostname/
	  myuser/hgwebdir.cgi</ulink> in your browser.  It should
	display an empty list of repositories.  If you get a blank
	window or error message, try walking through the list of
	potential problems in section <xref
	  linkend="sec:collab:wtf"/>.</para>

      <para id="x_4d8">The <filename role="special">hgwebdir.cgi</filename>
	script relies on an external configuration file.  By default,
	it searches for a file named <filename

	    Integer.  If the web interface displays alternating
	    <quote>stripes</quote> to make it easier to visually align
	    rows when you are looking at a table, this number controls
	    the number of rows in each stripe.</para>
	</listitem>
	<listitem><para id="x_4f0"><envar role="rc-item-web">style</envar>:
	    Controls the template Mercurial uses to display the web
	    interface.  Mercurial ships with two web templates, named
	    <literal>default</literal> and <literal>gitweb</literal>
	    (the latter is much more visually attractive).  You can
	    also specify a custom template of your own; see chapter
	    <xref linkend="chap:template"/> for details.
	    Here, you can see how to enable the
	    <literal>gitweb</literal> style.</para>
	  <programlisting>[web]
style = gitweb</programlisting>
	</listitem>
	<listitem><para id="x_4f1"><envar role="rc-item-web">templates</envar>:
	    Path.  The directory in which to search for template

691:4ce9d0754af3

    <para id="x_44f">The easiest way to get started with the web interface is to
      use your web browser to visit an existing repository, such as
      the master Mercurial repository at <ulink
	url="http://www.selenic.com/repo/hg?style=gitweb">http://www.selenic.com/repo/hg?style=gitweb</ulink>.</para>

    <para id="x_450">If you're interested in providing a web interface
      to your own repositories, Mercurial provides two ways to do
      this.  The first is using the <command role="hg-cmd">hg
	serve</command> command, which is best suited to short-term
      <quote>lightweight</quote> serving.  See <xref
	linkend="sec:collab:serve"/> below for details of how to use
      this command.  If you have a long-lived repository that you'd
      like to make permanently available, Mercurial has built-in
      support for the CGI (Common Gateway Interface) standard, which
      all common web servers support.  See <xref
	linkend="sec:collab:cgi"/> for details of CGI
      configuration.</para>

  </sect1>
  <sect1>

	a number of people get together in a single location (a
	company's conference room, a hotel meeting room, that kind of
	place) and spend several days more or less locked in there,
	hacking intensely on a handful of projects.</para>

      <para id="x_457">A sprint is the perfect place to use the
	<command role="hg-cmd">hg serve</command> command, since
	<command role="hg-cmd">hg serve</command> does not require any
	fancy server infrastructure.  You can get started with
	<command role="hg-cmd">hg serve</command> in moments, by
	reading <xref linkend="sec:collab:serve"/> below.  Then simply
	tell the person next to you that you're running a server, send
	the URL to them in an instant message, and you immediately
	have a quick-turnaround way to work together.  They can type
	your URL into their web browser and quickly review your
	changes; or they can pull a bugfix from you and verify it; or
	they can clone a branch containing a new feature and try it
	out.</para>

      <para id="x_458">The charm, and the problem, with doing things in an ad hoc
	fashion like this is that only people who know about your
	changes, and where they are, can see them.  Such an informal
	approach simply doesn't scale beyond a handful people, because

	potential for damage, I can ask you to clone my repository
	into a temporary repository of your own and test it.  This
	lets us put off publishing the potentially unsafe change until
	it has had a little testing.</para>

      <para id="x_45c">In this kind of scenario, people usually use
	the <command>ssh</command> protocol to securely push changes
	to the central repository, as documented in <xref
	  linkend="sec:collab:ssh"/>.  It's also usual to publish a
	read-only copy of the repository over HTTP using CGI, as in
	<xref linkend="sec:collab:cgi"/>. Publishing
	over HTTP satisfies the needs of people who don't have push
	access, and those who want to use web browsers to browse the
	repository's history.</para>

    </sect2>
    <sect2>
      <title>Working with multiple branches</title>

    </sect2>
    <sect2>
      <title>Where collaboration meets branch management</title>

      <para id="x_479">Once you and your team set up some shared
	repositories and start propagating changes back and forth
	between local and shared repos, you begin to face a related,
	but slightly different challenge: that of managing the
	multiple directions in which your team may be moving at once.
	Even though this subject is intimately related to how your
	team collaborates, it's dense enough to merit treatment of its
	own, in <xref linkend="chap:branch"/>.</para>

    </sect2>
  </sect1>
  <sect1>
    <title>The technical side of sharing</title>

	  url="http://www.selenic.com/repo/hg/raw-file/tip/hgwebdir.cgi">http://www.selenic.com/repo/hg/raw-file/tip/hgwebdir.cgi</ulink>.</para>

      <para id="x_4d6">You'll need to copy this script into your <filename
	  class="directory">public_html</filename> directory, and
	ensure that it's executable.</para>

      <programlisting>cp .../hgwebdir.cgi ~/public_html
chmod 755 ~/public_html ~/public_html/hgwebdir.cgi</programlisting>

      <para id="x_4d7">With basic configuration out of the way, try to
	visit <ulink url="http://myhostname/
	  myuser/hgwebdir.cgi">http://myhostname/
	  myuser/hgwebdir.cgi</ulink> in your browser.  It should
	display an empty list of repositories.  If you get a blank
	window or error message, try walking through the list of
	potential problems in <xref
	  linkend="sec:collab:wtf"/>.</para>

      <para id="x_4d8">The <filename role="special">hgwebdir.cgi</filename>
	script relies on an external configuration file.  By default,
	it searches for a file named <filename

	    Integer.  If the web interface displays alternating
	    <quote>stripes</quote> to make it easier to visually align
	    rows when you are looking at a table, this number controls
	    the number of rows in each stripe.</para>
	</listitem>
	<listitem><para id="x_4f0"><envar
	      role="rc-item-web">style</envar>: Controls the template
	    Mercurial uses to display the web interface.  Mercurial
	    ships with two web templates, named
	    <literal>default</literal> and <literal>gitweb</literal>
	    (the latter is much more visually attractive).  You can
	    also specify a custom template of your own; see 
	    <xref linkend="chap:template"/> for details. Here, you can
	    see how to enable the <literal>gitweb</literal>
	    style.</para>
	  <programlisting>[web]
style = gitweb</programlisting>
	</listitem>
	<listitem><para id="x_4f1"><envar role="rc-item-web">templates</envar>:
	    Path.  The directory in which to search for template