Quick updates to doc/gf-developers.t2t

2026-05-26 03:08:55 -06:00 · 2012-05-15 12:51:58 +00:00
parent a2bae03824
commit 74cd9c4979
2 changed files with 116 additions and 33 deletions
--- a/doc/gf-developers.html
+++ b/doc/gf-developers.html
@@ -1,19 +1,21 @@
 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
 <HTML>
 <HEAD>
-<META NAME="generator" CONTENT="http://txt2tags.sf.net">
+<META NAME="generator" CONTENT="http://txt2tags.org">
 <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=utf-8">
 <LINK REL="stylesheet" TYPE="text/css" HREF="../css/style.css">
 <TITLE>GF Developers Guide</TITLE>
 </HEAD><BODY BGCOLOR="white" TEXT="black">
-<P ALIGN="center"><CENTER><H1>GF Developers Guide</H1>
+<CENTER>
-<FONT SIZE="4">
+<H1>GF Developers Guide</H1>
-<I>Authors: Björn Bringert  and  Krasimir Angelov</I><BR>
+<FONT SIZE="4"><I>Authors: Björn Bringert, Krasimir Angelov and Thomas Hallgren</I></FONT><BR>
-Last update: Mon Dec 14 18:55:45 2009
+<FONT SIZE="4">Last update: Tue May 15 14:51:04 2012, but some information here is outdated</FONT>
-</FONT></CENTER>
+</CENTER>
 <P></P>
 <HR NOSHADE SIZE=1>
 <P></P>
  <UL>
  <LI><A HREF="#toc1">Setting up your system for building GF</A>
  <LI><A HREF="#toc2">Getting the sources</A>
@@ -49,8 +51,10 @@ Last update: Mon Dec 14 18:55:45 2009
 <P></P>
 <HR NOSHADE SIZE=1>
 <P></P>
 <A NAME="toc1"></A>
 <H1>Setting up your system for building GF</H1>
 <P>
 Before to build GF from sources you need to install some tools on your system.
 GF is written in Haskell, so first of all you need recent version of the Haskell compiler GHC.
@@ -65,16 +69,20 @@ so you cannot use previous versions. GHC is available from here:
 Once you have installed GHC, open a terminal (Command Prompt on Windows) and try
 to execute the following command:
 </P>
 <PRE>
  $ ghc --version
 </PRE>
 <P>
 This command should show you which version of GHC you have. If the installation
 of GHC was successful you should see message like:
 </P>
 <PRE>
  The Glorious Glasgow Haskell Compilation System, version 6.10.3
 </PRE>
 <P>
 The other two tools that we use are the lexer generator for Haskell - Alex:
 <A HREF="http://www.haskell.org/alex/">http://www.haskell.org/alex/</A>
@@ -93,6 +101,7 @@ plan to use GF for continuous development then it is recomended to install
 some of these libraries. The GF configuration script checks the libraries
 in the following order:
 </P>
 <UL>
 <LI>haskeline
 <LI>readline
@@ -104,9 +113,11 @@ the first that is found will be used in the compilation. The libraries are also
 in Haskell and could be found on Hackage: <A HREF="http://hackage.haskell.org/packages/archive/pkg-list.html">http://hackage.haskell.org/packages/archive/pkg-list.html</A>. If you want to check whether,
 you already have some of these you can use the following command:
 </P>
 <PRE>
  $ ghc-pkg list
 </PRE>
 <P>
 which shows the list of all installed libraries. 
 </P>
@@ -126,44 +137,56 @@ see <A HREF="http://darcs.net/">http://darcs.net/</A> for more information. Ther
 <A HREF="http://darcs.net/DarcsWiki/CategoryBinaries">http://darcs.net/DarcsWiki/CategoryBinaries</A>. There is also source code if you want to compile it yourself. Darcs is
 also written in Haskell and so you can use GHC to compile it.
 </P>
 <A NAME="toc2"></A>
 <H1>Getting the sources</H1>
 <P>
 Once you have all tools in place you can get the GF sources. If you just want to compile and use GF
 then it is enough to have read-only access. It is also possible to make changes in the sources but if
 you want these changes to be applied back to the main sources you will have to send the changes to us.
 If you plan to work continuously on GF then you should consider to get read-write access.
 </P>
 <A NAME="toc3"></A>
 <H2>Read-only access</H2>
 <A NAME="toc4"></A>
 <H3>Getting a fresh copy for read-only access</H3>
 <P>
 Anyone can get the latest development version of GF by running (all on one line):
 </P>
 <PRE>
