Some fixes in darcs.txt. Added darcs.html.

author: bringert <bringert@cs.chalmers.se> 2005-11-17 14:57:23 +0000
committer: bringert <bringert@cs.chalmers.se> 2005-11-17 14:57:23 +0000
commit: 2e808d442d89166272466a9a10dbfd635cd57dc5 (patch)
tree: 01138706d24d29a9ae41354146dd2ed4a5ae0dcc
parent: fc0316e7aefd97ae6b452a8b1a02032c916ee29b (diff)
2 files changed, 438 insertions, 26 deletions
diff --git a/doc/darcs.html b/doc/darcs.html
new file mode 100644
index 000000000..a2c189ae4
--- /dev/null
+++ b/doc/darcs.html
@@ -0,0 +1,388 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<HTML>
+<HEAD>
+<META NAME="generator" CONTENT="http://txt2tags.sf.net">
+<TITLE>GF Darcs repository</TITLE>
+</HEAD><BODY BGCOLOR="white" TEXT="black">
+<P ALIGN="center"><CENTER><H1>GF Darcs repository</H1>
+<FONT SIZE="4">
+GF has now been moved to a Darcs repository. No changes should be committed to the CVS repository from now on.
+</FONT></CENTER>
+
+<P></P>
+<HR NOSHADE SIZE=1>
+<P></P>
+  <UL>
+  <LI><A HREF="#toc1">What is darcs?</A>
+  <LI><A HREF="#toc2">How do I install Darcs?</A>
+  <LI><A HREF="#toc3">Read-only access</A>
+    <UL>
+    <LI><A HREF="#toc4">Getting a fresh copy for read-only access</A>
+    <LI><A HREF="#toc5">Updating your copy</A>
+    <LI><A HREF="#toc6">Submitting patches</A>
+    </UL>
+  <LI><A HREF="#toc7">Read-write access</A>
+    <UL>
+    <LI><A HREF="#toc8">Setting up your $PATH on the Chalmers system</A>
+    <LI><A HREF="#toc9">Setting up ssh alias and ControlMaster</A>
+    <LI><A HREF="#toc10">Setting up an ssh ControlMaster connection</A>
+    <LI><A HREF="#toc11">Getting a fresh copy</A>
+    <LI><A HREF="#toc12">Getting other people's changes?</A>
+    <LI><A HREF="#toc13">Commit your changes</A>
+    <LI><A HREF="#toc14">Apply a patch from someone else</A>
+    </UL>
+  <LI><A HREF="#toc15">Troubleshooting</A>
+    <UL>
+    <LI><A HREF="#toc16">I get the error "darcs not found" when pushing</A>
+    <LI><A HREF="#toc17">I get the error "(sftp) failed to fetch files."</A>
+    <LI><A HREF="#toc18">I get the error "Not a repository: gfreposerver:..."</A>
+    <LI><A HREF="#toc19">How do I avoid typing in my password so many times?</A>
+      <UL>
+      <LI><A HREF="#toc20">Using ssh ControlMaster</A>
+      <LI><A HREF="#toc21">Using ssh-agent</A>
+      </UL>
+    </UL>
+  <LI><A HREF="#toc22">Further information about Darcs</A>
+  </UL>
+
+<P></P>
+<HR NOSHADE SIZE=1>
+<P></P>
+<A NAME="toc1"></A>
+<H1>What is darcs?</H1>
+<P>
+Darcs is a decentralized revision control system. These are some of
+the reasons for switching GF from CVS to Darcs:
+</P>
+<UL>
+<LI>you can keep local revision control in your checked-out copy, since
+  each checked-out copy is a repository in itself. For example, this
+  allows the WebALT project to keep a local GF repository for working
+  on the resource grammars, and submit patches to the main repo when
+  that is convenient. It also allows individual developers to keep
+  revision control over their own modifications before they are ready
+  to submit them, or if they are temporarily without net access.
+<P></P>
+<LI>we can provide read-only access over HTTP using the existing CS web server.
+<P></P>
+<LI>it is possible and easy to rename and remove both files and directories.
+</UL>
+
+<P>
+For more information about Darcs, see <A HREF="http://darcs.net/">http://darcs.net/</A>
+</P>
+<A NAME="toc2"></A>
+<H1>How do I install Darcs?</H1>
+<P>
+There are precompiled packages for many platforms available at
+<A HREF="http://darcs.net/DarcsWiki/CategoryBinaries">http://darcs.net/DarcsWiki/CategoryBinaries</A>.
+</P>
+<P>
+There is also source code if you want to compile it yourself. Darcs is
+written in Haskell and you need GHC to compile it.
+</P>
+<A NAME="toc3"></A>
+<H1>Read-only access</H1>
+<A NAME="toc4"></A>
+<H2>Getting a fresh copy for read-only access</H2>
+<P>
+Anyone can get the latest development version of GF by running (all on one line):
+</P>
+<PRE>
+  $ darcs get --partial --set-scripts-executable http://www.cs.chalmers.se/Cs/Research/Language-technology/darcs/GF/
+</PRE>
+<P></P>
+<P>
+This will create a directory called <CODE>GF</CODE> in the current
+directory. See <CODE>GF/src/INSTALL</CODE> for instructions on compiling. The
+main difference to compiling a GF release from sources is that you
+need to run <CODE>autoconf</CODE> before <CODE>configure</CODE>.
+</P>
+<A NAME="toc5"></A>
+<H2>Updating your copy</H2>
+<P>
+Get all new patches from the main repo:
+</P>
+<PRE>
+  $ darcs pull -a
+</PRE>
+<P></P>
+<P>
+Without <CODE>-a</CODE>, you can choose which patches you want to get.
+</P>
+<A NAME="toc6"></A>
+<H2>Submitting patches</H2>
+<P>
+If you are using read-only access, send your patches by email to
+someone with write-access. Create the patch with:
+</P>
+<PRE>
+  $ darcs send -o mypatch.patch
+</PRE>
+<P></P>
+<P>
+(where <CODE>mypatch</CODE> is hopefully replaced by a slightly more
+descriptive name). Send it as an e-mail attachment. If you have
+sendmail or something equivalent installed, it is possible to send the
+patch directly from darcs. If so, replace <CODE>-o mypatch.patch</CODE> with
+<CODE>--to=EMAIL</CODE> where <CODE>EMAIL</CODE> is the address to send it to.
+</P>
+<A NAME="toc7"></A>
+<H1>Read-write access</H1>
+<P>
+If you have an account on the Chalmers system and want read-write
+access, you can access the repository using ssh.
+You need to be a member of the <CODE>langtech</CODE> group to push changes to
+the repository.
+</P>
+<A NAME="toc8"></A>
+<H2>Setting up your $PATH on the Chalmers system</H2>
+<P>
+The <CODE>darcs</CODE> program has to be on your <CODE>$PATH</CODE> on the Chalmers
+system to make it possible for you to push changes to the main
+repository. To fix this, log in to your Chalmers account and run:
+</P>
+<PRE>
+  echo unsup &gt;&gt; $HOME/.vcs4/pathsetup
+</PRE>
+<P></P>
+<P>
+Note that the path setup works differently on different Chalmers machines.
+The command above will setup you path on the newer machines correctly.
+</P>
+<A NAME="toc9"></A>
+<H2>Setting up ssh alias and ControlMaster</H2>
+<P>
+In order to avoid typing in you password multiple times for each
+action on the remote repository, you can use ssh's ControlMaster
+functionality. This allows several ssh instances to use the connection
+established by one existing instance.
+</P>
+<P>
+Add this to <CODE>~/.ssh/config</CODE> (create the file if it does not exist,
+replace <CODE>bringert</CODE> with your own username on the
+Chalmers system):
+</P>
+<PRE>
+  Host gfreposerver
+  HostName momo.medic.chalmers.se
+  User bringert
+  ControlPath /tmp/ssh-gfreposerver
+</PRE>
+<P></P>
+<P>
+This sets up an alias <CODE>gfreposerver</CODE> for the server we use 
+for the Darcs repository. Note that you really need to use 
+<CODE>momo.medic.chalmers.se</CODE> (or some other server with the new Linux system)
+since we need to have a server with Darcs 1.0.4. If you use some server
+with an earlier Darcs version you can mess up the repository.
+</P>
+<P>
+More information about the ControlMaster feature is available in 
+<CODE>man ssh_config</CODE>.
+</P>
+<A NAME="toc10"></A>
+<H2>Setting up an ssh ControlMaster connection</H2>
+<P>
+Before connecting to the remote server, you need to set up a master
+ssh connection to it. As long as this connection is up, you don't
+need to enter your password when connecting to the GF repository server.
+</P>
+<P>
+Start the master connection:
+</P>
+<PRE>
+  $ ssh -M gfreposerver
+</PRE>
+<P></P>
+<P>
+<B>NOTE: You need to have a ControlMaster connection running whenever you want to access the repo using ssh.</B>
+You may want to create a script or alias for starting the connection.
+</P>
+<A NAME="toc11"></A>
+<H2>Getting a fresh copy</H2>
+<P>
+Get your copy with (all on one line):
+</P>
+<PRE>
+  $ darcs get --partial --set-scripts-executable gfreposerver:/users/cs/www/Research/Language-technology/darcs/GF/
+</PRE>
+<P></P>
+<P>
+The option <CODE>--partial</CODE> means that you do not download all of the
+history for the repository. This saves space, bandwidth and CPU time,
+and most people don't need the full history of all changes in the
+past.
+</P>
+<A NAME="toc12"></A>
+<H2>Getting other people's changes?</H2>
+<P>
+Get all new patches from the main repo:
+</P>
+<PRE>
+  $ darcs pull -a
+</PRE>
+<P></P>
+<P>
+Without <CODE>-a</CODE>, you can choose which patches you want to get.
+</P>
+<A NAME="toc13"></A>
+<H2>Commit your changes</H2>
+<P>
+There are two steps to commiting a change to the main repo. First you
+have to record the changes that you want to commit:
+</P>
+<PRE>
+  $ darcs record
+</PRE>
+<P></P>
+<P>
+This creates a patch against the previous version and stores it in you
+local repository. You can record any number of changesets before
+pushing them to the main repo. In fact, you don't have to push them at
+all if you want to keep the changes only in your local repo.
+</P>
+<P>
+If you think there are too many questions about what to record, you
+can use the <CODE>-a</CODE> flag to <CODE>record</CODE>. Or answer <CODE>a</CODE> to the first
+question. Both of these record all the changes you have in your local
+repository.
+</P>
+<P>
+Then you can push the patch(es) to the main repo. If you are using
+ssh-access, all you need to do is:
+</P>
+<PRE>
+  $ darcs push ```
+</PRE>
+<P></P>
+<P>
+If you use the <CODE>-a</CODE> flag to push, all local patches which are not in
+the main repo are pushed.
+</P>
+<A NAME="toc14"></A>
+<H2>Apply a patch from someone else</H2>
+<P>
+Use:
+</P>
+<PRE>
+  $ darcs apply &lt; mypatch.patch
+</PRE>
+<P></P>
+<P>
+This applies the patch to your local repository. To commit it to the
+main repo, use <CODE>darcs push</CODE>.
+</P>
+<A NAME="toc15"></A>
+<H1>Troubleshooting</H1>
+<A NAME="toc16"></A>
+<H2>I get the error "darcs not found" when pushing</H2>
+<P>
+If you get <CODE>darcs not found</CODE> when you try to push your changes, you
+don't have darcs on your <CODE>$PATH</CODE> on the Chalmers system. See
+the section above on setting up your <CODE>$PATH</CODE> on the Chalmers system.
+</P>
+<A NAME="toc17"></A>
+<H2>I get the error "(sftp) failed to fetch files."</H2>
+<P>
+There seems to be a problem with how darcs 1.0.4 calls sftp, which
+means that normal password authentication does not work. Either
+use Darcs 1.0.3, and be prepared to enter your password many times,
+or use the ssh ControlMaster feature as desctribed above.
+</P>
+<A NAME="toc18"></A>
+<H2>I get the error "Not a repository: gfreposerver:..."</H2>
+<P>
+You get this error when you have set up ControlMaster, but don't have a master
+connection running. Start a master connection:
+</P>
+<PRE>
+  $ ssh -M gfreposerver
+</PRE>
+<P></P>
+<P>
+If your master connection keeps dying because of inactivity, you can have it
+run some program with outputs something once in a while, e.g.:
+</P>
+<PRE>
+  $ ssh -M gfreposerver "bash -c 'while true; do echo -n .; sleep 30; done'"
+</PRE>
+<P></P>
+<A NAME="toc19"></A>
+<H2>How do I avoid typing in my password so many times?</H2>
+<A NAME="toc20"></A>
+<H3>Using ssh ControlMaster</H3>
+<P>
+See above.
+</P>
+<A NAME="toc21"></A>
+<H3>Using ssh-agent</H3>
+<P>
+**NOTE: the method below will not work with MEDIC's new systems, such as
+ momo.medic.chalmers.se since MEDIC has decided to disable public key
+ authentication on all new machines. **
+</P>
+<P>
+With the ssh access method, Darcs needs to log in with ssh. For some
+reason it needs to do this several times for each operation. You can
+avoid this by setting up public-key authentication for ssh.
+</P>
+<P>
+Here is a guide to setting this up:
+<A HREF="http://cfm.gs.washington.edu/security/ssh/client-pkauth/">http://cfm.gs.washington.edu/security/ssh/client-pkauth/</A>
+</P>
+<P>
+Short summary (should on most modern Linux distros, maybe other
+platforms too):
+</P>
+<P>
+Generate a key pair:
+</P>
+<PRE>
+  $ mkdir -p ~/.ssh
+  $ chmod 700 ~/.ssh
+  $ ssh-keygen -q -f ~/.ssh/id_rsa -t rsa
+  Enter passphrase (empty for no passphrase): ...
+  Enter same passphrase again: ...
+</PRE>
+<P></P>
+<P>
+Upload the public key to your Chalmers account (replace <CODE>bringert</CODE> with
+your username):
+</P>
+<PRE>
+  $ ssh-copy-id -i ~/.ssh/id_rsa.pub bringert@remote.cs.chalmers.se
+</PRE>
+<P></P>
+<P>
+Add the key to ssh-agent (ssh-agent then remembers your key for a
+while, so that you don't have to type in the passphrase again):
+</P>
+<PRE>
+  $ ssh-add
+  Enter passphrase for /home/bjorn/.ssh/id_rsa: ...
+</PRE>
+<P></P>
+<P>
+This is the part that is most likely to fail. If ssh-add says that it
+couldn't find ssh-agent, you need to follow the instructions linked to
+above to start ssh-agent.
+</P>
+<P>
+Try to use it to log in (with your own username again):
+</P>
+<PRE>
+  $ ssh bringert@remote.cs.chalmers.se
+  ...
+  zsh:bringert:[~]&gt;
+</PRE>
+<P></P>
+<A NAME="toc22"></A>
+<H1>Further information about Darcs</H1>
+<P>
+For more info about what you can do with darcs, see <A HREF="http://darcs.net/manual/">http://darcs.net/manual/</A>
+</P>
+
+<!-- html code generated by txt2tags 2.0 (http://txt2tags.sf.net) -->
+<!-- cmdline: txt2tags -t html -\-toc darcs.txt -->
+</BODY></HTML>
diff --git a/doc/darcs.txt b/doc/darcs.txt
index 85ad6e80e..6875b3b98 100644
--- a/doc/darcs.txt
+++ b/doc/darcs.txt
@@ -3,6 +3,11 @@ GF Darcs repository
 GF has now been moved to a Darcs repository. No changes should be committed to the CVS repository from now on.
 
 
+% NOTE: this is a txt2tags file.
+% Create an html file from this file using:
+% txt2tags -t html --toc darcs.txt
+
+
 = What is darcs? =
 
 Darcs is a decentralized revision control system. These are some of
@@ -61,6 +66,7 @@ $ darcs pull -a
 
 Without ``-a``, you can choose which patches you want to get.
 
+
 == Submitting patches ==
 
 If you are using read-only access, send your patches by email to
@@ -82,6 +88,24 @@ patch directly from darcs. If so, replace ``-o mypatch.patch`` with
 
 = Read-write access =
 
+If you have an account on the Chalmers system and want read-write
+access, you can access the repository using ssh.
+You need to be a member of the ``langtech`` group to push changes to
+the repository.
+
+== Setting up your $PATH on the Chalmers system ==
+
+The ``darcs`` program has to be on your ``$PATH`` on the Chalmers
+system to make it possible for you to push changes to the main
+repository. To fix this, log in to your Chalmers account and run:
+
+```
+echo unsup >> $HOME/.vcs4/pathsetup
+```
+
+Note that the path setup works differently on different Chalmers machines.
+The command above will setup you path on the newer machines correctly.
+
 == Setting up ssh alias and ControlMaster ==
 
 In order to avoid typing in you password multiple times for each
@@ -97,19 +121,20 @@ Chalmers system):
 Host gfreposerver
 HostName momo.medic.chalmers.se
 User bringert
-ControlPath /tmp/bringert@momo.medic.chalmers.se:22
+ControlPath /tmp/ssh-gfreposerver
 ```
 
