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/stable/source/>.  This will
probably change to the 'unstable' area soon.  The area 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

The boot-floppies code tree is not setup optimally for translations.
Currently, one has to make a completely different build 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 itself has multi-lingual support.  We
are looking to improve this for the next release, but space is at a
premium on root.bin.  As a translator, that doesn't affect you
overmuch, but it is good to be aware of it.

To translate, you should probably get the entire CVS boot-floppies
tree.  See ../README-CVS for information on how to do this.

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.

All translations of the SGML files should go in the documentation
subdirectory itself.  Name the French version of the Installation
Manual 'documentation/install.fr.sgml', and so forth.  If you
define a lot of little small files, you can do like we did for the
English version and put the files in documentation/en/*.sgml.

If you would like to point to language-specific URLs for urls.ent,
rather than copying that file and modifying it, you should use the
language switches to override the entities:

  <![ %lang-ja [ <!entity url-debian-policy
    "http://www.debian.or.jp/Documents/Documents_ja/debian-policy/"> ]]>
  <!entity url-debian-policy "http://&www-debian-org;/doc/debian-policy/">



** Known Translators

See ../README-Translators.

