| 1 |
2002-06-03 |
| 2 |
Emil Brink |
| 3 |
|
| 4 |
gentoo |
| 5 |
CONFIGURATION FILE FORMAT CHANGES |
| 6 |
|
| 7 |
0. INTRODUCTION |
| 8 |
Notes to help me maintain (or at least minimize loss of) config |
| 9 |
file compatibility between various gentoo releases. |
| 10 |
|
| 11 |
Note that I always try to make gentoo auto-convert the configuration |
| 12 |
file. This means that the format loaded is not always the same as |
| 13 |
the one saved, i.e. gentoo will (silently) "convert" the configuration |
| 14 |
file. As always, gentoo will not save the config file unless you tell |
| 15 |
it to, so there is never any risk of "losing" your old config. |
| 16 |
|
| 17 |
When a config file format change occurs, it is recommended to simply |
| 18 |
start the version of gentoo in which the change occured, and let it |
| 19 |
load your old config. Then check around to see if you've lost any |
| 20 |
important settings. If not, just click "Save" in the configuration |
| 21 |
window, to convert the file into the new format. If there are losses, |
| 22 |
read below for possible tips on how to recreate relevant data... |
| 23 |
|
| 24 |
With 0.11.24, one disruptive change is that the "Smart Size" (also |
| 25 |
known as "IQSize") content type is no longer supported, and not |
| 26 |
properly detected on load either. gentoo will map *any* unknown |
| 27 |
content type into a Size column. |
| 28 |
|
| 29 |
0.11.25 adds another disruptive change. Shortcuts are transformed |
| 30 |
from being a separate feature to being just another sheet of good |
| 31 |
old buttons. This means they get saved among the buttons, too. There |
| 32 |
is no support for loading the old-style Shortcut information, so |
| 33 |
you will simply lose your shortcuts. Luckily, redefining them should |
| 34 |
be fairly straight-forward. |
| 35 |
|
| 36 |
To minimize excess baggage in the code, I would like to get rid of |
| 37 |
the loading code for old-style config formats at some point in the |
| 38 |
future. Therefore, please convert your config file, even if it |
| 39 |
doesn't seem strictly necessary. Of course, once you make a config |
| 40 |
change and click "Save", the file is converted. There is no way to |
| 41 |
make gentoo *write* an old-style configuration file. |
| 42 |
|
| 43 |
|
| 44 |
I. FILE STYLES |
| 45 |
|
| 46 |
VERSION |
| 47 |
any pre-0.11.7 to 0.11.7 |
| 48 |
|
| 49 |
NESTING |
| 50 |
<FileStyles> |
| 51 |
|
| 52 |
NAME TYPE FUNCTION |
| 53 |
Style Style description The entire style description format |
| 54 |
has changed. |
| 55 |
|
| 56 |
CHANGES |
| 57 |
The entire <Styles> tag has a completely new internal format. |
| 58 |
Properties are now identified by name, rather than weird hard- |
| 59 |
coded index integers as they were before. |
| 60 |
|
| 61 |
COMPATIBILITY TACTICS |
| 62 |
The current code loads old-style (pre-0.11.7) config files just |
| 63 |
fine, and silently converts them into the new format the next |
| 64 |
time you save. |
| 65 |
|
| 66 |
|
| 67 |
II. BUTTON FIELDS |
| 68 |
|
| 69 |
VERSION |
| 70 |
any pre-0.11.6 to 0.11.6 |
| 71 |
|
| 72 |
NESTING |
| 73 |
<ButtonSheets> |
| 74 |
<ButtonSheet> |
| 75 |
<ButtonSheetRows> |
| 76 |
<ButtonRow> |
| 77 |
<ButtonRowButtons> |
| 78 |
<Button> |
| 79 |
<narrow> AND <show_tooltip> |
| 80 |
|
| 81 |
NAME TYPE FUNCTION |
| 82 |
narrow boolean Flag: is button narrow? |
| 83 |
show_tooltip boolean Flag: show button's tooltip? |
| 84 |
|
| 85 |
CHANGES |
| 86 |
These two flags are no longer stored as individual boolean XML |
| 87 |
nodes. Rather, their data is packed into a binary flags word, |
| 88 |
which is then stored as a single unsigned integer. This makes |
| 89 |
the config file less readable, but also makes it smaller and |
| 90 |
lets the code be slightly more efficient. I think it's OK. |
| 91 |
|
| 92 |
COMPATIBILITY TACTICS :) |
| 93 |
Keep old-style parsing code in for a while. This will allow |
| 94 |
old config files (containing the "narrow" and "show_tooltip" |
| 95 |
XML tags explicitly) to still be read in. Stop writing these |
| 96 |
fields; just write the binary-packed version. |
| 97 |
|
| 98 |
In a few releases, I hope that enough people have upgraded "in |
| 99 |
the correct way", so this redundant config parsing code is no |
| 100 |
longer required. |
| 101 |
|
| 102 |
|
| 103 |
III. STYLE COLORS |
| 104 |
|
| 105 |
VERSION |
| 106 |
any pre-0.11.6 to 0.11.6 |
| 107 |
|
| 108 |
NESTING |
| 109 |
<FileStyles> |
| 110 |
<Style> |
| 111 |
<Properties> |
| 112 |
<Property> |
| 113 |
<Color>, <red>, <green> AND <blue> |
| 114 |
|
| 115 |
NAME TYPE FUNCTION |
| 116 |
Color RGB color info A style's color. |
| 117 |
|
| 118 |
CHANGES |
| 119 |
There is now a leaf-type XML node for colors, so these four nodes |
| 120 |
have been replaced by a single one, in this case called <color>. |
| 121 |
|
| 122 |
COMPATIBILITY TACTICS |
| 123 |
The old-style style-loading code is still in there, and will remain |
| 124 |
for the next few releases. |
| 125 |
|
| 126 |
|
| 127 |
IV. DIRPANE SORTING |
| 128 |
|
| 129 |
VERSION |
| 130 |
any pre-0.11.14 to 0.11.14 |
| 131 |
|
| 132 |
NESTING |
| 133 |
<DirPanes> |
| 134 |
<DirPaneLeft> and <DirPaneRight> |
| 135 |
<DPSort> |
| 136 |
<column> |
| 137 |
|
| 138 |
NAME TYPE FUNCTION |
| 139 |
column a dirpane column index Which column to sort by. |
| 140 |
|
| 141 |
CHANGES |
| 142 |
As of gentoo 0.11.14, it is possible to sort on any type of |
| 143 |
*content*, not only those actually displayed in a given pane. |
| 144 |
This field has simply been removed, and replaced by a |
| 145 |
field called "content", whose (textual) value is the name of the |
| 146 |
content type to sort by. |
| 147 |
This is a very minimal, yet somewhat disruptive, change, |
| 148 |
since the loading code in 0.11.14 makes no attempt to translate |
| 149 |
an incoming "old-style" column index to a content type. On the |
| 150 |
other hand, all you need to do to get back in shape is click the |
| 151 |
column you wish to sort by, and save the config... |