-This sets up an alias ``gfreposerver`` for the machine we use 
-to access the Darcs repository. Note that you really need to use 
+This sets up an alias ``gfreposerver`` for the server we use 
+for the Darcs repository. Note that you really need to use 
 ``momo.medic.chalmers.se`` (or some other server with the new Linux system)
-since we need to have a server with Darcs 1.0.4.
+since we need to have a server with Darcs 1.0.4. If you use some server
+with an earlier Darcs version you can mess up the repository.
 
-More information about the ControlMaster feature is available in ``man
-ssh_config``.
+More information about the ControlMaster feature is available in 
+``man ssh_config``.
 
 
-== Setting up an ssh connection ==
+== Setting up an ssh ControlMaster connection ==
 
 Before connecting to the remote server, you need to set up a master
 ssh connection to it. As long as this connection is up, you don't
@@ -121,10 +146,12 @@ Start the master connection:
 $ ssh -M gfreposerver
 ```
 
+**NOTE: You need to have a ControlMaster connection running whenever you want to access the repo using ssh.**
+You may want to create a script or alias for starting the connection.
+
 == Getting a fresh copy ==
 
-If you have an account on the Chalmers system and want read-write
-access, you can get your copy with (all on one line):
+Get your copy with (all on one line):
 
 ```
 $ darcs get --partial --set-scripts-executable gfreposerver:/users/cs/www/Research/Language-technology/darcs/GF/
