added a section how to update the Ethereal sources

svn path=/trunk/; revision=11996

4 files changed, 86 insertions, 34 deletions

diff --git a/docbook/dg-src/EDG_chapter_env_intro.xml b/docbook/dg-src/EDG_chapter_env_intro.xml
index e47c993c75..1e825a1e48 100644
--- a/docbook/dg-src/EDG_chapter_env_intro.xml
+++ b/docbook/dg-src/EDG_chapter_env_intro.xml
@@ -275,7 +275,7 @@
 	source on your platform for productive use. However, if you going to 
 	develop changes to the Ethereal sources, it might be better to use the 
 	latest SVN sources. For details about the different ways to get the 
-	Ethereal source code see <xref linkend="ChSrcObtaining"/>.
+	Ethereal source code see <xref linkend="ChSrcObtain"/>.
     </para>
     <para>
 	Before building Ethereal from a source distribution, make sure you have
diff --git a/docbook/dg-src/EDG_chapter_libraries.xml b/docbook/dg-src/EDG_chapter_libraries.xml
index 7276c3fb3a..ff056d0461 100644
--- a/docbook/dg-src/EDG_chapter_libraries.xml
+++ b/docbook/dg-src/EDG_chapter_libraries.xml
@@ -109,7 +109,7 @@
 	<para>
 	Before you start the download, you must have installed both
 	the required tools (see <xref linkend="ChapterTools"/>) and also the 
-	Ethereal sources (see <xref linkend="ChSrcObtaining"/>).
+	Ethereal sources (see <xref linkend="ChSrcObtain"/>).
 	</para>
 	<para>
 	By default the libraries will be downloaded and installed into 
@@ -156,7 +156,7 @@
 	<listitem>
 	<para>
 	Update your Ethereal sources to the latest SVN files (see <xref 
-	linkend="ChSrcObtaining"/>), so the zip filenames in the setup target 
+	linkend="ChSrcObtain"/>), so the zip filenames in the setup target 
 	of Makefile.nmake is in sync with the library zip files on the server.
 	</para>
 	</listitem>
diff --git a/docbook/dg-src/EDG_chapter_sources.xml b/docbook/dg-src/EDG_chapter_sources.xml
index 2ad4fd3c49..e253473e59 100644
--- a/docbook/dg-src/EDG_chapter_sources.xml
+++ b/docbook/dg-src/EDG_chapter_sources.xml
@@ -142,10 +142,11 @@
 	</para>
   </section>	
 
-  <section id="ChSrcObtaining">
-	<title>Obtaining the Ethereal sources</title>
+  <section id="ChSrcObtain">
+	<title>Obtain the Ethereal sources</title>
 	<para>
-	There are several ways to obtain the sources from the Subversion server.
+	There are several ways to obtain the sources from Ethereal's Subversion 
+	server.
 	</para>
 	<note><title>Note!</title>
 	<para>
@@ -200,29 +201,20 @@
 	the latest version (including directories) from the server to your machine.
 	This will take some time, depending on the speed of your internet line.
 	</para>
-	<para>
-	After this first time checkout is done, you only need to update your 
-	sources by typing (in the Ethereal source dir):
-	</para>
-	<para>
-	<prompt>$</prompt> 
-	<userinput>svn update</userinput>
-	</para>
-	<para>
-	This will only take a few seconds, even on a slow internet line. It will 
-	replace old file versions by new ones. If you and someone else have 
-	changed the same file, Subversion will try to merge the changes into 
-	your private file (this is working remarkably well).
-	</para>
 	</section>
 
 	<section id="ChSrcSVNWeb">
-	<title>Subversion web interface</title>
+	<title>Anonymous Subversion web interface</title>
+	<para>
+	Recommended for development purposes, if direct Subversion access isn't 
+	possible (e.g. because of a restrictive firewall).
+	</para>
 	<para>
 	Age: a few minutes (same as anonymous Subversion access).
 	</para>
 	<para>
-	 The entire source tree is available via a web interface at:
+	 The entire source tree of the Subversion repository is available via a 
+	 web interface at:
 	 <ulink url="http://anonsvn.ethereal.com/viewcvs/viewcvs.py/"/>. 
 	 You can view 
 	 each revision of a particular file, as well as diffs between different 
@@ -233,19 +225,22 @@
 	<section id="ChSrcNightly">
 	<title>Nightly snapshots</title>
 	<para>
+	Well, not recommended at all.
+	</para>
+	<para>
 	Age: up to 24 hours.
 	</para>
 	<para>
-	The SVN server will automatically generate a snapshot of the SVN
+	The Subversion server will automatically generate a snapshot of Ethereal's
 	sourcetree every night. These snapshots can be found at: <ulink
 	url="http://www.ethereal.com/distribution/nightly-builds/"/>.
 	</para>
 	<para>
