content.txt

Emdros is a text database middleware-layer aimed at storage and retrieval of "text plus information

eqtc).</P>

<P>If using SQLite, you may wish to specify a path.  Do so in
quotes:</P>

<PRE class="code">
{PREHASH} database
database = "C:{PREBACKSLASH}Program Files{PREBACKSLASH}Emdros{PREBACKSLASH}EmdrosSQLite-1.2.0.pre173{PREBACKSLASH}db{PREBACKSLASH}mydb"
</PRE><!-- widthincm : 12 -->

<h3>Rasterising unit</h3>

<PRE class="code">
{PREHASH} rasterising unit
raster{PREUNDERSCORE}unit          = clause
</PRE><!-- widthincm : 12 -->

<P>The Emdros Query Tool operates with a notion of "rasterising unit".
That is the unit to be displayed on one line.  For example, if your
query returns a bunch of words, then, in the example above, all
clauses that contains at least one of the words will be fetched and
displayed.</P>

<P>There can only be one rasterising unit.</P>

<h3>Raster context</h3>

<PRE class="code">
{PREHASH} raster context
raster{PREUNDERSCORE}context{PREUNDERSCORE}before          = 10
raster{PREUNDERSCORE}context{PREUNDERSCORE}after           = 10
</PRE><!-- widthincm : 12 -->

The &quot;raster_unit&quot; can be replaced with &quot;so many monads
of context&quot; (before and after a hit).  If a raster_unit is
specified, it will take priority.  If a raster unit is not specified,
then both of the raster_context_before / raster_context_after values
must be present.


<h3>Data units</h3>

<PRE class="code">
{PREHASH} data units
data{PREUNDERSCORE}unit            = clause
data{PREUNDERSCORE}unit            = phrase
data{PREUNDERSCORE}unit            = word
data{PREUNDERSCORE}feature         = word.surface
data{PREUNDERSCORE}feature         = word.psp
data{PREUNDERSCORE}feature         = phrase.phrase{PREUNDERSCORE}type
data{PREUNDERSCORE}feature         = phrase.function        {PREHASH} You can have more than one
data{PREUNDERSCORE}unit{PREUNDERSCORE}name            = clause."Cl"
data{PREUNDERSCORE}left{PREUNDERSCORE}boundary   = phrase.OPEN{PREUNDERSCORE}BRACKET    {PREHASH} Specifies left boundary marker
data{PREUNDERSCORE}right{PREUNDERSCORE}boundary  = phrase.CLOSE{PREUNDERSCORE}BRACKET   {PREHASH} Specifies right boundary marker
</PRE><!-- widthincm : 14 -->

<P>The data units are the units to be displayed in each rasterising
line.  They can be anything, and need not be words.</P>

<P>You must specify which feature(s) to display for each data unit.
The feature-names must be prefixed with the name of the data unit plus
a dot, as in the example above.</P>

<P>The capitalisation must be exactly the same as the value for the
"data_unit" key.  For example, if you said "data_unit = phrase", then
you must also say "data_feature = phrase.phrase_type", not
"Phrase.phrase_type".</P>

<P>There can be more than one data unit.  If so, they should be
specified in the order from largest to smallest (e.g., clause, phrase,
word).  This will give the "output" output style (see below) a hint as
to how to print things in the right order.</P>

<P>You can optionally specify "boundary markers" that will be printed
at the left and right boundaries of a unit respectively.  The strings
to be printed can be taken from the following table:</P>

<table border="1">  <!-- columns : 2 -->
<tr>
  <th>This string...</th>
  <th>Is replaced by...<br>(without the quotes)</th>
</tr>
<tr>
  <td>SPACE</td>
  <td>"&nbsp;"</td>
</tr>
<tr>
  <td>COMMA</td>
  <td>","</td>
</tr>
<tr>
  <td>COMMA_SPACE</td>
  <td>",&nbsp;"</td>
</tr>
<tr>
  <td>COLON</td>
  <td>":"</td>
</tr>
<tr>
  <td>COLON_SPACE</td>
  <td>":&nbsp;"</td>
</tr>
<tr>
  <td>OPEN_BRACE</td>
  <td>"{OPENBRACE}"</td>
</tr>
<tr>
  <td>CLOSE_BRACE</td>
  <td>"{CLOSEBRACE}"</td>
