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 $