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 . 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: * 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 .txt built, but also the parameter entity %.txt is defined. For instance, '' 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: 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 . 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: ]]> ** Known Translators See ../README-Translators.