</tr>
<tr>
  <td>OPEN_BRACKET</td>
  <td>"["</td>
</tr>
<tr>
  <td>CLOSE_BRACKET</td>
  <td>"]"</td>
</tr>
<tr>
  <td>OPEN_PAREN</td>
  <td>"("</td>
</tr>
<tr>
  <td>CLOSE_PAREN</td>
  <td>")"</td>
</tr>
<tr>
  <td>NEWLINE</td>
  <td>newline</td>
</tr>
<tr>
  <td>NIL</td>
  <td>""</td>
</tr>
</table>

<P>The "data_unit_name" key gives, for a given object type, a string
which will appear above all the other data_features (if any).  In the
above example, the clause unit is given a "Cl" label.</P>

<P>Finally, in the graphical version of the Emdros Query Tool, it is
possible to have an interlinear display.  The order of the lines in
the interlinear display is the same as the data_feature keys. The
number of lines is equal to the number of features for the data unit
for which the most data_feature keys are given, plus the number of
data_unit_name keys for that unit.</P>


<h3>TECkit mappings</h3>

<PRE class="code">
{PREHASH}surface
data{PREUNDERSCORE}feature{PREUNDERSCORE}teckit{PREUNDERSCORE}mapping  = word.surface."e:{PREBACKSLASH}TECkit{PREBACKSLASH}mymap.map"
data{PREUNDERSCORE}feature{PREUNDERSCORE}teckit{PREUNDERSCORE}in{PREUNDERSCORE}encoding  = word.surface.bytes
data{PREUNDERSCORE}feature{PREUNDERSCORE}teckit{PREUNDERSCORE}out{PREUNDERSCORE}encoding = word.surface.unicode

{PREHASH} lemma
data{PREUNDERSCORE}feature{PREUNDERSCORE}teckit{PREUNDERSCORE}mapping  = word.lemma."e:{PREBACKSLASH}TECkit{PREBACKSLASH}mymap.map"
data{PREUNDERSCORE}feature{PREUNDERSCORE}teckit{PREUNDERSCORE}in{PREUNDERSCORE}encoding  = word.lemma.bytes
data{PREUNDERSCORE}feature{PREUNDERSCORE}teckit{PREUNDERSCORE}out{PREUNDERSCORE}encoding = word.lemma.unicode
</PRE><!-- widthincm : 14 -->

<P><strong>TECkit</strong> is a tool made by SIL International.  It
converts between encodings, in particular to and from Unicode.  The
Emdros Query Tool incorporates TECkit, and you can apply it to any
textual feature of any object type.</P>

<P>TECkit works with a so-called "map file" -- a text file which you
or someone else writes.  More information about writing TECkit
mappings can be found on SIL's website:</P>

<center><P><strong>http://scripts.sil.org/TECkit/</strong></P></center>

<P>The Emdros Query Tool needs three pieces of information in
order for TECkit to work on a particular feature:</P>

<OL> 

  <LI>The name of the file which holds the maping.  This is given
      with the key "data_feature_teckit_mapping".

  <LI>The input encoding (encoding of the feature-string): This is
      given with the key "data_feature_teckit_in_encoding".  The value
      can be either "bytes" or "unicode" (without the quotes).
      "bytes" means that TECkit does not convert to UTF-8.  "unicode"
      means it is converted to UTF-8 for display.  You should use
      whatever is used in the map file for input encoding here.

  <LI>The output encoding (encoding to transform into): This is given
      with the key "data_feature_teckit_out_encoding".  The same
      meanings and restrictions apply as for the input encoding.

</OL>

<P>TECkit can not only convert between encodings, but also remove
stuff from a string.  This can come in handy when you have characters
in your feature-strings which you do not wish to display.  Again, see
the TECkit site on SIL's website for information on how to write a
TECkit mapping.</P>

<P>You should give first the object type, then a dot, then the
feature-name, then a dot, then the full path to the map file.  You
probably need to enclose the path in "double quotes".</P>

<P>You can only have one TECkit per feature.</P>


<h3>Reference unit</h3>

<PRE class="code">
{PREHASH} reference units
reference{PREUNDERSCORE}unit      = verse
reference{PREUNDERSCORE}feature   = verse.book
reference{PREUNDERSCORE}feature   = verse.chapter
reference{PREUNDERSCORE}feature   = verse.verse