@@ -175,9 +202,6 @@ ssh-access, all you need to do is:
 If you use the ``-a`` flag to push, all local patches which are not in
 the main repo are pushed.
 
-You need to be a member of the ``langtech`` group to push to the
-repository.
-
 
 
 == Apply a patch from someone else ==
@@ -194,6 +218,12 @@ main repo, use ``darcs push``.
 
 = Troubleshooting =
 
+== I get the error "darcs not found" when pushing ==
+
+If you get ``darcs not found`` when you try to push your changes, you
+don't have darcs on your ``$PATH`` on the Chalmers system. See
+the section above on setting up your ``$PATH`` on the Chalmers system.
+
 == I get the error "(sftp) failed to fetch files." ==
 
 There seems to be a problem with how darcs 1.0.4 calls sftp, which
@@ -218,18 +248,18 @@ $ ssh -M gfreposerver "bash -c 'while true; do echo -n .; sleep 30; done'"
 ```
 
 
-= How do I avoid typing in my password so many times? =
+== How do I avoid typing in my password so many times? ==
 
-== Using ssh ControlMaster ==
+=== Using ssh ControlMaster ===
 
 See above.
 
 
-== Using ssh-agent ==
+=== Using ssh-agent ===
 
-*NOTE: the method below will not work with MEDIC's new systems, such as
+**NOTE: the method below will not work with MEDIC's new systems, such as
  momo.medic.chalmers.se since MEDIC has decided to disable public key
- authentication on all new machines. *
+ authentication on all new machines. **
 
 With the ssh access method, Darcs needs to log in with ssh. For some
 reason it needs to do this several times for each operation. You can
@@ -279,18 +309,12 @@ $ ssh bringert@remote.cs.chalmers.se
 zsh:bringert:[~]>
 ```
 
-= I get "darcs not found" when pushing =
 
-If you get ``darcs not found`` when you try to push your changes, you
-don't have darcs on your ``$PATH`` on the Chalmers system. To fix
-this, log in to your Chalmers account and run:
 
-```
-echo unsup >> $HOME/.vcs4/pathsetup
-```
 
-
-= Further information =
+= Further information about Darcs =
 
 
 For more info about what you can do with darcs, see http://darcs.net/manual/
+
+
author	bringert <bringert@cs.chalmers.se>	2005-11-17 14:57:23 +0000
committer	bringert <bringert@cs.chalmers.se>	2005-11-17 14:57:23 +0000
commit	2e808d442d89166272466a9a10dbfd635cd57dc5 (patch)
tree	01138706d24d29a9ae41354146dd2ed4a5ae0dcc
parent	fc0316e7aefd97ae6b452a8b1a02032c916ee29b (diff)