-  $ darcs get --lazy --set-scripts-executable http://code.haskell.org/gf/
+  $ darcs get --lazy --set-scripts-executable http://www.grammaticalframework.org/ gf
 </PRE>
-<P></P>
+
 <P>
 This will create a directory called <CODE>gf</CODE> in the current
 directory.
 </P>
 <A NAME="toc5"></A>
 <H3>Updating your copy</H3>
 <P>
 To get all new patches from the main repo:
 </P>
 <PRE>
  $ darcs pull -a
 </PRE>
 <P>
 This can be done anywhere in your local repository, i.e. in the <CODE>gf</CODE>
 directory, or any of its subdirectories.
 Without <CODE>-a</CODE>, you can choose which patches you want to get.
 </P>
 <A NAME="toc6"></A>
 <H3>Recording local changes</H3>
 <P>
 Since every copy is a repository, you can have local version control
 of your changes.
@@ -172,17 +195,19 @@ of your changes.
 If you have added files, you first need to tell your local repository to 
 keep them under revision control:
 </P>
 <PRE>
  $ darcs add file1 file2 ...
 </PRE>
-<P></P>
+
 <P>
 To record changes, use:
 </P>
 <PRE>
  $ darcs record
 </PRE>
-<P></P>
+
 <P>
 This creates a patch against the previous version and stores it in your
 local repository. You can record any number of changes before
@@ -195,19 +220,22 @@ can use the <CODE>-a</CODE> flag to <CODE>record</CODE>. Or answer <CODE>a</CODE
 question. Both of these record all the changes you have in your local
 repository.
 </P>
 <A NAME="toc7"></A>
 <H3>Submitting patches</H3>
 <P>
 If you are using read-only access, send your patches by email to
 someone with write-access. First record your changes in your local 
 repository, as described above. You can send any number of recorded
 patches as one patch bundle. You create the patch bundle with:
 </P>
 <PRE>
  $ darcs send -o mypatch.patch
  $ gzip mypatch.patch
 </PRE>
-<P></P>
+
 <P>
 (where <CODE>mypatch</CODE> is hopefully replaced by a slightly more
 descriptive name). Since some e-mail setups change text attachments
@@ -220,44 +248,52 @@ 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="toc8"></A>
 <H2>Read-write access</H2>
 <P>
-If you have a user account on code.haskell.org, you can get read-write access over SSH
+If you have a user account on <A HREF="http://www.grammaticalframework.org">www.grammaticalframework.org</A>, you can
-to the GF repository. 
+get read-write access over SSH to the GF repository.
 To get an account, <A HREF="http://community.haskell.org/admin/account_request.html">fill out this form</A>.
 Once you have an account, ask &lt;<A HREF="mailto:aarne@chalmers.se">aarne@chalmers.se</A>&gt; to add you to the <CODE>GF</CODE> project.
 </P>
 <A NAME="toc9"></A>
 <H3>Getting a fresh copy</H3>
 <P>
 Get your copy with (all on one line),
 replacing <CODE>bringert</CODE> with your own username on code.haskell.org:
 </P>
 <PRE>
-  $ darcs get --lazy --set-scripts-executable bringert@code.haskell.org:/srv/code/gf
+  $ darcs get --lazy --set-scripts-executable bringert@www.grammaticalframework.org:/usr/local/www/GF/ gf
 </PRE>
-<P></P>
+
 <P>
 The option <CODE>--lazy</CODE> means that darcs defers downloading all 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="toc10"></A>
 <H3>Getting other people's changes?</H3>
 <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="toc11"></A>
 <H3>Commit your changes</H3>
 <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, then you push them
