translators README modified

[Adam Di Carlo <aph@debian.org>]

If you are on the 'To' line of this message, you are listed as a
translator for the Install Manual.  Let me know if you do not wish to
get such messages, or if the listed translators is incorrect in any
way.

I hope the translation efforts are going well.

As you may already be aware, the web source access page to the
Installation Manual has changed; see below.

Also, I've added messages_$(LINGUA).ent files to that directory, which
hopefully will really help those who don't have CVS access to the
whole boot-floppies sources.

I am still eagerly awaiting the first install.$(LINGUA).sgml file (or
for the other two SGML files.  As you may or may not know, the
'all-arch-docs' target from the top-level Makefile is used to build
some of the web pages at <URL:http://www.debian.org/releases/slink/>;
I hope to use Apache content negotiation to build these files right
out of the sources. It's going to be a bit hairy, so please do me a
favor and check in or email me for checking a translated SGML file.

>From what Martin Schulze tells me, it might not be feasible for me to
build i18n PDF files, but I can deal with that.

I'm including the updated README-authors file, which you can also get
from the web site.  Please read through this file; I've added more
information for translators here, specifically, an area called
'Translation Issues'.

--
.....Adam Di Carlo....adam@onShore.com.....<URL:http://www.onShore.com/>


This is the boot-floppies documentation area.  For maximum
maintainability, I have endeavored to eliminate as many instances of
'double-coding' as feasible.  That is, instead of having to set a
variablein the top-level Makefile, *and* update the documentation, you
only have to set the top-level Makefile.

However, naturally, this makes the documentation area a little bit
more complex than people might be useful.  This document explains some
of the features and ways I did this, as well as how the SGML
documentation contains switches for different platforms.

* Getting the Newest SGML Source

Go to <URL:http://www.debian.org/releases/slink/source/>.  This is
updated manually when significant changes are made (more often than
boot-floppies package releases).


* Platform "flavors"

A different version of each document is made for each architecture.
Use 'make all-arch-docs' on the top level to create all architectural
flavors of the installation manual.

This is accomplished in the text using SGML marked sections.  See SGML
references for more info on marked sections.  Briefly, you have
parameters for the different architectures, i.e., '%i386'.  This is
set automatically in the 'dynamic.ent' file; see the '%' entities in
'defaults.ent' for details on what parameter entities are available.

If you want to mark a paragraph or any SGML text as i386-only, for
instance, use this SGML construct:

  <![ %i386 [  INSERT TEXT HERE ]]>


* Makefile targets

Currently, the boot-floppies is setup with a few top-level 'make' targets:

 - 'make docs'

	make documentation for your architecture, current
	language setting

 - 'make all-arch-docs'

	make documentation for all architectures, current language
	setting

You can override the defaults (such as language and architecture) by
setting some of the variables explicitly below, either on the command
line or in the top-level Makefile (or better yet, 'Makefile.config').


* Variables set via 'make'

These variables are automatically set, and placed into the dynamic.ent
file:

 - kernelversion (KVER), altkernelversion (ALTKVER), language
   (LINGUA), release (RELEASE), architecture (architecture),

	set from top-level Makefile (configure in ../Makefile or
	../Makefile.config), using the names in the parentheses

 - docversion, docdate
	set from ../debian/changelog

 - FDISK_DOC
	looks at the root disks EXTRACT list for '*fdisk', determining
	which fdisk programs are available for your platform.  It will
	be populated with strings like `cfdisk.txt' or `atari-fdisk.txt'.
	Then rules with the names of the values of this variable
	engage, which will extract the man pages from the actual
	packages (util-linux, etc) which contain the programs.  It
	finds the packages just as the top-level Makefile does; use
	../Makefile.config to override

	If a given architecture has a given fdisk flavor, not only is
	<fdisk-flavor>.txt built, but also the parameter entity
	%<fdisk-flavor>.txt is defined.  For instance, '<![ %cfdisk.txt [
        ... ]]>' can be used to conditionally include information
	relevant to cfdisk.

	Failure during the execution of these rules is tolerated,
	although that may change

