This is the module with the sources of the DrGeo manual.

If you wish to work on or to participate in the translation of a
manual, you are suggested to entirely read this document. Also you may
want to read part of this document from time to time.

The various sections of this document explain how is set up the
translation procedure within this module. Some of the paragraphs below
may look a bit difficult to follow, however translating the manual is
one step but keeping a translated version up to date with the source
manual is more difficult. The main purpose of this CVS module
organisation is to have a consistent way to keep track of the update
in the source manual and to apply it to the translated manual.

HOW TO COMPILE MANUAL
---------------------

In top directory:

aclocal
automake
autoconf
./configure --prefix=/usr
cd fr (up to you)
make drgenius.pdf
make drgenius.html
make install (it will install the .html so that Dr.Geo can found it)

DOCUMENT TO TRANSLATE
---------------------

To translate the Dr Geo manual, one file need to get translated:

	o the drgenius.tex file, it is the manual source;


LATEX & HYPERLATEX
------------------

LaTeX & HyperLaTeX are used to produce from a single .tex document a
paper version and a html version used as an online help.  Common
macros to all the manuals are placed in the drgeniusCommon.tex
file. This file is included near the top of the drgenius.tex
document. The drgenius.tex is the manual. Each national manual has its
own directory -- generally a two letters directory name.



PICTURES
--------

In the manual, the pictures are located in the "figures" directories
of the various manual version. However, while translating the manual,
the c/figures can be used for all manual versions by setting the LaTeX
macro \drgeniusImagePath to the appropriate relative path
"../c/figures".

If you want to get localised pictures as well, create a 'figures'
directory in your locale directory, for example it/figures. Into that
directory copy the c/figures/Makefile. Then in the it/Makefile.am
change '../c/figures' to 'figures'. Then you need to get all the new
shot as .png images into it/figures.



SOURCE MANUAL
-------------

The source manual is the French version -- in the fr directory. This
means this is the version where new stuff is written first.

The international version -- in English -- is in the c directory, we
keep it as best as we can up to date with the French version.

In short, if you can read French, you should update your national
manual from this manual. Otherwise, use the international version in
the C directory.


DR GEO MANUAL VERSION
------------------------

When a manual version is ready (i.e. to be translated to other
languages or up to date with the original version) it is tagged in the
CVS. The tag names are of the form version-X_X where X are
numbers. The first version is always version-1_0.

Examples:

To mark the fr/drgenius.tex ready to be translated to other language
we mark it with the following command:

	cvs tag version-1_0 fr/drgenius.tex

To mark the it/drgenius.tex as up to date to the version-1_1 of the
French manual we use the following command:

	cvs tag version-1_1 it/drgenius.tex


IMPORTANT NOTE FOR TRANSLATOR
-----------------------------

\xname{} instructions must not be translated. These commands set hooks
for the Dr. Geo on-line help manual. Translating the commands will
just broke the Dr. Geo on-line help system (i.e. the user will not get
the required help section).


STARTING THE TRANSLATION
------------------------

Let's see with an example:

Let's say you want to create a new Dutch version of the manual. The
country code is nl (you may want to have nl_BE and nl_NL)

1. fetch the whole drgenius-man module from the OFSET CVS

	cvs -d:ext:hilaire@cvs.sourceforge.net:/cvsroot/ofset co drgenius-man

2. create the manual directory and related data

	cd drgenius-man
	mkdir nl

3. edit the following files, necessary to resp. autoconf and automake.

        a. In configure.ac, add  nl/Makefile  to the list of AC_CONFIG_FILES:

	AC_CONFIG_FILES([
	Makefile
	c/Makefile
	fr/Makefile
	...
	nl/Makefile)]

	b. In Makefile.am, add  nl  to the list of subdirectories:

	SUBDIRS = c es fr ... nl

4. fetch the last stable manual version you want to translate
from. Let's say you want to translate from the French version.

	a. First see what the latest stable version of the French manual is

	cvs update
	cat fr/version

	Let's say the previous command returns version-1_2

	b. Fetch the French version-1_2 from the CVS and commit

	cvs add nl
	cd nl
	cp ../fr/Makefile.am .  (edit the file to set the appropriate path)
				(just replace fr by nl)
	touch ChangeLog version	
	cvs get -r version-1_2 -p drgenius-man/fr/drgenius.tex > drgenius.tex
	cvs get -r version-1_2 -p drgenius-man/fr/topic.dat > topic.dat
	
	You are ready to translate the drgenius.tex and topic.dat to Dutch. 
	
	
	When translations are done, commit the files to the CVS server:
	
	cvs add drgenius.tex Makefile.am ChangeLog version topic.dat
	cvs -z3 commit -m "Initial set-up of the manual."

	The add operation is only need once, then updates to the files can
	be commited with the commit command.


