2002-06-03
							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...

With 0.11.24, one disruptive change is that the "Smart Size" (also
known as "IQSize") content type is no longer supported, and not
properly detected on load either. gentoo will map *any* unknown
content type into a Size column.

0.11.25 adds another disruptive change. Shortcuts are transformed
from being a separate feature to being just another sheet of good
old buttons. This means they get saved among the buttons, too. There
is no support for loading the old-style Shortcut information, so
you will simply lose your shortcuts. Luckily, redefining them should
be fairly straight-forward.

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 to
make gentoo *write* an old-style configuration 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.


IV. DIRPANE SORTING

VERSION
any pre-0.11.14 to 0.11.14

NESTING
 <DirPanes>
  <DirPaneLeft> and <DirPaneRight>
   <DPSort>
    <column>

NAME		TYPE			FUNCTION
column		a dirpane column index	Which column to sort by. 

CHANGES
As of gentoo 0.11.14, it is possible to sort on any type of
*content*, not only those actually displayed in a given pane.
	This field has simply been removed, and replaced by a
field called "content", whose (textual) value is the name of the
content type to sort by.
	This is a very minimal, yet somewhat disruptive, change,
since the loading code in 0.11.14 makes no attempt to translate
an incoming "old-style" column index to a content type. On the
other hand, all you need to do to get back in shape is click the
column you wish to sort by, and save the config...