* Variables from dbootstrap messages

messages.ent is automatically generated from the dbootstrap (also
known as dinstall) gettext messages using a script called cpp2sgml.
This takes the `cpp' defines such as MSG_NEXT and turns it into:

   <!entity MSG-NEXT "``Next''">

It automatically adjusts for the current setting of LINGUA variable.


* URLS

All urls are stored in the file `urls.ent', set manually.  This file
should be considered language neutral; if we have translated versions
of these URLs available, we should use marked sections to define
alternate values for the variables.


* Other variables

Other variables are stored in the file `defaults.ent' and set
manually.  These include a number of bits of information which have
been folded out into this file since they either occur repeatedly, or it
is simply more convenient to keep these likely to change bits of
information separate.

Amongst the variables set there include variables such as
&num-of-distrib-pkgs (number of packages distributed with the system)
and %workaround-bug-XXXX (which are used to easily identify and
disable text working around a specific bug).

** Translation Issues

First off, the boot-floppies are not setup optimally for translations.
They are setup to make a completely new set of files for each
language.  The language-specific elements are really only the
documentation, and the stuff on the Rescue Image and the Driver Image
(and root.bin).  The base system has multi-lingual support.  We are
looking to improve this for the next release, but space is at a
premium on root.bin.

Secondly, you should probably get the entire CVS boot-floppies tree.
Unfortunately, it is currently setup in a non-official location
(master.debian.org:/debian/home/sr1/lib/cvs/boot-floppies). If you
have an account on master you can use CVS's :ext: protocol (and set
CVS_RSH to ssh) to retrieve the sources.

If you don't have an account on master, you'll have to download them
from the web <URL:http://www.debian.org/releases/slink/source/>.  This
location includes a ChangeLog and messages_$(LINGUA).ent files.
You'll have to move or link into place the right 'dynamic.ent' and
'messages.ent' files.

Finally, we have decided that it would be best if we keep all the
translations of all the Installation Manuals in the boot-floppies
documentation subdirectory itself.  What I propose to do is to have,
for instance, the French version of the Installation Manual be named
documentation/install.fr.sgml, and so forth.

Rigth now the documentation/Makefile does not have the facilities to
switch by LINGUA and select the right translation; but I'm just
wanting for the first translation to be entered into the system to
start building this logic in the Makefile.  We might have to make a
few hacks on 'debiandoc-sgml' as well.


** Known Translators

The following translators have volunteered (*gulp*) to help translate
the Installation Manual to other languages.  Work is actively
underway.

The following are the list of parties who have volunteered to help
translate the Installation Manual, in no particular order.  The
structuration and facilitation of this work by the boot-floppies team
is unclear and being worked out.

Finnish:	Tapio Lehtonen <tale@iki.fi>
		Antti-Juhani Kaijanaho <gaia@iki.fi>

German:		Hartmut Koptein <koptein@et-inf.fho-emden.de>
		Philipp Frauenfelder <pfrauenf@debian.org>
		Martin Schulze <joey@infodrom.north.de>

Croatian:	Matej Vela <mvela@public.srce.hr>

Italian:	Paolo Didonè <dido@prosa.it>

Spanish:	Enrique Zanardi <ezanard@debian.org>
		Tinguaro Barreno <tbarreno@debian.org>
		Pedro Gracia <pedro@id-agora.com>
		Angel David Rancel Mendoza <root@delegacion.fisica.ull.es>

Portuguese:	Eduardo Marcel Macan <macan@debian.org>
		Jose Carlos Benfati <benfati@zzp.com.br>
		Gleydson Silva <gleydson_s@yahoo.com>

Japanese:	Yoshizumi Endo <y-endo@ceres.dti.ne.jp>

Bulgarian:	George Tchavdarov <george@sagabg.net>

French:		Christophe Le Bars <clebars@debian.org>