-	If anonymous SVN isn't possible, e.g. if the connection to the server
-	isn't possible because of a corporate firewall, the sources can be
-	obtained by downloading this nightly snapshots. However, if you are
+	If anonymous Subversion access isn't possible, e.g. if the connection to 
+	the server isn't possible because of a corporate firewall, the sources 
+	can be obtained by downloading this nightly snapshots. However, if you are
 	going to maintain your sources in parallel to the "official" sources
-	for some time, it's recommended to use the latest SVN access if
+	for some time, it's recommended to use the anonymour Subversion access if
 	possible (believe it, it will save you a lot of time).
 	</para>
 	</section>
@@ -267,9 +262,66 @@
 	</para>
 	<para>
 	The differences between the released sources and the sources stored at
-	the SVN server are keep on growing until the next release is done (at
-	the release time, the released and latest SVN versions are then
-	identical again :-).
+	the Subversion repository are keep on growing until the next release is 
+	done (at the release time, the released and latest Subversion repository
+	versions are then identical again :-).
+	</para>
+	</section>
+
+  </section>
+
+  <section id="ChSrcUpdating">
+	<title>Update the Ethereal sources</title>
+	<para>
+	After you obtained the Ethereal sources for the first time, you 
+	might want to keep them in sync with the sources at the Subversion 
+	repository.
+	</para>
+	
+	<section id="ChSrcAnonUpdate">
+	<title>... with Anonymous Subversion access</title>
+	<para>
+	After the first time checkout is done, updating your 
+	sources is simply done by typing (in the Ethereal source dir):
+	</para>
+	<para>
+	<prompt>$</prompt> 
+	<userinput>svn update</userinput>
+	</para>
+	<para>
+	This will only take a few seconds, even on a slow internet line. It will 
+	replace old file versions by new ones. If you and someone else have 
+	changed the same file since the last update, Subversion will try to merge 
+	the changes into your private file (this is working remarkably well).
+	</para>
+	</section>
+
+	<section id="ChSrcZipUpdate">
+	<title>... from zip files</title>
+	<para>
+	Independant of the way you retrieve the zip file of the Ethereal sources
+	(as <xref linkend="ChSrcObtain"/> is providing several ways), the way to 
+	bring the changes from the official sources into your personal source tree
+	is identical.
+	</para>
+	<para>
+	First of all, you will download the new zip file of the official sources
+	the way you did it the first time.
+	</para>
+	<para>
+	If you didn't changed anything in the sources, you could simply throw 
+	away your old sources and reinstall everything just like the first time.
+	But be sure, that you really didn't changed anything. It might be a good
+	idea to simply rename the "old" dir to have it around, just in case you 
+	remember later that you really did changed something before.
+	</para>
+	<para>
+	Well, if you did change something in your source tree, you have to merge 
+	the official changes 
+	since the last update into your source tree. You will install the content 
+	of the zip file into a new directory and use a good merge tool (e.g. 
+	<ulink url="http://winmerge.sourceforge.net/"/> for Win32) to bring 
+	your personal source tree in sync with the official sources again. 
 	</para>
 	</section>
 
@@ -411,7 +463,7 @@ make
   </section>
 
   <section id="ChSrcCommit">
-	<title>Committing changed sources</title>
+	<title>Commit changed sources</title>
 	<para>
 	If you have finished changing the Ethereal sources to suit your needs,
 	you might want to contribute your changes back to the Ethereal SVN
@@ -614,7 +666,7 @@ diff -ur ../ethereal-0.10.6/epan/dissectors/packet-dcerpc.c ./epan/dissectors/pa
 	  It's a good idea to work with the same sources that are used by the 
 	  other developer's, this makes it usually much easier to apply your 
 	  patch. For information about the different ways to get the sources,
-	  see <xref linkend="ChSrcObtaining"/>.
+	  see <xref linkend="ChSrcObtain"/>.
 	  </para></listitem>
 	  <listitem><para>
 	  <command>Update your SVN sources just before making a patch.
diff --git a/docbook/dg-src/EDG_chapter_tools.xml b/docbook/dg-src/EDG_chapter_tools.xml
index f758800400..11c91b1ce4 100644
--- a/docbook/dg-src/EDG_chapter_tools.xml
+++ b/docbook/dg-src/EDG_chapter_tools.xml
@@ -946,7 +946,7 @@ warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.]]>
 	changes back to the Ethereal community, it is recommended to use a SVN 
 	client to get the latest source files. For detailed information about the 
 	different ways to obtain the Ethereal sources, see 
-	<xref linkend="ChSrcObtaining"/>.
+	<xref linkend="ChSrcObtain"/>.
 	</para>
 	<para>
 	Along with the traditional command-line client, several GUI clients are 
@@ -1204,7 +1204,7 @@ written by Larry Wall and Paul Eggert]]>
 	<title>Win32: Verify installed tools</title>
 	<para>
 	After you've installed the Ethereal sources (see <xref 
-	linkend="ChSrcObtaining"/>), you can check the correct installation of 
+	linkend="ChSrcObtain"/>), you can check the correct installation of 
 	all tools by using the verify_tools target of the 
 	<filename>Makefile.nmake</filename> from the source package.
 	</para>