reference{PREUNDERSCORE}sep = SPACE {PREHASH} between book and chapter
reference{PREUNDERSCORE}sep = COMMA {PREHASH} between chapter and verse
</PRE><!-- widthincm : 14 -->

<P>If you have a unit in your database which somehow identifies the
position in the document, or an ID, you can display these units at the
left of each line.  The canonical example is the Biblical system of
book-chapter-verse, but in many corpora, there will be a unit
identifying, e.g., which newspaper article something came from.</P>

<P>In the above example, verse is the reference unit, and three
features are fetched, namely book, chapter, verse.  The order in which
they are specified in the configuration file is the order in which
they will be emitted.

<P>If there is more than one reference unit feature, you must specify
the separators to separate them.  In the above example "SPACE" will be
emitted between "book" and "chapter", and "COMMA" will be emitted
between the chapter and the verse (again, the order matters).  See the
table above for some possibilities of using special characters.</P>

<P>There can be only one reference unit.</P>

<h3>Output style</h3>

<PRE class="code">
{PREHASH}output{PREUNDERSCORE}style = kwic
{PREHASH}output{PREUNDERSCORE}style = tree
output{PREUNDERSCORE}style = output
</PRE><!-- widthincm : 14 -->

<P>Specifies which implementation to use for emitting
solutions. Currently, three kinds of output style are implemented:</P>

<UL>
  <LI><strong>output</strong>: A "bracketed" view.
  <LI><strong>tree</strong>: A "tree" view
  <LI><strong>kwic</strong>: A "key words in context" view.
</UL>

<h3>Data tree parent</h3>

<PRE class="code">
{PREHASH} Tree parent feature.
{PREHASH} If output{PREUNDERSCORE}style = tree, then it is assumed that
{PREHASH} there is a feature on all relevant data units which gives the
{PREHASH} id{PREUNDERSCORE}d of the parent.  That is, each child node in the tree
{PREHASH} must have a feature which provides the id{PREUNDERSCORE}d of its parent.
{PREHASH} If a data{PREUNDERSCORE}unit is provided which does not have a data{PREUNDERSCORE}tree{PREUNDERSCORE}parent,
{PREHASH} then that data{PREUNDERSCORE}unit *must* contain the top-most nodes in the tree.
data{PREUNDERSCORE}tree{PREUNDERSCORE}parent = clause.parent
data{PREUNDERSCORE}tree{PREUNDERSCORE}parent = phrase.parent
data{PREUNDERSCORE}tree{PREUNDERSCORE}parent = word.parent
</PRE><!-- widthincm : 14 -->

<P>If "output_style" is set to "tree", then this option specifies, for
each terminal and non-terminal in the tree, what feature gives the
parent of the node.  Note that this feature must have type "id_d", and
the value must point to the id_d of the parent node.</P>

<h3>Tree terminal unit</h3>

<PRE class="code">
{PREHASH} Tree terminal unit.
{PREHASH} If output{PREUNDERSCORE}style = tree, then the Emdros Query Tool needs to know
{PREHASH} which object types are terminals (i.e., leaf nodes in the tree)
{PREHASH} and which object types are non-terminals.  This is done by
{PREHASH} designating *one* (1) data{PREUNDERSCORE}unit to be the data{PREUNDERSCORE}tree{PREUNDERSCORE}terminal{PREUNDERSCORE}unit.
{PREHASH} The rest of the data{PREUNDERSCORE}units will then be non-terminals.
data{PREUNDERSCORE}tree{PREUNDERSCORE}terminal{PREUNDERSCORE}unit = word
</PRE><!-- widthincm : 14 -->

<P>This options tells the tree layout code which data_unit contains
the terminals.  Note that the Emdros Query Tool assumes that terminals
and nonterminals are different object types.  There may be more than
one nonterminal object type, but only one terminal object type.  The
non-terminsl object types are determined based on the data_unit
option.</P>
<h3>Hit type</h3>

<PRE class="code">
{PREHASH} hit type
{PREHASH} hit{PREUNDERSCORE} must be one of:
{PREHASH}    focus
{PREHASH}    innermost
{PREHASH}    innermost{PREUNDERSCORE}focus
{PREHASH}    outermost
hit{PREUNDERSCORE}type    =  outermost
</PRE><!-- widthincm : 12 -->