@@ -265,34 +301,42 @@ to the main repo. For instructions on recording your changes locally,
 see "Recording local changes" above. 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="toc12"></A>
 <H3>Apply a patch from someone else</H3>
 <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="toc13"></A>
 <H2>Further information about Darcs</H2>
 <P>
 For more info about what you can do with darcs, see <A HREF="http://darcs.net/manual/">http://darcs.net/manual/</A>
 </P>
 <A NAME="toc14"></A>
 <H1>Compilation from sources</H1>
 <P>
 The build system of GF is based on Cabal (see <A HREF="http://www.haskell.org/cabal/">http://www.haskell.org/cabal/</A> for more information).
 Cabal is installed by default together with the GHC compiler. This is actually a library which could
@@ -301,15 +345,19 @@ called Setup.hs which is placed in the top directory of every project managed wi
 The three main steps that are needed for compilation are much like what you do in a project
 written in C, you have: configure, build and install.
 </P>
 <A NAME="toc15"></A>
 <H2>Configure</H2>
 <P>
 During the configuration phase Cabal will check that you have all necessary tools and libraries
 needed for GF. The configuration is started by the command:
 </P>
 <PRE>
  $ runghc Setup.hs configure
 </PRE>
 <P>
 The command <CODE>`runghc`</CODE> comes with the GHC compiler and is batch interpreter which executes
 the specified script without the need to compile it advance. Setup.hs is our compilation driver
@@ -317,16 +365,20 @@ which is based on Cabal. If you don't see any error message from the above comma
 you have everything that is needed for GF. You can also add the option <CODE>`-v`</CODE> to see
 more details about the configuration.
 </P>
 <A NAME="toc16"></A>
 <H2>Build</H2>
 <P>
 The build phase does two things. First it builds the GF compiler from the Haskell sources
 and after that it builds the GF Resource Grammar Library using the already build compiler.
 The simplest command is:
 </P>
 <PRE>
  $ runghc Setup.hs build
 </PRE>
 <P>
 Again you can add the option <CODE>`-v`</CODE> if you want to see more details.
 </P>
@@ -334,18 +386,22 @@ Again you can add the option <CODE>`-v`</CODE> if you want to see more details.
 Sometimes you just want to work on the GF compiler and don't want to recompile the resource
 library after each change. In this case use this extended command:
 </P>
 <PRE>
  $ runghc Setup.hs build rgl-none
 </PRE>
 <P>
 The resource library could also be compiled in two modes: with present tense only and 
 with all tenses. By default it is compiled with all tenses. If you want to use
 the library with only present tense you can compile it in this special mode with
 the command:
 </P>
 <PRE>
  $ runghc Setup.hs build present
 </PRE>
 <P>
 Before to use this command make sure that the script lib/src/mkPresent has executable
 permissions on Linux.
@@ -355,28 +411,34 @@ You could also control which languages you want to be recompiled by adding the o
 <CODE>`langs=list`</CODE>. For example the following command will compile only the English and the Swedish
 language:
 </P>
 <PRE>
  $ runghc Setup.hs build langs=Eng,Swe
 </PRE>
-<P></P>
+
 <A NAME="toc17"></A>
 <H2>Install</H2>
 <P>
 After you have compiled GF you can install the binaries to make the system usable.
 On Linux you will need root privileges to do this. Use the command:
 </P>
 <PRE>
  $ su
 </PRE>
 <P>
 and enter the root password. This step should be skipped on Windows.
 </P>
 <P>
 The installation itself is started with the command:
 </P>
 <PRE>
  $ runghc Setup.hs install
 </PRE>
 <P>
 This command installs the GF compiler in the default place for executable
 files in your system. For example on Linux this is usualy /usr/local/bin and on
@@ -388,71 +450,91 @@ The compiled GF Resource Grammar Library will be installed in /usr/local/share/g
 on Linux and in c:\Program Files\Haskell\gf-3.1\lib on Windows. Again the location could
 be changed using the <CODE>`--prefix`</CODE> option.
 </P>
 <A NAME="toc18"></A>
 <H2>Clean</H2>
 <P>
 Sometimes you want to clean up the compilation and start again from clean
 sources. Use the clean command for this purpose:
 </P>
 <PRE>
  $ runghc Setup.hs clean
 </PRE>
-<P></P>
+
 <A NAME="toc19"></A>
 <H2>SDist</H2>
 <P>
 You can use the command:
 </P>
 <PRE>
  $ runghc Setup.hs sdist
 </PRE>
 <P>
 to prepare archive with all source codes needed to compile GF.
 </P>
 <A NAME="toc20"></A>
 <H1>Compilation with make</H1>
 <P>
 If you feel more comfortable with Makefiles then there is a thin Makefile
 wrapper arround Cabal for you. If you just type:
 </P>
 <PRE>
  $ make
 </PRE>
 <P>
 the configuration phase will be run automatically if needed and after that
 the sources will be compiled. If you don't want to compile the resource library
 every time then you can use:
 </P>
 <PRE>
  $ make gf
 </PRE>
 <P>
 For installation use:
 </P>
 <PRE>
  $ make install
 </PRE>
 <P>
 For cleaning:
 </P>
 <PRE>
  $ make clean
 </PRE>
 <P>
 and to build source distribution archive run:
 </P>
 <PRE>
  $ make sdist
 </PRE>
-<P></P>
+
 <A NAME="toc21"></A>
 <H1>Running the testsuite</H1>
 <P>
 GF has testsuite. It is run with the following command:
 </P>
 <PRE>
  $ runghc Setup.hs test
 </PRE>
 <P>
 The testsuite architecture for GF is very simple but still very flexible.
 GF by itself is an interpreter and could execute commands in batch mode.
@@ -476,13 +558,15 @@ that we will not incidentaly break your code later.
 If you don't want to run the whole testsuite you can write the path to the subdirectory
 in which you are interested. For example:
 </P>
 <PRE>
  $ runghc Setup.hs test testsuite/compiler
 </PRE>
 <P>
 will run only the testsuite for the compiler.
 </P>
-<!-- html code generated by txt2tags 2.5 (http://txt2tags.sf.net) -->
+<!-- html code generated by txt2tags 2.6 (http://txt2tags.org) -->
-<!-- cmdline: txt2tags gf-developers.txt -->
+<!-- cmdline: txt2tags -thtml ./doc/gf-developers.t2t -->
 </BODY></HTML>
--- a/doc/gf-developers.t2t
+++ b/doc/gf-developers.t2t
@@ -1,11 +1,12 @@
 GF Developers Guide
-Authors: Björn Bringert  and  Krasimir Angelov
+Authors: Björn Bringert, Krasimir Angelov and Thomas Hallgren
-Last update: %%mtime(%c)
+Last update: %%mtime(%c), but some information here is outdated
 % NOTE: this is a txt2tags file.
 % Create an html file from this file using:
 % txt2tags -t html --toc darcs.txt
 %!style:../css/style.css
 %!target:html
 %!options(html): --toc
 %!encoding:utf-8
@@ -88,7 +89,7 @@ If you plan to work continuously on GF then you should consider to get read-writ
 Anyone can get the latest development version of GF by running (all on one line):
 ```
-$ darcs get --lazy --set-scripts-executable http://code.haskell.org/gf/
+$ darcs get --lazy --set-scripts-executable http://www.grammaticalframework.org/ gf
 ```
 This will create a directory called ``gf`` in the current
@@ -163,10 +164,8 @@ patch directly from darcs. If so, replace ``-o mypatch.patch`` with
 == Read-write access ==
-If you have a user account on code.haskell.org, you can get read-write access over SSH
+If you have a user account on www.grammaticalframework.org, you can
-to the GF repository. 
+get read-write access over SSH to the GF repository.
 To get an account, [fill out this form http://community.haskell.org/admin/account_request.html].
 Once you have an account, ask <aarne@chalmers.se> to add you to the ``GF`` project.
 === Getting a fresh copy ===
@@ -175,7 +174,7 @@ Get your copy with (all on one line),
 replacing ``bringert`` with your own username on code.haskell.org:
 ```
-$ darcs get --lazy --set-scripts-executable bringert@code.haskell.org:/srv/code/gf
+$ darcs get --lazy --set-scripts-executable bringert@www.grammaticalframework.org:/usr/local/www/GF/ gf
 ```
 The option ``--lazy`` means that darcs defers downloading all the