							1999-05-27
							Emil Brink

				gentoo
		CONFIGURATION FILE FORMAT CHANGES

0. INTRODUCTION
Notes to help me maintain (or at least minimize loss of) config
file compatibility between various gentoo releases.

Note that I always try to make gentoo auto-convert the configuration
file. This means that the format loaded is not always the same as
the one saved, i.e. gentoo will (silently) "convert" the configuration
file. As always, gentoo will not save the config file unless you tell
it to, so there is never any risk of "losing" your old config.

When a config file format change occurs, it is recommended to simply
start the version of gentoo in which the change occured, and let it
load your old config. Then check around to see if you've lost any
important settings. If not, just click "Save" in the configuration
window, to convert the file into the new format. If there are losses,
read below for possible tips on how to recreate relevant data...

At time of writing (0.11.7), there are no known disruptive config
format changes. Just save the config, and it gets converted over.

To minimize excess baggage in the code, I would like to get rid of
the loading code for old-style config formats at some point in the
future. Therefore, please convert your config file, even if it
doesn't seem strictly necessary. Of course, once you make a config
change and click "Save", the file is converted. There is no way of
making gentoo *write* and old-style config file.


I. FILE STYLES

VERSION
any pre-0.11.7 to 0.11.7

NESTING
 <FileStyles>

NAME		TYPE			FUNCTION
Style		Style description	The entire style description format
					has changed.

CHANGES
The entire <Styles> tag has a completely new internal format.
Properties are now identified by name, rather than weird hard-
coded index integers as they were before.

COMPATIBILITY TACTICS
The current code loads old-style (pre-0.11.7) config files just
fine, and silently converts them into the new format the next
time you save.


II. BUTTON FIELDS

VERSION
any pre-0.11.6 to 0.11.6

NESTING
 <ButtonSheets>
  <ButtonSheet>
   <ButtonSheetRows>
    <ButtonRow>
     <ButtonRowButtons>
      <Button>
	<narrow> AND <show_tooltip>

NAME		TYPE			FUNCTION
narrow		boolean			Flag: is button narrow?
show_tooltip	boolean			Flag: show button's tooltip?

CHANGES
These two flags are no longer stored as individual boolean XML
nodes. Rather, their data is packed into a binary flags word,
which is then stored as a single unsigned integer. This makes
the config file less readable, but also makes it smaller and
lets the code be slightly more efficient. I think it's OK.
			
COMPATIBILITY TACTICS :)
Keep old-style parsing code in for a while. This will allow
old config files (containing the "narrow" and "show_tooltip"
XML tags explicitly) to still be read in. Stop writing these
fields; just write the binary-packed version.

In a few releases, I hope that enough people have upgraded "in
the correct way", so this redundant config parsing code is no
longer required.


III. STYLE COLORS

VERSION
any pre-0.11.6 to 0.11.6

NESTING
 <FileStyles>
  <Style>
   <Properties>
    <Property>
     <Color>, <red>, <green> AND <blue>

NAME		TYPE			FUNCTION
Color		RGB color info		A style's color.

CHANGES
There is now a leaf-type XML node for colors, so these four nodes
have been replaced by a single one, in this case called <color>.

COMPATIBILITY TACTICS
The old-style style-loading code is still in there, and will remain
for the next few releases.
