Read Me

Table of Contents:
    1. Aims
    2. Workflow
        2.1 Text Input
        2.2 Syntactical Analysis
        2.3 Semantical Analysis
    3. Preferences
        3.1 View
        3.2 Analysis
        3.3 Print (Export)
    4. How We Help You
    5. How You Can Help Us
    6. Contact
    7. F.A.Q.

HermeneutiX offers a graphical user interface for developing syntactical and semantical analyses of complex
(not neccessarily foreign language) texts. You need a Java Runtime Environment (JRE) to run it.
For a list of the latest/upcoming changes and features click here. It is in a separate article,
so you can subscribe for this list only instead of the whole wiki page, in case you are interested.


1. Aims

Simplification/Time Saving in developing the analyses (compared to the extensive arranging in Office- or drawing programs)
Free of charge availability (HermeneutiX is Free Software and thereby OpenSource; specifically under the FreeBSD License)
Exchangeability of the analyses between HermeneutiX users (due to the lightweight XML file format)
Uniformity of notation enabling the user to focus on contents at hand instead of the cumbersome layouting of a multitude of elements
Usability of results due to the integrated SVG export (enabling arbitrary image size without any loss of quality)
Teaching and Learning Aid (cooperative network mode and adaptability of font size for all texts in the analysis view in favor of projector usage)


2. Workflow

HermeneutiX by default starts up with a new project which comes in the text input view.
Basically a couple of projects can be open simultaneously. You can switch between them via the tab bar or the Window menu item.
Single projects can be saved to a hmx file and respectively loaded from one.

There is currently no immediate print option available but rather the possibility to export one of the analyses to an image file (recommended: SVG).
The image can be viewed and printed by a variety of third party programs (e.g. a modern Web-Browser).

For a more detailed overview of the possible actions take a look at the HmX-Features.pdf (downloadable at SourceForge as well)


2.1 Text Input

A new HermeneutiX project always starts with the arrangement of the origin text to analyze.
Furthermore its language needs to be defined. Because of the analyse´s integrity the latter cannot be changed after beginning the analysis.
The selected language determines if the text is aligned from left-to-right or from right-to-left as well as the selectable clause item functions
in the syntactical analysis. Thus it is not mandatory to select the actual language.
Just choose a language with the same alignment and at least the same syntactical variety.

The font type and size can be adjusted at any time later on.
But by pushing the associated button you start the analysis itself and won´t be able to change the selected language again.

In order to avoid the more time-consuming alternative in the syntactical analysis it is recommended to structurize the origin text
while in the text input view. Inserting line separators allows you to mark single propositions while tabstops indicate the contained clause items.
You can as well just paste a preformatted text and get going.
But beware that you cannot save nor export before you get into the analysis view.


2.2 Syntactical Analysis

By finishing the text input you begin the analysis and are asked for some project meta information which are all optional.
From this moment on you can save and export your project at any time.
Initially you reach the syntactical analysis view.

The first task at hand is to structure your text according to the contained clause items (not necessarily every single word) and propositions.
In the analysis view you can accomplish this by means of the clause item context menus (reachable by secondary/right mouse button).
Ideally you have already structured you origin text while in the text input view using line separators and tabstops.

The aim of the syntactical analysis is a literal interpretation of the given text. Therefore you determine the functions of the single clause items
and check for their counterpart in your translation. Additionally you can assign and verify the clause item functions of the whole propositions
by subordinating them to one another.

The button on the left allows you to switch to the semantical analysis at any time, but it is recommended to finish at least the structuring
of the propositions first, because later changes in the proposition assignment might drop some branches in your semantical analysis.


2.3 Semantical Analysis

The aim of the semantical analysis is a translation that communicates the pristine intended statement of the original author.

It is based on the proposition structure defined in the syntactical analysis. The semantical relations between single or multiple propositions
can be represented in a tree structure with their respective roles at each node. Similar to the approach in the syntactical analysis you can
subsequently check your translations if they preserve the uncovered semantical relations.

In principle it is a refining of the translation produced in the syntactical analysis in which you can always switch back
via the button on the right. Beware that changes in the proposition structure might affect their assigned semantical relations.


3. Preferences

The appearance and behavior of HermeneutiX can be customized to a certain extent via the main menu item File > Preferences.
If you are using Mac OS X you will find the preferences option in the usual application menu.


3.1 View

Appearance (Swing-"Look And Feel"):
	determines how the program windows and components are rendered
Arrow Color:
	sets the color of the arrows in the analysis view indicating parts of a single proposition that are separated by at least one other proposition
