* AmigaWorld * created by Wolfgang Lug Documentation of version 1.0 1. What is AmigaWorld? ====================== AmigaWorld is a database program that contains information about every country on Earth. It enables you to have a look at the data of one country, or to compare several countries. It is very easy to handle, and you can use it with your favourite colors, font, and even language (at the moment there are English and German data files). It works on every Amiga that has one MByte of memory and Kickstart 1.2 or greater. 2. How do I start AmigaWorld? ============================= Nothing as easy as this: Under Workbench you just double-click on the icon. That's all. If you want to start AmigaWorld from the CLI, you have to make sure that AmigaWorld is in the current directory (e.g. cd df0:AmigaWorld). Otherwise it won't find the necessary data files. You receive a special font together with AmigaWorld. If you want to install it in your system, just double-click the InstallFont icon. CLI users enter: "execute InstallFont". Whether you install it or not, in every case you need the diskfont library on your boot disk. This library is included on every standard Workbench disk. 3. How do I make AmigaWorld "speak" other languages? ==================================================== After having started AmigaWorld, everything is displayed in English. But you can switch to another language! Just chose the item "Language" from the menu "Configuration". A new window pops up, and you are asked to enter the name of the new language. At the moment you can only choose between English and German, but I hope that future versions of AmigaWorld will give you more choice. If you want to translate AmigaWorld into a new language, feel free to do so! It is not very difficult, but it means a lot of work. See chapter 6 for details. 4. How to use AmigaWorld ======================== Just try and find out! Most features are easy to understand, but you might not notice some of the less intuitive features. Therefore here comes a quick survey about the AmigaWorld screen: The list of countries --------------------- The list of countries is on the right side. It contains all the countries that are selected. How to select and deselect countries will be described later on. If you move the mouse on a country's name and press the left button, a new window pops up where the available data for this country is displayed. With this method you can open up to ten country windows at the same time, thus enabling you to compare their data. You close the windows by hitting the close gadget in the upper left corner. The proportional gadget ----------------------- The proportional gadget in the middle of the screen enables you to move up and down in the country list. The map ------- The map has two functions, that are quite useful after a search: If you move the mouse upon the map and click the left button, the selection of the continents is restored as it was before the last search. If you hit the right mouse button over the map, all countries are selected (and thus displayed). The "Selection" menu is not influenced by this. The search gadget ----------------- The search gadget is below the map. If you type in some text and hit return afterwards, AmigaWorld searches for a country with the name you entered. If you have entered e.g. "Belgium", only Belgium will be selected and the data about it will be displayed in a new country window. If you enter "Guyana" AmigaWorld will select the independent state of Guyana and the French colony with the same name. If you're too lazy to type in the whole name or if you don't know it com- pletely, it is sufficient to enter the first letters and a star '*'. If you enter e.g. "fra*", France will be displayed. AmigaWorld knows several names for many countries: It doesn't matter if you enter "UK", "England" or "Great Br*"; the result is equal. Before starting a search, you should remember that AmigaWorld searches only the selected countries. If only European countries are selected, AmigaWorld won't find "China" or "Mexico". Therefore it is usually necessary to restore the old selection after every search: Just click on the map. It is not only possible to search for a country's name: You can also search for a country, if you know its capital; or you can search for all countries, where a specified language is spoken; or you can search for all countries in South East Asia, e.g. This depends on your selection in the "Search for" menu. By the way: The search function is still enabled, when you have already opened some country windows. 5. The Menus ============ A speciality, that should not be one ------------------------------------ Intuition gives you two ways of choosing a menu item: 1st) You press the right mouse button, move the mouse upon the item and release the right button. That is nothing new to you, I suppose. 2nd) You press the right mouse button, move the mouse upon the item and press the LEFT button, without releasing the right one. Probably you wonder why the guy is telling you this rather boring story. Well, with the second method it is not only possible to select one item, but three or four. So you can make your choice in the "Display" menu at once, or you can chose "Font" and "Colors" from the configuration menu at once. Especially if you use this on the "Selection" menu, you will notice that it works a lot faster than selecting five menu items one after another, each time waiting until the program processed the input. Although it is an intuition feature, it is not supported by many programs. Registrated users can have a look at the source code to see how it works; it's really simple. Coming next there is a description of all the menu items: The "AmigaWorld" menu --------------------- "About" whodunnit "User" tells how (and why) to become a registered user. If you are registered you will find your own name. "Quit" It does what it is suspected to do. WITHOUT any stupid questions if you really, really, really want to exit. The "Selection" menu -------------------- The upper six items tell AmigaWorld which continents shall be selected and thus displayed in the country list. If you want only information about African countries, just switch off the rest of the world! "Dependencies" If this item is activated, not only independent states are selected but all the other countries and territories, too, e.g. Greenland or Hong Kong. In the freeware version you cannot deactivate this one. The "Sort by" menu ------------------ If you select an item from this menu, the country list will be sorted. The order depends on the item you have chosen. If you chose "Area" the biggest countries are displayed first and the tiny ones last. "Name" The countries are not really sorted alphabetically, but in the same order as in the datafile. That has two advantages: - You can change the order, e.g. you can put colonies together with their mother countries. - It saved me a lot of work, because it would have been very complicated to write an algorithm that can cope with all the national chars. In the English version they are not important, but have a look at the German data file. Nearly everything contains an 'ä' or an 'ß' ... "Area" The country with the greatest area is displayed first. "Population" China is displayed on top, unsettled countries last. The other items work the same way, but they are only enabled in the version for registered users. The "Display" menu ------------------ This menu determines the looks of the country list. It is interesting especial- ly in connection with the "Sort by" menu. "Rank" The country list will be numbered. This is helpful when comparing countries. An example: You have chosen only "Europe" in the "Selection" menu and "Population" in the "Sort by" menu. The begin of the list would look like this: 1 Russia 2 Germany 3 Great Britain ... "Official Names" Instead of the common names (like Greece) the official names (like Greek republic) will be displayed. "Value" The value that corresponds with the "Sort by" menu will be displayed behind the names in the list, if this item is checked. "All Countries" AmigaWorld does not only display the selected countries but all the others, too. They are shown in another color, so you can still recognize which are selected and which aren't. It has no effect on the search feat- ure. The "Search for" menu --------------------- If you enter some text in the down left gadget, AmigaWorld by default searches for a country, with a name that is like your input. But you can also search for other things, depending on what you choose from this menu: "Name" ist the default setting. "Capital" From now on AmigaWorld will look for capitals that match your input. If you enter "Bo*" for example, Colombia (Bogota) and Germany (Bonn) will be selected. If you enter "Ber*", Germany (Berlin) and Switzerland (Bern) will be selected. As you know, AmigaWorld often knows different names or capitals for one country. "Language" You would like to know all countries, where the people speak English, Turkish or Swahili - no problem! At least not for registered users. "Location" If you chose this, it it usually better to enter the '*' in the search gadget. If you don't, AmigaWorld won't find countries with a longer description of their location. Example: If you enter "Central America", only the countries on the continent will be listed. But if you enter "Central America*" these countries AND the islands in the Carribean will be selected. This item is disabled in the freeware version. The "Configuration" menu ------------------------ This menu makes it possible to adjust AmigaWorld's outfit to your own prefer- ences: "Colors" A color requester comes up. Registered users can easily use it in their own programs. "Interlace" If you have a flicker-fixer (or tough eyes) you can turn interlace mode on/off. "Font" If you don't like my beautiful font (shame on you!) then you can select another one. Its size should not exceed 15 points. Why not? Try and fint out! "Language" This enables you to communicate with AmigaWorld in another language. At the moment you can choose between English and German, but who knows? Maybe YOU will send me a translation into your own language! "Save" This writes the current settings onto the disk. If you start AmigaWorld again, you will find your favourite configuration directly after the start. Disabled in the freeware version. 6. The awo files ================ awo.cfg ------- AmigaWorld reads some files after you started it. The one that is read first is called "awo.cfg". It contains the configuration data as you have saved it with the menu "Configuration"/"Save". If AmigaWorld cannot find this file it continues with the default values. Because you can easily modify "awo.cfg" with a text editor, it is not included in the freeware version, I'm sorry. awo.output ---------- The file "awo.output" contains all the texts, that are displayed by AmigaWorld. The file can either be in a subdirectory with the name of the language or in the same directory like AmigaWorld. If you have chosen English as language, AmigaWorld will try to open "English/awo.output". If it cannot open this file, the program looks for "awo.output". It is not too difficult to create a new translation of "awo.output": Just load one of the output files that came along with AmigaWorld into your favourite text editor. Now you have to translate it line by line. You should save the result in a new sub-directory with the name of the language. For example: An Italian output file should be saved as "Italiano/awo.output", a French one as "Française/awo.output", and so on. The first line must read "AWO-Output" (case-sensitive!) and the last line must consist of this char: '#'. It is possible to place comments in the output file: Everything that follows a semicolon ';' will be ignored. On the other hand you cannot specify output text that contains a semicolon, because AmigaWorld will only read the first part of it. Maybe you wonder about all those blank lines in the files? This is space for future versions! If there are e.g. new menu items, they can be placed between the existing ones. If there were no blank lines for this, everything had to be appended at the end, making the output data look rather confuse. A star '*' means, that the text of this line is the same in all translations, and thus internal (copyright, my address). awo.data -------- This file is the most important one. It contains all the information about the countries. These are as topical as possible (November 1992), but it would be strange if there weren't some mistakes in it. It was not easy for me to translate "awo.data" into English because this isn't my native language and I didn't know the English names of many countries, capitals, and languages. I could find some of them in dictionaries, but not all. Thus you will find some mis-spellings in my translation, e.g. in African languages or in the capitals of former Soviet republics. All translations that seemed strange to me are marked with two backslashes '\\', so you can glance thru the data file and check out for mistakes. Nevertheless, I ask you not to spread any modified data files. It is better to send your improvements directly to me. I will include them in future versions of AmigaWorld, making them available to a large number of users. What comes next is a description of the construction of "awo.data": The countries are listed in the order, in which they shall be displayed by AmigaWorld, i.e. alphabetically. The information about one country is written in nine lines, that stick together. line 1: The common names of the country. You can enter more than one name for a country. Only the first one will be displayed but if you use the search gadget, the other names will be recognized, too. They are divided by a vertical slash '|'. Example: "Netherlands|The Netherlands|Holland" line 2: The official name of the country. You can only specify one official name. That is sufficient, because you cannot search for official names anyway. line 3: The abbreviation, as it is used on number-plates. If the country is independent, its abbreviation is written in this line (e.g. "F" for France). Its length must not exceed three chars. If the country is not independent, the abbreviation of the mother country is written, enclosed by square brackets (e.g. "[F]" for Guadeloupe or French Polynesia). A question mark '?' means that the abbreviation is not known. line 4: The location: At the beginning of the line the continents are specified as figures: 1 = Africa, 2 = America, 3 = Asia, 4 = Australia and Pacific Ocean, 5 = Europe, 6 = Polar Regions. After a vertical slash the location is written as text. Example: "53|East Europe and North Asia" for Russia line 5: The capital(s): This line works exactly as line 1 with the country name: At the beginning there is the text that will be displayed in the country window. Afterwards there are other names that the search function will recognize, either. The names are divided by vertical slashes. Example: "Washington (DC)|Washington" But there are also countries with more than one capital. They are entered like this: "Berlin (government in Bonn)|Berlin|Bonn". line 6: The language(s). This line contains the languages that are spoken in the country. It works like line 1 and line 5. Example: "English and French|English|French" line 7: The area as square kilometres. AmigaWorld accepts only integer numbers. Usually it doesn't matter, but if you were consequent, you had to round off Vatican to zero ... line 8: The population. line 9: The Gross National Product as millions of US-$. To highten the readability of the file one can enter as many blank lines as one likes; I suggest one after every country. Comments are also possible: As in "awo.output", everything is ignored that follows a semicolon ';'. The semicolon should not be divided from the text by any spaces. If you enter "London ;that's were I live!" the search function will get confused and not recognize "London" but only "London ". The file must start with "AWO-Datafile" and end with a '#'. (Can anyone tell me what you call this stupid char?) If you want to translate "awo.data", you should know that it is a lot of work. I've seen that when I made the English version (groan). But I guess that it is much easier to translate something into one's native language than into a foreign language. So I encourage you to spend a few years on putting it into French or whatever! At least AmigaWorld will support your efforts: If you make a mistake, the program tells you, what went wrong and where it went wrong, i.e. the line number. The program searches for "awo.data" in the same way as for "awo.output". This has one advantage: If you translate only one of these two files, you can move the other one into its parent directory. Examplel: AmigaWorld (dir) Deutsch (dir) awo.output awo.data English (dir) awo.output Française (dir) awo.output AmigaWorld awo.data If you have this directory structure, there are different output texts for English, French, and German, but English and French use the same country file. This saves space on your disk, because you don't have to put the same file "awo.data" once into the directory "English" and once into the directory "Française". 7. Legal stuff ============== All folks that release a computer program write some stuff like this in their documentations. Maybe there is some sense in it, so I'm going to do it, too: The author will not be liable for any damage arising from the failure of this program to perform as described, or any destruction of other programs or data residing on a system attempting to run the program. While the author knows of no damaging errors, the user of this program uses it at his or her own risk. I stole it from the documentation of Patch 2.0 by Hartmut Stein who took it out of a readme by some other guy. You see, this is a paragraph with tradition! Of course I do not take any liability for the data files, either. 8. Distribution =============== The limited freeware version of AmigaWorld may be spread as you like it. I encourage you to make copies and give them to your friends! If you take money for copying AmigaWorld, the amount must not exceed the value that Mr Fred Fish of Tempe/Arizone takes for one disk. And you must spread the whole distribution as you have received it yourself. Please do not modify or delete any files from it. The entire list of files looks like this: AmigaWorld (dir) Deutsch (dir) awo.data awo.output Dokumentation Dokumentation.info Entwicklung Entwicklung.info English (dir) awo.data awo.output Documentation Documentation.info History History.info Fonts (dir) Lucifer (dir) 8 Lucifer.font AmigaWorld AmigaWorld.info Deutsch.info English.info It is not allowed to give the version for registered users to any other people. Only those parts of the source code may be spread that are marked as Public Domain. Lucifer font is Public Domain, i.e. you can spread it, modify it and use it in your own programs. 9. How to become a registered user ================================== If you like AmigaWorld, why don't you become a registered user? Registered users will receive the latest version of AmigaWorld, of course without any annoying limitations. They will also receive the source code of the program, that should be interesting to everyone who creates programs in Modula-2. Escpecially the following parts will be useful: EasyIntuition contains procedures to open screens, windows and to initialize menus. If your program crashes, all screens and windows are closed automatically. This is quite use- ful while developing software. EasyGadgets contains procedures to create and evaluate gadgets. As you see, it supports 3D-look. ColorRequest contains the color requester. Vanilla does not really belong to the source code yet. It converts rawkey events into ASCII code and it does also tell you if some non-ASCII key was hit, e.g. Help. You can also have a look, if any qualifiers (Shift, Amiga Keys, Numeric Pad, ...) were used. Vanilla is based on a program by Peter Graham Evans, that can be found on some AmigaLib- Disk. Examples Together with the source I provide some examples that show you how to use those modules that are listed above. Because I could not afford DM 400,- on an update (the update costed more than the whole thing, when I bought it!) I'm still using version 3.3 of m2Amiga. If you have a later version of the compiler you should recompile everything, because the result will be much shorter than the big thing that comes along with this distribution. Well, if you want to become a registered user, send US-$ 20 (or the equivalent in your own currency) to this address: Wolfgang Lug Altmühlstr. 20a 6200 Wiesbaden Germany Of course I'm keen on your money in the first place, but I'm looking forward to ANY reaction on AmigaWorld. So, if you have any ideas, how to improve AmigaWorld, or if you know how to create the 3D-look for windows without using tag-items: Write to me! If you find bugs in the program or in the data files, or if you just want to tell me about all my nasty mistakes in the English documentation: Contact me! And, most important: If you have translated "awo.data" and "awo.output" into a new language, please send your translations to me!! If you are the first one that provides a translation into this language, you will get your registration fee back! And if you just want to chat about "Yothu Yindi" or other interesting topics: Write to me! Credits ======= Last not least I wanna say "Thank you!" to some people: Alexander Linke who put me on Modula-2. Bernd Preusing for his module "IntuiPointer", which creates the busy pointer for the mouse. Kai Bolay for ImageConvert, that I used for converting the title and the little map into source code. Jean-Michel Forgeas for his great editor "Az". I wrote the documentation and all data files with it, and it is really the best editor for the Amiga that I know. E N J O Y ! and remember: IBM sucks