<P>The hit type determines how the sheaf is interpreted.  There are
four available options:</P>

<UL>

   <LI><strong>focus</strong>: Means that an object originating in a
       block with the FOCUS keyword present will result in one "hit".

   <LI><strong>innermost</strong>: Means that only the innermost
       MatchedObjects will give rise to hits; one hit per string of
       blocks in which all matched objects have no descendants (i.e.,
       no inner sheaf).

   <LI><strong>innermost_focus</strong>: Like innermost, but only
       those matched objects whose &quot;focus&quot; boolean is set
       will have their monads included.

   <LI><strong>outermost</strong>: Means that only the outermost
       MatchedObjects will give rise to hits; one hit per outermost
       MatchedObject.

</UL>

<P>If none of these are specified, then &quot;outermost&quot; is
assumed as the default.</P>


<h3>Options</h3>

<PRE class="code">
{PREHASH} display options
option = apply{PREUNDERSCORE}focus
option = break{PREUNDERSCORE}after{PREUNDERSCORE}raster
option = quiet
option = single{PREUNDERSCORE}raster{PREUNDERSCORE}units
</PRE><!-- widthincm : 14 -->

<P>You can have these options:</P>

<table border="1">  <!-- columns : 2 -->
<tr>
  <th>Option</th>
  <th>Meaning</th>
</tr>

<tr>
  <td>apply_focus</td>
  <td>If set, then those data units which had the "focus" keyword in
  the original query will be surrounded by {OPENBRACE}braces{CLOSEBRACE} in the
  output.</td>
</tr>

<tr>
  <td>break_after_raster</td>
  <td>If set, then a newline is emitted after each raster-line.  If
  not set, then the raster-lines are run together.</td>
</tr>

<tr>
  <td>quiet</td>

  <td>If set, then only results will be printed; nothing else.  If not
  set, then things like progress and number of solutions will be
  printed.  If an error occurs, then that will be printed regardless
  of the status of this option.</td>

</tr>

<tr>
  <td>single_raster_units</td>

  <td>If set, then each raster unit will only ever be printed once.
      This affects the number of solutions printed: If two solutions
      each contain the same raster unit, then only one of the
      solutions will be printed.</td>

</tr>

</table>


<h3>Display options</h3>

<PRE class="code">
input{PREUNDERSCORE}area{PREUNDERSCORE}font{PREUNDERSCORE}name  = "Arial MS Unicode"
input{PREUNDERSCORE}area{PREUNDERSCORE}font{PREUNDERSCORE}size  = 11  {PREHASH} in points
output{PREUNDERSCORE}area{PREUNDERSCORE}font{PREUNDERSCORE}name{PREUNDERSCORE}1 = "SPIonic"
output{PREUNDERSCORE}area{PREUNDERSCORE}font{PREUNDERSCORE}name{PREUNDERSCORE}2 = "Courier New"
output{PREUNDERSCORE}area{PREUNDERSCORE}font{PREUNDERSCORE}name{PREUNDERSCORE}3 = "Times New Roman"
output{PREUNDERSCORE}area{PREUNDERSCORE}magnification  = 100  {PREHASH} in percent (%)
</PRE><!-- widthincm : 14 -->

<P>You can set the default font name and font size (in points) for the
input area.</P>

<P>You cannot set the font size in points for the output area.
Instead, you can set it to a percentage of 12 point.  For example,
setting output_area_magnification to 150 will select a font size of 18
points, and setting it to 200 will select a font size of 24
points.</P>
	


</page>



<page ID="3000">

<h2>Topographic queries vs. table-queries</h2>

<P>The Emdros Query Tool can display two kinds of results: Sheaves
(from topographic queries) and tables (from all other queries).</P>

<h2>Topographic queries</h2>

<P>Topographic queries are described in the <page_anchor
ID="3100">cheat sheet</page_anchor>.</P>

</page>


<page ID="3100">

<h2>Preamble</h2>

<P>For topographic queries, you must prefix the query with this magic
incantation:</P>

<PRE class="code">
SELECT ALL OBJECTS
WHERE
// Your query here.