=============================
.* - *. Pretty Garage .* - *.
=============================
#  By Lucas Pedrosa  (Cas)  #
=============================

[-1-] About Pretty Garage

	Pretty Garage is a GUI-based garage program for Stunts that can help you organise your cars in different directories (garages) and groups and keep them syncronised with online repositories. It's designed to be user-friendly, simple and powerful.


[-2-] Setting up for the first time

    Starting from version 1.2, Pretty Garage will make a self-setup best effort on first run. If the program is run from a directory other than its own, it'll try to locate the data files where the binary is. It will also try to read the configuration from there or from your somewhere inside your home directory or the local path in order to be able to actually write to and update that configuration.
    If no configuration file is found, it will try to produce the best default parameters, including an attempt to locate Stunts in your hard drive and even create a default garage. This may fail if Stunts is not installed or the directory can't be written to, in which case, you'll be told to manually edit the configuration file.
    In case the default parameters don't work well for you, open pgarage.cfg (the configuration file) and set the following:

- At the "stunts=" line, enter the directory where you have installed Stunts
- You'll find some "garage=" examples. You're going to need to set up at least one garage directory. Uncomment one of these lines or add a new one and specify an existing directory that you want to be able to swap cars with. Make sure your user has the permission to access and modify both Stunts and the garage directory.
- Optionally, you can set up a junkyard, that is, an extra garage that can be called "junk" or "junkyard" where cars go by default when you delete them. This isn't a requirement.
- You'll see that the screen width and height are commented out. This will default to 800x600 for your program window. Feel free to change it to some comfortable size for you. If you're compiling the program for DOS, though, remember you need to specify an existing DOS resolution.
- If you have an unzip program other than "unzip", you can change the line that says "unzip=" and configure it. This will allow Pretty Garage to download and install cars that are zipped.
- If you have stunpack, you can point it with "stunpack=". This will only be used if you try to generate images for packed cars (typically, the original cars). You probably won't need this because the cachéd images are already supplied and new cars are normally unpacked.

	You're ready to go!  Save the file and you can run Pretty Garage. If your system can't run any of the provided binaries, you can follow the instructions in source/compile.txt to compile from source for your system.


[-3-] Basic usage

	When you first start the program, it'll pull up the car list from your Stunts directory on the left hand side and your main (first) garage on the right hand side. You can change any of these two list by clicking on any of the options on the far right. If you click with the left mouse button, it'll go to the left list and if you click with the right mouse button, it'll go to the right list.
	You can scroll the lists with the mouse wheel. Also, you can use the up and down arrow keys for the same purpose and Tab to switch between the two lists.
	Click on any car with right mouse button and it'll be selected. To select more than one car, do this while holding Shift or Ctrl. This will produce the expected behaviour, with Shift aiding in selecting a list of consecutive cars and Ctrl in selecting and deselecting individual cars. If you select a car on one list, all cars in the other list will be de-selected.
	To move cars between Stunts and a garage or between two garages, hold down the left mouse button on a list that contains selected cars and drag them to the other list. You will be warned if there'd be any problem with this action, such as when you're moving more cars into Stunts than it can handle or if some cars would be overwritten. You can force the action by holding Shift while dragging.


[-4-] Groups

	You'll notice that, by default, you also have a group (in orange). In this case, the group of original cars. Groups look like garages when you select them. The bring up a list. But they are not directories. Instead, the cars in a group are just there by reference and you can see where each car actually is located as it's specified in the list. When you drag cars from a group to a garage (or Stunts), Pretty Garage will move every car from the group that can be moved to make sure all are at the destination. The cars will still belong to the group. If you drag from a garage (or Stunts) to a group, the cars will be added to the group, but not removed from source. Draggin from a group to another just copies the cars. The files are never moved when dragging to a group.
	It's possible to create a new group by selecting cars from an existing list and dragging them to the other panel while holding down Ctrl. This will cause a new group to be created containing the selected cars and the list will be brought to the destination panel. Nothing will happen to the list previously on that panel.


[-5-] Naming and configuring lists

	Right click at the top of a panel, on top of a list, to change the list name and/or directory/address depending of its nature. You can change the name of garages, groups and repositories, the directory for Stunts and garages and the address for repositories.


[-6-] Shortcut keys

Up/Down		- Scroll a panel list
Tab			- Change current panel
Del			- Delete selected car(s)
Enter       - Type command
Ctrl+A		- Select/de-select all cars in a list
Ctrl+D		- Delete a group, garage or repository. Careful!
Ctrl+S		- Change sorting method (by car name or car ID)
Esc			- Save configuration and exit
Ctrl+Q		- Exit without saving configuration
Ctrl+F		- Attempt to re-generate car image
			  You can then press a number to select the paint job