Relation Color:
	sets the color of the semantical relation tree lines in the analysis view
Highlight color of commented elements:
	sets the color of the propositions/clause items/relations that has a comment attached
Indentation Width:
	determines how far subordinated propositions in the syntactical analysis view are indented
Show settings on start of new analysis:
	hides or shows by default the origin text properties when beginning a new project in the text input view
Font of all non-origin-language texts:
	sets the font type and size of the following texts in the analysis view: clause item functions, propositions functions, relation roles, translations and comments


3.2 Analysis

Default Author:
	preset of the corresponding meta data field when starting the analysis of a new project
Default Origin Language:
	default origin language selected when starting a new project in the text input view
Default Font:
	font type and size to set for the origin text of each language when selected in the text input view of a new project
Maximum number of undo operations:
	number of reversible model change actions (Beware that each undoable action consumes memory and should be treated carefully.)


3.3 Print (Export)

Element Colors:
	colors of arrows, semantical relation lines and the border and background of propositions in the exported images
Font Colors:
	possibly diverse colors of texts in the exported images
Font of all non-origin-language texts:
	font type and size of all texts in the exported images that are not part of the originally analyzed text
	(the font type and size of the origin text in the exported images is the same as in the analysis view)


4. How We Help You

If you have any problem or question not covered in the FAQ section please write us a mail (see contact section).
That applies for suggestions and change requests as well. We appreciate all feedback.


5. How You Can Help Us

HermeneutiX is intended to address foreign language texts and thereby offers only proper clause item functions in the syntactical analysis
regarding the specified origin language. The currently available languages are Greek and Hebrew which almost limits its use to bible excerpts
(for which it was originally designed for). Despite that initial idea there is no reason against using it in other fields of philology and
linguistics in general. So if you are able to compose a list of all proper clause item functions of a single language
(like english, german, latin, french, spanish, chinese, ...) we would really appreciate it to be able to include it in the next HermeneutiX
release to the benefit of all other users.
The other language related request refers to the translation of the graphical user interface itself.
Since German is our mother tongue we were only bold enough to add an English version of all this.
Please help us to improve HermeneutiX by adding more language options.

In both cases are explicitly no programming skills required! If you are interested please contact us and we will be happy to include your
contribution for the benefit of all other users in the next HermeneutiX release as soon as possible.


6. Contact

The easiest way to reach us/me is by email:
	- Carsten Englert (CarstenEnglert@users.sourceforge.net)


7. F.A.Q.

Question:
	I just extracted the HermeneutiX.app from its .dmg, but when I open it I get the error message
	"HermeneutiX.app is damaged and can't be opened".
Solution:
	Wait for a future release of HermeneutiX or use the workaround:
	deactivate your Gatekeeper, start HermeneutiX.app and reactivate Gatekeeper (it should remember your decision to start HermeneutiX).
Reason:
	The Gatekeeper is a anti-malware feature introduced in the latest Mac OS X versions.
	It only allows the usage of Apps signed with a Apple Developer ID.

Question:
	Why does the export of my HmX project to JPEG or PNG fail?
Solution:
	Try a smaller target size or the recommended SVG export. If you need a big rasterized graphic (such as JPEG or PNG) try exporting your project
	to SVG and convert it with the aid of a more eligible program like an image viewer, image manipulation program (such as GIMP) or your web browser.
Reason:
	For generating a rasterized image each pixel needs to be calculated separately before potential compressing methods reduce the necessary
	amount of memory to hold it. If you choose a target size that causes too many pixels to be calculated, the memory assigned to your
	Java Runtime Environment (JRE/JVM) won´t suffice and causing it to cancel the export job.

Question:
	Why are my user settings/preferences from the last time I used HermeneutiX reset to their previous values?
Solution:
	Make sure HermeneutiX is in a directory where it has the permission to write files.
Reason:
	HermeneutiX stores the user preferences in a file (in the directory where it is located) when the application is closed.
	If HermeneutiX does not get the required permission from your operating system it simply falls back on the default values on its next start.

Question:
	I relocated HermeneutiX to another directory. Why are all my settings/preferences gone?
Solution:
	Copy the file ".options.properties" from the previous directory to the new one.
Reason:
	HermeneutiX stores the user preferences in this file when the application is closed. Because of the prefixed dot in the file name it is invisible
	on some operating systems or you just missed to relocate it along with the other files.
	You can also avoid this problem by copying/relocating the whole directory containing HermeneutiX.