5. Once the translation is up to date and you are sure about that,
 mark it as version-1_2 (do not forget to commit once more before tagging):

	echo "version-1_2" > nl/version
	cvs -z3 commit "Updated version."
	cvs tag version-1_2 nl/drgenius.tex



UPDATING A TRANSLATION
----------------------

The updates of the translated manuals are organised with the TAG
system which comes with CVS. We use this system to mark new manual
version ready to be translated. The last stable version can be found
from the version file within the respective directory of the manual.

In a few words, to update a translated manual from one stable version
to the next stable one of the source language manual, we look at the
differences between the last two stable versions of the source
language manual, then apply this differences to our translated manual.

In the following we will take an example to explain further how to
proceed.

Let's say we have the Dutch manual version-1_1 up to date while the
release version-1_2 of the French source manual is committed into the
CVS. 

Note: To know what is the latest stable version of the French source
manual proceed as:

	cd your-working-copy
	cvs update
	cat fr/version

The Dutch maintainer will want to apply to its manual the
differences between the version-1_1 and version-1_2 in the French
manual. All this means the maintainer will need:

	- the Dutch manual version-1_1
	- the French manual version-1_1
	- the French manual version-1_2

Here how we proceed:

	cd nl
	cvs get -r version-1_1 -p drgenius-man/fr/drgenius.tex > drgenius-1_1.tex
	cvs get -r version-1_2 -p drgenius-man/fr/drgenius.tex > drgenius-1_2.tex

Then look at differences with a command like

	diff -u drgenius-1_1.tex drgenius-1_2.tex | less

	or

	diff -u drgenius-1_1.tex drgenius-1_2.tex > diff.txt


Lines deleted from drgenius-1_1.tex begin with the sign '-' and lines
added to drgenius-1_2.tex begin with the sign '+'. Some lines before and
after these changes are the same.

The diff document produced with the diff command may not always be easy
to read. There is an alternative tool to look at the differences. The
section UPDATING A TRANSLATION WITH EMACS explains this tool.


UPDATING A TRANSLATION WITH EMACS
---------------------------------

You can use the GNU Emacs Ediff (Menu Tools->Compare->..)  to look at
the differences.

Start Emacs, then go to the menu Tools->Compare->Two Files... (or use
M-x ediff-files).

Select the files  nl/drgenius-1_1.tex  nl/drgenius-1_2.tex

(Note: Remember, those drgenius-1_1.tex and drgenius-1_2.tex files are 
the French versions we fetch from the CVS into the nl directory)

Emacs will show you the differences between these two versions. You
can browse them with 'n' and 'p' ('?' toggle key for help).

You can now open in a third view (C-x 4 f or open a new frame with C-x
5 f) the source of the Dutch source manual (nl/drgenius.tex)



When the translation is up to date, mark it as version-1_2 (do not
forget to commit it a very last time before tagging)

	echo "version-1_2" > nl/version
	cvs -z3 commit "Updated version."
	cvs tag version-1_2 nl/drgenius.tex

Then you can safely delete the drgenius-1_1.tex and drgenius-1_2.tex file

	rm nl/drgenius-1_1.tex
	rm nl/drgenius-1_2.tex


NOTE: Of course, if you translated from the international version, you
just need to replace every 'fr' by 'c'.



Comment, remarks, proofreading are very welcome to enhance this
document.






IN PROGRESS
-----------

DO NOT READ HERE. Documented function may not work for now.

A more easy way for comparing two versions is to use
vc-minor-mode. With an updated working directory, you have to edit the
last version of drgenius.tex. For example, the mode line contains
somethinglike CVS-1.2 for drgenius-1_2.tex. Then use : 

	C-x v ~

and type 1.1 to obtain the previous version of the file (see C-h m and
Version Control in the Emacs manual for more help on VC minor mode). A
new buffer is created. Then use :

	M-x ediff-buffers

and validate two times (Emacs should propose the correct buffers). You
have now previous version of the file (v1.1) at the top and the last
one (v1.2) at the bottom of the frame. You can browse differences with
'n' and 'p' ('?'  toggle key for help).


$Id: README,v 1.12 2003/08/12 14:49:15 hilaire Exp $