This document gives a brief overview of APE's functionality and commands.
In its current state of development APE allows to write and share web-based commentaries which are dynamically linked to primary source editions on a local computer system. Using dynamic linking distinguishes APE's hypertext system from conventional ones as commonly used on the internet today.
Dynamic linking can be compared with using canonical bibliographic references to printed books in a library. Let us consider what happens if a novice reader comes across a reference to, let's say, "Plato: Smp. 172a". If she wants to follow such a reference, the first thing to be done is to decrypt the tokens which form this expression. There are various ways to do so, like asking a librarian, looking into a bibliographic index etc. If she succeeds, she will find out that "Plato: Smp." is a reference to a book, or more precisely: a dialog, written by the Greek philosopher Plato and intitled "Symposion" in Greek, "Convivium" in Latin, "Gastmahl" in German, etc. Next, she will have to look into the library catalog to find out which editions are available and where they are located on the shelves. Guided by the shelf marks one is than enabled to consult a chosen edition and there to find the text passage associated with the number "172a", which is, by the way, the very beginning of the dialog.
Such a procedure includes at least two distinct kinds of references. The canonical reference "Plato: Smp. 172a" and a proprietary shelf mark. The canonical reference is relatively vague, since it does not determine the kind of edition to be used. It guides the reader to a text passage, but the reader is free to chose among several versions. On the other side, the proprietary shelf mark is very specific, since it must unequivocally indicate the place where an edition is to be found in the library.
If we compare this situation with the linking mechanism of todays World Wide Web, it is apparent that the World Wide Web is lacking the flexibility of the traditional reference systems used for printed books. What to do to gain a similar flexibility in a hypertext system almost presents itself: A hypertext link must not directly refer to the location of a target document, but instead must be of the same relatively vague nature as "Plato: Smp. 172a". When a computer follows such a vague link, it first consults a kind of library catalog to find an instance of a text passage by combining the preferences of the user with the characteristics of the editions available. Using such a strategy might appear to be only a small step apart from the method of static linking used with today's HTML standard on the World Wide Web, but in the outcome it makes linking far more flexible.
The technical details are, in short, as follows: While HTML links use so-called Uniform Resource Locators (URLs) pointing to a particular storage location where data is to be retrieved, APE imitates ordinary bibliographic references by means of so-called Uniform Resource Names (URNs). An URN is a references consisting of a character sequence with a unique global meaning. It is a name, not an address. In other words: It does not directly point to a data resource; instead an URN must be resolved into an URL in order to retrieve instances of its meaning.
From the fact that an URN is associated with a unique meaning does not follow that there is only one URL associated with it. It is analogous to "Plato: Smp. 172a", which uniquely identifies the beginning of Plato's "Symposion" though the "Symposion" is available in many different editions. Moreover, saying that the meaning of "Plato: Smp. 172a" is fixed does not imply that one is obliged to use it only for consulting a primary source edition. A person may combine it with other available data in any way that makes sense to her, for example she can search the index of other books whether they contain anything about "Plato: Smp. 172a" or she can compile the beginnings of Plato's other dialogs to carry out a comparison. Likewise, the use of URNs is not limited to retrieving directly associated documents. Its limits are only the limits of our imagination to build and clever navigate and query webs of associated URNs.
The information in this section applies only to APE, when it is running in Standard mode, but not in Demo mode. When APE is distributed in Demo mode it contains a preconfigured user profile and a catalog of documents which are automatically indexed the first time APE is started. Later the catalog cannot be altered. APE running in Demo mode is regonizable by it not having a menu section "Administration", which is described in this section. For security reasons switching the mode is not possible from inside APE. To switch the mode the value of the "on" property in the "Autorun" section of the "settings.ini" file must be set to "0" for Standard mode and to "1" for Demo mode.
The APE running in Standard mode allows to set up different user profiles. Each user profile has its own catalog and preferences. The preferences of the current active user profile can be modified via the "Edit Profile" dialog accessible by the "Administration/Edit Preferences ..." entry in the APE menu. This dialog allows to edit the name of (or an alias for) the person using this profile, the maximum number of items in the memory cache and the font for the structure and the comment display. It is recommented to use a font which covers as much as possible of Unicode, eg. "Lucida Sans Unicode". If nevertheless you do not get the letters displayed you expected try another Unicode font. It may also be the case that no appropriate font is installed on your computer. To determine the size of the cache requires perhaps some experience as well. A rule of thumb is that the larger the catalog and the more memory is available the larger the cache should be. If you frequently experience that APE is getting slow when navigating a structure file and the status bar is telling you that APE is analyzing a catalog file you should increase the cache's size.
To create, rename, remove or edit any profile as well as to switch the active profile the "Manage User Profiles" dialog must be used which can be opend via the "Administration/Profiles ..." entry in the APE menu.
In APE's framework a set of URNs replaces a traditional reference system, and two levels of catalogs are used to handle these URNs. A low level catalog consists of an XML document which contains information about a certain reference system. There are three types of such low level catalogs: (i) Info files declaring human readable labels for URNs, (ii) URN-to-URN mappings to transform one reference system to another equivalent one, and (iii) URN-to-URL mappings to identify the system location for a particular dereferenced source. A high level catalog is a collection of low level catalogs. It is currently implemented on the local computer system and must be configured by an APE user herself. A future version of APE will allow the access of remote high level catalogs via the internet, too.
This introduction does not explain the structure of the low level catalog files. Usually the low level catalog files should be packaged together with its corresponding resource files. So if you get some text documents to be used with APE the collection should also contain several low level catalog files to be installed inside APE as described in the next paragraph.
When setting up the standard version of APE the first thing to do is to install low level catalogs to be used in its high level catalog. This is to be done in the Catalog Administration Dialog which can be opened via the "Administration/Catalogs ..." entry in the APE menu. On the dialog form you can see three tabs for the three different kinds of low level catalogs. The Display Mapping Catalog index holds references to URN-to-URL mappings. The Resolve Mapping Catalog index holds references to URN-to-URN mappings. The Info Files Catalogs index holds references to info files. Below the catalog indices there is a display for status messages, and at the bottom of the dialog form you can see some buttons used to maintain the catalogs. -- To add a new low level catalog click the "Add file ..." button. A Open File Dialog appears where you can choose one or more files containing a low level catalog to be installed. To remove a low level catalog first select its corresponding entry in the catalog indices and then click the "Delete Entry" button. You can undo all modifications and reset the Catalog Administration Dialog to its initial state by clicking the "Undo" button. Finally, to confirm your modification click the "OK" button, or use the "Cancel" button to close the dialog discarding all modifications.
The APE desktop consists of three parts. The upper half of the left side contains the Primary Display mainly used to show a passage from a primary text. The lower half of the left side contains the Secondary Display used to show additional information such as notes, parallel versions and cross-references of the primary text, or additional documents like the help file you are currently reading. At the right side there is the Structure Display consisting of some rows of buttons and a tree view display. It is used to display and edit structure documents.
The usual way to access a primary text within APE is by using a corresponding structure file. After loading a structure file its contents is displayed in form of a tree view. A tree view entry is selected by clicking on it. Then the Primary Display is updated with the text passage associated with the selected tree view entry according to the available editions as listed in the Catalog. The Secondary Display gives access to the associated notes and to an "Apparatus" showing, if available, parallel versions of the associated text passage.
Structure files can be loaded either from a local storage medium or from a remote location via the internet. To open a new structure file locally you can either use the "Open document" button of the Structure Display or press [Ctrl]+'O'. An Open Document Dialog appears where you can choose the structure files to be opened. To open a remote structure file type its URL into the white edit field of the Structure Display and press [Return]. To cancel loading a remote structure file click on the "Stop loading" button.
When APE is running in Demo mode, it might automatically load one or more structure files at startup (depending on the preconfiguration of the Demo mode).
Use the "Show info" button to display some background information about the active structure file. To return to the structure tree view click on the "Show structure" button.
APE includes a structure editor to modify loaded structures or to create new ones from the scratch. To create a new empty structure click on the "new document" button. To save a structure file to its original location, thus overwriting the old one, click on the "Save document" or "Save all modified documents" button. To save a structure to a new location use the "Save document as" button. To close a document without saving click on the "Close document" or "Close all documents" button.
To edit a structure file APE must be in edit mode. To switch edit mode on or off use the "Edit document" button. When APE is switched into edit mode there appears a new row of edit buttons in the Structure Display. These buttons operate on the selected tree view entry. Use the arrow buttons to move the selected tree view entry around in the structure tree. Use the minus button to remove the selected entry and the plus button to insert a new entry.
Clicking the "Edit info" button opens an Info Edit Dialog where you can modify the global information about the active structure file. -- Under the "Title" tab you can enter the full title for the structure text, a label for the tabs above the Structure Display's tree view display, and the name of the authors of the structure file (do not confuse this with the author(s) of the primary text). You may provide alternative titles and labels for the same structure files both in the same or in different languages. -- Under the "Publication" tab you can specify the availability of the structure file. This is primarily used for license information. -- Under "Source Desc." you can specify the possibly non-digital source of the structure file. If the structure file itself is the original you should indicate this by a sentence like "No source: created in machine-readable form." -- If the structure file is the outline of a particular text which itself is known by an URN this URN can be specified under "Notes". -- Under "Rendering" the so-called "rendering priority" can be specified. The rendering priority is an ordered list of URNs determining which type of edition is used in the Primary Display if more than one type of edition is available. By specifying more than one type of edition you can implement a kind of fallback strategy: APE first looks for editions corresponding to the first edition type; if none is available it looks for the second, and so on. If you do not know the edition types available for the texts you are linking to, then leave the list empty. In this case APE will display all available versions in the Primary Display.
The "Edit note" button is used to modify the properties entry itself. When clicking on it an Item Editor Dialog appears. At the top of the dialog there is a white edit field called "Caption" where you can type in the text that appears in the structure document as the label of the entry. Below it there are two tabs visible. The first is the "Note" tab. Here you can enter text to be displayed under the notes tab in the Secondary Display. The second is the "Resource Map" tab. Here you must add the URNs associated with the selected structure tree entry.
For typing text passages both, the Info Edit Dialog and the Item Editor Dialog, use a special kind of sub-editor. This sub-editor is paragraph orientated. You can add new paragraphs by clicking on the plus button and remove a selected paragraph by clicking on the minus button. To modify the sequence of paragraphs use the up and down arrow buttons. On most sub-editors you can specify the main language of each paragraph. Best practice is to use the language codes from ISO 639. To enter the text of a paragraph itself you can either type it directly into the table of paragraphs or use, if available, the memo field below this table.