<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet href="http://www.germane-software.com/~ser/Software/documentation.xsl" type="text/xsl"?>
<!DOCTYPE documentation>
<documentation>
	<head>
		<title>Esperanto Parser</title>
		<base>EOParser</base>
		<version>2.0</version>
		<date>2001-254</date>
		<home>http://www.germane-software.com/software/EOParser</home>
		<archive type="windows">eoparser.zip</archive>
		<archive type="unix">eoparser.tgz</archive>
		<osd>software.osd</osd>
		<language>ruby</language>
		<author email="ser@germane-software.com" href="http://www.germane-software.com/~ser">Sean Russell</author>
	</head>

	<overview>
	<purpose lang="en">
		<p>
Esperanto is an artificial language created in the late 1800's,
designed to be a language for diplomats.  Esperanto is characterized by
the relative ease with which it is learned due to a simple ruleset, with no
exceptions to the rules.  The EOParser is a framework for processing
Esperanto.
		</p>
		<p>
EOParser is the first step in the creation of an AI.  Esperanto, being highly
regular, is an excellent candidate for a computer/human interface language.
EOParser provides the human->computer link.  The neural network and
computer->human link will be part of a separate package.  In the meantime,
EOParser can also function as an Esperanto -> English translator.
		</p>
	</purpose>
	
	<!--
	<purpose lang="eo">
	<p>
Esperanto estas arta lingvo kreigxis en maljuna 1800's kaj intencigxis esti
lingvo por diplomatoj.  Esperanto karakterigxas per relativa facila lernigxi,
kial ke simplaj reguloj sen esceptoj.  EOParser estas kadro por procezi
Esperanton.
	</p>
	<p>
EOParser estas unua pasxo en kreigo de AI (Arta Inteligento).  Esperanto,
kiu estas tre regula lingvo, estas mosxta kandidato por komputila/homa
interfaca lingvo.  EOParser donas homan -> komputilan cxeneron.  
	</p>
	</purpose>
	-->

	<features lang="en">
		<p>
EOParser has an entirely text-based interface, or can function as a library
for other applications.  The interface accepts Esperanto sentances and
produces a morphological breakdown.
		</p>
	</features>
	</overview>

	<operation lang="en">
	<subsection title="Installation">
		<p>First, install <link href="http://www.ruby-lang.org">Ruby</link>.  Ruby is like perl and python, only better, and it is required to run this software.</p>
<p>Unzip the archive into any directory; it will create a subdirectory
named EOParser.  That's it!</p>
	</subsection>
	<subsection title="Usage">
		<p>The interactive interpreter is called EO.rb.  Run this from the EOParser directory.  <code>ruby EO.rb</code>
The Esperanto dictionary will be loaded, during which time a series of "."
will be displayed.  Then the prompt ("###") is displayed.  Enter any Esperanto
text, and the results will be displayed.  Enter "quit" by itself on a line
to exit the parser loop.</p>
	<p>
	The output of the parser is more complicated than plain english, since 
	EO.rb is not a true transaltor, but is rather an example program using the 
	EO Parser library.  Immediately after pressing "Enter", you will see some
	progress dots.  There will be one dot for each word, and they will appear as
	each word is scanned.  Immediately after this follows the transaltion.  
	First, unless the word is interpreted as a name, the translations will be 
	lower case.  Following each word is a parenthetical description of the 
	word. </p>
	<example>### mi
.
I (n pronoun 4)</example>
	<p>This means that "mi" is a noun, and a pronoun, and that it has a match value 
	of 4.  You can ignore the match value for now.</p>
	<example>### mia
.
I (adj pronoun 4)</example>
	<p>"mia" is a pronoun root, but is acting as an adjective; this would translate 
	into english as "my".
	</p>
	<p>In some cases, the translation is ambiguous.</p>
		<example>### amuzadas
.
[ love use continued (v present 2) || funny continued (v present 2)]</example>
		<p>In this case, "amuzadas" can be translated as "continuing to use love" 
		or as "continuing to amuse".  The appropriate translation choice is an
		ability this program does not possess.
	</p>
	</subsection>
	<subsection title="Using EOParser as a library">
		<p>
			There are numerous levels at which the EOParser can be used, and which
			use will determine which file to require.  The simplest for single
			words is to require Parser.rb, and use the parser directly:</p>
			<example>require "Parser"
results = EO::Parser.parse( "eklernis" )
			</example>
			<p>The parser will return all possible matches as an array, sorted by the
			match value.
		</p>
	</subsection>
	</operation>

	<status>
	<bugs lang="en">
	<!-- item status="fixed"></item -->
	<item status="fixed">Punctuation is processed, isn't reported in the results</item>
	<item>Unrecognized words are assumed to be names; this isn't a bug, but it
	can be annoying and will probably never get fixed unless the parser gets
	really intelligent about parsing and can recognize and correct typos.</item>
<item status="fixed">Names and other unrecognized words are poorly handled.  This is another
	side effect of the lack of parser intelligence, but this item will be fixed.
	This isn't really a bug, but a future feature, so see the To Do list for 
	more clarification.</item>
	</bugs>

	<todo lang="en">
		<item status="fixed">
	Specifically, some names get parsed as Esperanto words, because many names
	contain Esperanto roots.  The parser just breaks the words apart; it doesn't
	(at the moment) validate the resulting words.  Therefore, you'll find 
	sometimes humorous translations such as "Ivy" -> "capability y", "lill" ->
	"he ll", and "Susan" -> "Healthy person".  The first fix will be the simple
	case of the parser, when it realizes the word doesn't have a valid Esperanto
	suffix, will flag the word as either a name or a misspelling.  Some words
	will be recognized as names more easily and accurately than others; "Ivy"
	is "capability" plus an unmatched "Y" and therefore probably a name. "Susan"
	will be more difficult, since "susan" could reasonably be "susano" with a
	typo, a legitimate word.
		</item>
		<!--
		<item><note></note></item>
		<item status="complete"></item>
		-->
	</todo>
	</status>
</documentation>
