ILocale->OpenCatalog()

This forum is for general developer support questions.
Post Reply
User avatar
mritter0
Posts: 214
Joined: Mon Aug 25, 2014 9:41 pm
Location: Bettendorf, IA, USA

ILocale->OpenCatalog()

Post by mritter0 »

I was doing some updating to my code for Locale handling. I was reading the AutoDocs for
OC_Version (uint16) - catalog version number required. Default is 0
which means to accept any version of the
catalog that is found. Note that if a version
is specified, the catalog's version must match
it exactly. This is different from version
numbers used by OpenLibrary().
Note: Do not call OpenCatalog() without
specifying OC_Version when you prefer
(but not require) a specific version.
In such cases call it with OC_Version and
fall back to a second call without OC_Version
when the first call returned NULL.
I have always done this in my .cd file:
; $VER: workbenchexplorer.catalog 1.5 (19.07.2017)

When really it should be:
; $VER: workbenchexplorer.catalog 15 (19.07.2017)

No decimal between version and revision. Or whatever whole number I want to use.

Correct? Sounds like it is to me.

If so, I have never seen anyone do it this way; always 1.1 or whatever.
Workbench Explorer - A better way to browse drawers
User avatar
thomasrapp
Posts: 310
Joined: Sat Jun 18, 2011 11:22 pm

Re: ILocale->OpenCatalog()

Post by thomasrapp »

Version tags are always version-dot-revision. (The dot is a seperator, not a decimal point. 1.10 is a higher revision than 1.9.)

Only the version number (the part before the dot) is checked by OpenCatalog and similar functions.

If you want to check for a specific version, you have to change the version number, not the revision number. So in your case it would be 2.5 for example. Then you can check for version 2 of the catalog.

Be aware of the consequences if you check for a version number on OpenCatalog: as the autodoc says, the version of the catalog must match exactly. Be prepared that your translators will be quite confused if they supply a catalog which will not be loaded because of mismatching version.
User avatar
nbache
Beta Tester
Beta Tester
Posts: 1714
Joined: Mon Dec 20, 2010 7:25 pm
Location: Copenhagen, Denmark
Contact:

Re: ILocale->OpenCatalog()

Post by nbache »

thomasrapp wrote:Be aware of the consequences if you check for a version number on OpenCatalog: as the autodoc says, the version of the catalog must match exactly. Be prepared that your translators will be quite confused if they supply a catalog which will not be loaded because of mismatching version.
OTOH, translators should know to give their translations a version number which corresponds to the version command in the .cd file. Its purpose is to make sure no earlier (or later) versions are used than the one the developer is supporting with the .cd (and therefore the program).

But of course, with a little care, developers should never need this tool, as they can keep catalogs backwards compatible by not inserting strings in the middle of the .cd file (or explicitly specify their IDs and keep them the same).

Best regards,

Niels
User avatar
mritter0
Posts: 214
Joined: Mon Aug 25, 2014 9:41 pm
Location: Bettendorf, IA, USA

Re: ILocale->OpenCatalog()

Post by mritter0 »

Gotcha. Maybe that should be made a bit more clear in the AutoDocs.

So then people should be doing:

Program Version: 1.5
Catalog Version: 15.0

Program Version: 1.6
Catalog Version: 16.0

Program Version: 2.0
Catalog Version: 20.0

etc. Or whatever way they want.

So they can specify OC_Version,16, and get the results they want. OC_Version,1, will succeed with every version of 1.x since it does not look at revision.

And like Niels said, this shouldn't be an issue by adding new strings at then end (which I do), but some day it might burn someone when they make a major change in their program.
Workbench Explorer - A better way to browse drawers
User avatar
broadblues
AmigaOS Core Developer
AmigaOS Core Developer
Posts: 600
Joined: Sat Jun 18, 2011 2:40 am
Location: Portsmouth, UK
Contact:

Re: ILocale->OpenCatalog()

Post by broadblues »

mritter0 wrote:Gotcha. Maybe that should be made a bit more clear in the AutoDocs.

So then people should be doing:

Program Version: 1.5
Catalog Version: 15.0

Program Version: 1.6
Catalog Version: 16.0

Program Version: 2.0
Catalog Version: 20.0

etc. Or whatever way they want.

So they can specify OC_Version,16, and get the results they want. OC_Version,1, will succeed with every version of 1.x since it does not look at revision.

And like Niels said, this shouldn't be an issue by adding new strings at then end (which I do), but some day it might burn someone when they make a major change in their program.
I think you've still missed the point.

There is no correlation between the program number and the catalog, so multplying by ten as in your examples is plain pointless.

You should bump the version number of the catalog, if it becomes in compatable with previous versions, which can be avoided, as noted, by taking care with the arrangement of strings.

So the version of the catalog might increment like so

1.1 first version
1.2 add more strings but keep order compatable
1.3 same again
1.4 fix some typos
1.5 add a few more strings
2.1 reorganise strings (because you ran out of space when you only allowed for 20 menustrings perhaps) no longer compatable so require version 2 in the OpenCatalog() command
2.2
2.3
2.4
3.1 Main program got total rewrite requireing new catalog. Up required version.
3.2

etc etc
User avatar
nbache
Beta Tester
Beta Tester
Posts: 1714
Joined: Mon Dec 20, 2010 7:25 pm
Location: Copenhagen, Denmark
Contact:

Re: ILocale->OpenCatalog()

Post by nbache »

Also, the .cd file's "#version" command takes an integer (this is e.g. the "2" broadblues refers to at 2.1 above), which is the exact version (regardless of revision) that catalogs must have to be accepted with it. Some developers also maintain a separate $VER: string with a version.revision in the .cd file, but this is not required and has no impact on whether the catalog can match.

Translators (can) keep their own versioning of their .ct files, but the version part must correspond to the #version in the .cd file, if one is present there. The revision part can be used to track ongoing translation changes.

The .catalog will get the same version.revision as the .ct file it is compiled from.

Best regards,

Niels
Post Reply