Library Locations and References

Locations are used to manage groups of libraries and documents. The purpose of locations is to make documents portable from one machine to another. To do that, locations can be online as well as on your local machine. If a document references online libraries, the required libraries will be downloaded automatically when the document is opened.

Documents reference libraries and these references specify where the library file is located. The references contain both the location of a file and the name of the file to be referenced. This is enough information so that a reference can be resolved to either a location on your computer or to an online location. Locations are also used to version and publish the libraries and documents that they contain.

References to libraries are created in a document by right-clicking the References node in the Document Explorer, then selecting Edit references.... See Libraries and References and Adding and Removing References for more details.

Locations can also be managed through the Locations List dialog, select Locations list... under Edit in the main menu. There are three types of locations, Local, Public, and Development. Local locations refer to a specific directory on the local machine. Public locations can refer to any public URL. Development locations are used when you create libraries and/or documents that will be placed online for use by other users.

Libraries in Public locations are not editable. Documents in Public locations can be edited but the changed version of the document has to be saved as a local file.

In the Locations List dialog, all of the libraries and documents available in each location are listed in a tree under the location. This dialog allows you to add, edit, and remove locations from the list. It also allows you to create new libraries and delete libraries from any of the local locations. The Locations List dialog also allows you to publish some or all of the documents and libraries in a location. See Creating public libraries and documents for more details.

In addition, the Sym application will automatically download libraries that are needed by documents that have references to online locations. For example, if a docment references the Math.eql library at the http://symbolicware.com/Locations/Published/Libraries location, that location will be created in the Location List (if it doesn't already exist) and the Math.eql library will be downloaded (if it hasn't already been downloaded) when the document is opened.

When Sym is installed, three locations are created by default. The first two are Public locations that point to the SymbolicWare web site, one contains libraries, the other contains sample documents. The third location is a Local location that points at the Libraries directory under the Documents directory specified in the Options dialog.

Adding a Reference to a document

The references to libraries under the References node in the Document Explorer include the name of the library and it's location. See Adding and Removing References for more details.

Adding a location

Locations can be either public or local. Either can be added by selecting the Add Location button on the right of the Location List dialog. The Add Location dialog will appear.

To create a new public location, enter the URL of the location in the Location: text box. When the new location is created, the SymList.xml file at the location is downloaded to provide the list of libraries, documents and the versions of these files that are available at this location.

To create a new local location, enter the directory of the location. The Select button allows you to pick a folder for the new location or you can just type the location into the text box. If this location existed already and there is a Published folder containing previously published versions of the libraries in this location, the Sym application will look at the SymList.xml file and get the name and list of versions from this file. If the selected directory does not contain a Published directory, you will be prompted for a location name and (optionally) a publication URL.

You can't add a location that points to the same URL as an existing location.

Using locations

Typically, there are four kinds of location that are used. First, you can use a location to reference libraries that are available online (a Public location). See Public locations for details.

Second, you can create a location that points to a folder on your machine that will contain libraries that you create. See Local locations for details.

Third, you can create a location that contains libraries that you create where the libraries are intended to eventually be published online. See Creating public libraries and documents for details.

Fourth, you can create a location that is just a redirect. You might use this if you need to open a document that was created on another machine and references local libraries on the machine where the document was created.