[-7-] Repositories and online groups

	You can use the "repo" configuration in pgarage.cfg to set up a repository index or online group. A repo line has the following structure:

repo=Repo-name|repo-web-address

	Repos appear in light blue among your selectable lists and are there to retrieve car lists from the internet. The address you provide must link to a car repository index, which is a file that describes a list of cars and optionally, how they can be obtained. There are two formats these files can have: proper car repository indices and simple car lists.
	You can create your own CRI file and put it on your site, then provide the address to it so people can sync to it and download cars. The car files don't need to be hosted on your site, although that is a possibility. The index is just that: an index. The format for these files goes like this:

	[car-ID]
	name=car-name
	zip=web-address-to-zip-file-containing-car-files
	files[]=file-that-will-be-found-in-the-zip
	files[]=another-file-that-will-be-found-in-the-zip
	.
	.
	.
	
	[car-ID]
	.
	.
	.

	The files[] entries tell clients which files within the zip actually represent the car. Files that are not listed as files[] could potentially be something else and not to be copied. Remember to respect file name capitalisation, as GNU/Linux is case sensitive.
	The other format is simply a list of car IDs separated by commas in just one line, for example:

	pmin,jagu,cdor,daud

	Of course, it's a lot simpler to only include a list like this, that is, an online group, but the result is very different. A proper car repository index will behave as a garage and you will be able to download cars from it, obtaining them from where it's specified in the CRI file, whereas online groups only pass the reference and Pretty Garage will only be able to identify the cars if they are currently installed in your computer, be it at Stunts or another garage. They will behave as groups and when you move cars from them, they'll be taken from wherever they are found in your computer, not from the internet.
	Updating CRIs and downloading from the internet requires "curl" to be installed in your system. Pretty Garage will call "curl" to retrieve the list or any car you download.
	In pgarage.cfg, you can configure when CRIs are updated. There's an option that reads "lastupdate=", which keeps track of the last time when they were updated, and another called "autoupdate=" that will specify the desired behaviour as follows:

# autoupdate=always
Update the list when the program starts and every time you bring the list into one of the panels. This will ensure your online lists are always up to date and immediately pick up any changes that happen online, but will make usage somewhat slower.

# autoupdate=yes (default)
Update the list when the program starts as long as lastupdate is in the past. Do not update during program usage.

# autoupdate=no
Do not update lists. Only download them if requested and they do not exist, that is, for the first time.

# autoupdate=never
Never update or download any list. Even if requested and not present, do not attempt to use the internet. The list will simply load empty.


[- 8 -] Junkyard

	The junkyard is just a garage, a directory. If you specify a garage with a name beginning with "junk" (case insensitive), the first such garage will be taken for your official junkyard.
	When you don't have a junkyard, if you attempt to remove cars, you will be warned and if you confirm, the car will be permanently deleted. On the other hand, if you do have a junkyard, you will not get any prompt and the car will be immediately moved to the junkyard instead of deleted. You can later recover the car by dragging it back from the junkyard.
	If you have a junkyard and you try to delete a car from it, you will get the default behaviour of a warning and upon confirmation, the car is deleted permanently.


[- 9 -] Commands

    By pressing Enter, you can issue commands to the garage tool. As of version 1.2, only a few commands are available for the purpose of filtering lists and add car configuration:

* setauthor <author name>
Use this command while one or more cars are selected to change the author name of the selected cars. This will be save in the corresponding car*.ccf file. Setting the author name is useful because later you can filter cars based on this field.

* newgarage [name [directory]]
With this, you can create a new garage. A default name will be given if not specified. The program will choose a default directory also, if not given. This will not create a new directory, only point to an existing one.

* select [name|id|author] <filter>
Entering the "select" command with a filter, you can make a comprehensive selection within a list. For example, type "select Porsche" to have all Porsches in your current list be selected, or "select *a" to highlight all cars whose name ends in "a". You can also combine filters, like "select Porsche*,Lambo*,GTO". By default, the filter is applied to the car name, but if you specify "id" or "author", the target can be changed, like "select id pmin,jagu,z*", to select the Porsche March Indy, the Jaguar and all cars whose ID starts in a Z.

* <and|or> [name|id|author] <filter>
Similarly, you can apply an "and" or "or" operator with a filter, which will combine the current selection with the new filter.

* not
This simple command will invert the current selection.

