               Overview of Boot-Floppies Documentation
                For Document Authors and Contributors

* Getting Started: useful Makefile rules

The docs in boot-floppies/documentation are provided in source SGML format
only, and you need to build the docs in output formats (such as HTML, PDF or
plain text). This is done with a few easy makefile rules:

  make uni-docs
	builds documentation for one language, single architecture

  make all-lang-docs
	builds documentation for all available languages, single architecture

  make all-arch-uni-docs
	builds documentation for one language, all architectures

  make all-arch-all-lang-docs
	builds documentation for all available languages, all architectures

  make lint-docs
	ensures your SGML is valid, single language, all architectures
	Add e.g. "LINGUA=de" to verify the German translation.
	-- please use this to verify a translation --

  make lint-all-lang-docs
	ensures SGML is valid, all languages, all architectures
	-- please use this if you have modified multiple languages --


Note that the validating SGML parser is run automatically by debiandoc2*
commands that build the documents, this rule just enhances its checks.

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 `config' file.

By default, documents that will be built include the Installation Manual
(install*.sgml), the fdisk and similar programs' manpages in text
(*fdisk.txt), the dselect Documentation for Beginners
(dselect-beginner*.sgml) and the short index file for use in web pages.
The Release Notes (release-notes*.sgml) are built separately.


* Getting the Newest SGML Source

If you can use CVS, either locally on cvs.debian.org, using 'pserver',
or using ssh or some such rsh replacement, then you should use that.
See ../README-CVS.

If you cannot, then you should be able to get it using the web interface:

  http://cvs.debian.org/boot-floppies/documentation/


* Notating TODO Or FIXME Items in Text

Use the entity &FIXME to notate any areas which need work.  This will
only be shown when %FIXME is set to INCLUDE in defaults.ent, so we can
easily remove it.

See install.sgml for how the FIXME entity is set in English version.


* Platform-Specific Versions

A different version of each document is made for each architecture.
Use 'make all-arch-uni-docs' to create all architectural flavors.

We can have a single document which has many different possible output
versions by using SGML marked sections.  See SGML references for more
info on marked sections, for instance,
<URL:http://www.freebsd.org/tutorials/docproj-primer/sgml-primer-marked-sections.html>.

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 ]]>


* Language-Independent Static Data

In order to have our documentation be more maintainable, we try to
separate any data which is not language-dependent out into separate
entity ('*.ent') files.

The following files contain language-independent data:

** urls.ent

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.

** defaults.ent

System type data and other entities which are statically maintained
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).


* Dynamic Information

The Makefile relies on a number of variables set from the top-level
`config' file to automatically populate data in the documentation.

The reason why we like to automatically populate data is because that
makes for more easily maintained documentation.  Keeping documentation
up-to-date is already an arduous take -- we do every thing we can to
simplify it.  Double-keyed information is bad.

The following files contain dynamically generated data:

** dynamic.ent

The dynamic information from ../config is transmitted to the SGML via the
file 'dynamic.ent'.  It contains entities like what architecture we are
building for, the kernel version boot-floppies were built with, the current
language, etc.

These are some of the important variables that are automatically set, and
placed into the 'dynamic.ent' file:

 - architecture (architecture), language (LINGUA), release (RELEASE),
   kernelversion (KVER), altkernelversion (ALTKVER)
	set from the top-level configuration file, ../config, using the
	names in the parenthesis

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

 - FDISK_DOCS
	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.  Failure during the
	execution of these rules is tolerated, although that may change. 
	They find the packages just as the top-level Makefile does; edit
	../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.

** messages.ent

'messages.ent' file is automatically generated from the dbootstrap gettext
'pottext' files using a script called po2sgml.  This takes the gettext 
message catalogs and turns them into entities. For example, from
../utilties/dbootstrap/po/C.po:

  #: baseconfig.c:19
  msgid "No swap partition found"
  msgstr "No swap partition found"

Would be in messages.ent:

  <!entity No-swap-partition-found "``No swap partition found''">

It automatically adjusts for the current setting of LINGUA variable.
Entity names are the same for every language, but their content will
be translated.

'po2sgml' also emits a number of compatability entities.  These are
names of old (or, um, stable) messages.


* 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.

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/xy/*.sgml (where
xy is your country's code).

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.

** EOF **

$Id: README-authors,v 1.23 2001/12/08 15:19:24 claush Exp $

Local variables:
mode: outline
End:
