jena-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From chrisdol...@apache.org
Subject svn commit: r1398843 [2/2] - in /jena/Scratch/Eyeball/trunk/doc: ./ eyeball-1-doc/
Date Tue, 16 Oct 2012 15:20:36 GMT
Added: jena/Scratch/Eyeball/trunk/doc/eyeball-2.4-full.html
URL: http://svn.apache.org/viewvc/jena/Scratch/Eyeball/trunk/doc/eyeball-2.4-full.html?rev=1398843&view=auto
==============================================================================
--- jena/Scratch/Eyeball/trunk/doc/eyeball-2.4-full.html (added)
+++ jena/Scratch/Eyeball/trunk/doc/eyeball-2.4-full.html Tue Oct 16 15:20:36 2012
@@ -0,0 +1,1396 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><!--
+  This is not the document you want to edit.
+
+  This document has been generated by the TOC-insertion tool.
+  You want to edit its template, not this document, which is
+  constructed by the `ant massage-manual` command from
+  `full-template.html`.
+
+--><html>
+<head>
+  <title>Eyeball 2.4</title>
+  <link href='styles/doc.css' rel='stylesheet' type='text/css'/>
+  <script>
+    function invert( id )
+      {
+      x = document.getElementById( id )
+      x.className = x.className == "hide" ? "show" : "hide"    
+      }
+  </script>
+</head>
+<body>
+  <h1>summary</h1>
+
+  <p>This document describes Eyeball 2.4, an 
+    "<a href='http://www.w3.org/RDF/'>RDF</a> 
+    <a href='http://en.wikipedia.org/wiki/Lint_programming_tool'>lint</a>"; 
+    see the 
+    <a href='ReleaseNotes.text'>release notes</a> for descriptions 
+    of changes from previous versions.
+    Eyeball is part of the Jena family of RDF/OWL tools: see
+    <a href='http://jena.sourceforge.net'>jena.sourceforge.net</a>
+    for the Jena documentation and downloads. Support for the
+    Jena family is provided on the mailing lists
+    <i>jena-dev@yahoogroups.com</i> (for developers using Jena)
+    and <i>jena-devel@lists.sourceforge.net</i> (for developers
+    modifying or extending Jena). Note that, ny support is provided 
+    on a voluntary basis, as and when the effort is available.
+  </p>
+
+  <p>
+  Throughout this document, the prefix <i>eye</i> stands for the 
+  URL <i>http://jena.hpl.hp.com/Eyeball#</i>.
+  </p>
+
+  <h1 onClick='invert(&apos;TOC&apos;)'>table of contents [click to reveal]</h1>
+
+  <div class='hide' id='TOC'>
+    <div class='toc'>
+    <div class='toc-h2'><a href='#toc-0'>installation</a></div><div class='toc-h2'><a href='#toc-1'>command line operation</a></div><div class='toc-h3'><a href='#toc-2'>examples of command-line use</a></div><div class='toc-h3'><a href='#toc-3'>-check specialURL+</a></div><div class='toc-h3'><a href='#toc-4'>-config fileOrURL and -root rootURI</a></div><div class='toc-h3'><a href='#toc-5'>-set Setting*</a></div><div class='toc-h3'><a href='#toc-6'>-include/-exclude shortNames</a></div><div class='toc-h3'><a href='#toc-7'>-assume Reference</a></div><div class='toc-h3'><a href='#toc-8'>-sign and -accept (experimental)</a></div><div class='toc-h3'><a href='#toc-9'>-version</a></div><div class='toc-h3'><a href='#toc-10'>-remark</a></div><div class='toc-h3'><a href='#toc-11'>-repair and -analyse (experimental)</a></div><div class='toc-h3'><a href='#toc-12'>-render Name</a></div><div class='toc-h3'><a href='#toc-13'>setting the proxy</a></div><div class='toc-h2'><a href='#toc-14'>i
 nspectors shipped with Eyeball</a></div><div class='toc-h3'><a href='#toc-15'>PropertyInspector (short name: &quot;property&quot;)</a></div><div class='toc-h3'><a href='#toc-16'>ClassInspector (short name: &quot;presumed-class&quot;)</a></div><div class='toc-h3'><a href='#toc-17'>URIInspector (short name: &quot;URI&quot;)</a></div><div class='toc-h3'><a href='#toc-18'>LiteralInspector (short name: &quot;literal&quot;)</a></div><div class='toc-h3'><a href='#toc-19'>PrefixInspector (short name: &quot;prefix&quot;)</a></div><div class='toc-h3'><a href='#toc-20'>VocabularyInspector (short name: &quot;vocabulary&quot;)</a></div><div class='toc-h3'><a href='#toc-21'>OwlSyntaxInspector (short name: &quot;owl&quot;)</a></div><div class='toc-h3'><a href='#toc-22'>SparqlDrivenInspector (short name: &quot;sparql&quot;)</a></div><div class='toc-h3'><a href='#toc-23'>AllTypedInspector (short name: &quot;all-typed&quot;)</a></div><div class='toc-h3'><a href='#toc-24'>ConsistentTypeInspect
 or (short name: &quot;consistent-type&quot;)</a></div><div class='toc-h3'><a href='#toc-25'>CardinalityInspector (short name: &quot;cardinality&quot;)</a></div><div class='toc-h3'><a href='#toc-26'>ListInspector (short name: &quot;list&quot;)</a></div><div class='toc-h2'><a href='#toc-27'>Eyeball problem reports</a></div><div class='toc-h3'><a href='#toc-28'>PropertyInspector: predicate not declared</a></div><div class='toc-h3'><a href='#toc-29'>ClassInspector: class not declared</a></div><div class='toc-h3'><a href='#toc-30'>URIInspector: bad URI</a></div><div class='toc-h3'><a href='#toc-31'>LiteralInspector: illegal language code</a></div><div class='toc-h3'><a href='#toc-32'>LiteralInspector: bad datatype URI</a></div><div class='toc-h3'><a href='#toc-33'>LiteralInspector: bad lexical form</a></div><div class='toc-h3'><a href='#toc-34'>PrefixInspector: bad namespace URI</a></div><div class='toc-h3'><a href='#toc-35'>PrefixInspector: Jena prefix found</a></div><div class=
 'toc-h3'><a href='#toc-36'>PrefixInspector: multiple prefixes for namespace</a></div><div class='toc-h3'><a href='#toc-37'>VocabularyInspector: not from schema</a></div><div class='toc-h3'><a href='#toc-38'>OwlSyntaxInspector: suspicious restriction</a></div><div class='toc-h3'><a href='#toc-39'>SparqlDrivenInspector: require failed</a></div><div class='toc-h3'><a href='#toc-40'>SparqlDrivenInspector: prohibit failed</a></div><div class='toc-h3'><a href='#toc-41'>AllTypedInspector: should have type</a></div><div class='toc-h3'><a href='#toc-42'>ConsistentTypeInspector: inconsistent types for resource</a></div><div class='toc-h3'><a href='#toc-43'>CardinalityInspector: cardinality failure</a></div><div class='toc-h3'><a href='#toc-44'>ListInspector: ill-formed list</a></div><div class='toc-h3'><a href='#toc-45'>ListInspector: suspect list idiom</a></div><div class='toc-h2'><a href='#toc-46'>inside the Eyeball configuration file</a></div><div class='toc-h3'><a href='#toc-47'>c
 onfiguration files</a></div><div class='toc-h3'><a href='#toc-48'>configuring schema names</a></div><div class='toc-h3'><a href='#toc-49'>configuring inspectors</a></div><div class='toc-h3'><a href='#toc-50'>configuring the URI inspector</a></div><div class='toc-h3'><a href='#toc-51'>configuring the vocabulary inspector</a></div><div class='toc-h3'><a href='#toc-52'>configuring the SPARQL-driven inspector</a></div><div class='toc-h3'><a href='#toc-53'>configuring renderers</a></div><div class='toc-h2'><a href='#toc-54'>inside the Eyeball code</a></div><div class='toc-h3'><a href='#toc-55'>creating an Eyeball</a></div><div class='toc-h3'><a href='#toc-56'>to eyeball a model</a></div><div class='toc-h2'><a href='#toc-57'>rebuilding Eyeball</a></div><div class='toc-h2'><a href='#toc-58'>creating and configuring an inspector</a></div><div class='toc-h3'><a href='#toc-59'>creating an Inspector</a></div><div class='toc-h3'><a href='#toc-60'>reports and report properties</a></div><
 div class='toc-h3'><a href='#toc-61'>configuring an inspector</a></div></div>
+  </div>
+
+  <h1>Eyeball - checking RDF for common problems</h1>
+
+  <p>Eyeball is a
+  library and command-line tool for checking RDF and OWL models for
+  various common problems. These problems often result in
+  technically correct but implausible RDF. Eyeball checks against
+  user-provided schema files and makes various closed-world
+  assumptions.
+  </p>
+
+  <p>Eyeball 2.4 can check for:</p>
+
+  <ul>
+    <li>unknown [with respect to the schemas] properties and classes</li>
+    <li>bad prefix namespaces</li>
+    <li>ill-formed URIs, with user-specifiable constraints</li>
+    <li>ill-formed language tags on literals</li>
+    <li>datatyped literals with illegal lexical forms</li>
+    <li>unexpected local names in schema namespaces</li>
+    <li>untyped resources and literals</li>
+    <li>individuals having consistent types, assuming complete typing</li>
+    <li>likely cardinality violations</li>
+    <li>broken RDF list structures</li>
+    <li>suspected broken use of the typed list idiom</li>
+    <li>obviously broken OWL restrictions</li>
+    <li>user-specified constraints written in SPARQL</li>
+  </ul>
+
+  <p>Eyeball's checks are performed by Inspector plug-ins and can
+  be customised by the user. Rendering its reports to output is
+  performed by Renderer plug-ins which can also be customised by
+  the user.</p>
+
+  <h2><a name='toc-0'></a>installation</h2>
+
+  <p>Fetch the Eyeball distribution zipfile and unpack it somewhere
+  convenient. Read the documention in the <i>doc</i> directory: the
+  one-minute guide <i>index.html</i>, the brief introduction
+  <i>brief.html</i>, and when necessary the manual <i>full.html</i>
+  (that's what this is).</p>
+
+  <p>Eyeball 2.4 comes with its own copy of Jena 2.5 with CVS
+  updates. Do <i>not</i> attempt to use other versions of Jena with
+  Eyeball.</p>
+
+  <p>In the Eyeball distribution directory, run the Eyeball
+  tests:
+  </p>
+
+  <blockquote>
+    ant test
+  </blockquote>
+
+  <p>
+    If these tests fail, something is wrong. 
+
+    (The message <i>(Note: 
+    statistician test disabled; don't worry about this.)</i> is not a
+    failure.)
+    
+    Sometimes
+    it's no more than a classpath problem, which you can fix. If not,
+    use the <i>jena-dev</i> mailing list to request assistance. Note that,
+    just as with Jena itself, any support is provided on a voluntary
+    basis, as and when the effort is available.
+  </p>
+
+  <p>
+    If the tests have passed, you can use Eyeball from the installation
+    directory, or copy <i>lib</i>, <i>etc</i> and <i>mirror</i> to
+    somewhere convenient.
+  </p>
+
+  <h2><a name='toc-1'></a>command line operation</h2>
+
+  <p>
+    You must ensure that <i>all</i> the Eyeball jars from <i>lib</i>
+    are on your classpath. (Note that Eyeball comes with its own Jena 
+    jar files and <i>may not work</i> with other Jena jars.) The
+    directories <i>etc</i> and <i>mirror</i> should be in the
+    current directory or also on your classpath.
+  </p>
+
+  <p>Run the Eyeball command:</p>
+
+    <pre>
+java [java options eg classpath and proxy] jena.eyeball
+    (-check | -sign | -accept) specialURL+
+    [-assume Reference*]
+    [-config fileOrURL*]
+    [-set Setting*]
+    [-root rootURI]
+    [-render Name]
+    [-include shortName*]
+    [-exclude shortName*]
+    [-analyse | -repair]
+    [-remark] [-version]
+</pre>
+  
+  <p>
+    The -<i>whatever</i> sections can come in any order
+    and may be repeated, in which case the additonal arguments are appended
+    to the existing ones. Exactly one of <i>-check</i>, <i>-sign</i>,
+    <i>-accept</i>, or <i>version</i> must be provided; all the other 
+    options are optional.
+  </p>
+
+  <p>
+    When Eyeball resolves ordinary filenames or URLs it uses the
+    Jena file manager to possibly map those names (<i>eg</i> to
+    redirect an <code>http:</code> URL to a local cached copy).
+    See the 
+    <a href='http://jena.sourceforge.net/how-to/filemanager.html'>
+    file manager howto</a> for details on how to configure the
+    file manager.
+  </p>
+
+  <h3><a name='toc-2'></a>examples of command-line use</h3>
+
+    <pre>
+java jena.eyeball -version
+
+java jena.eyeball -check myDataFile.rdf
+
+java jena.eyeball -assume dc -check http://example.com/nosuch.n3
+
+java jena.eyeball -assume mySchema.rdf -check myData.rdf -render xml
+
+java jena.eyeball -check myData.rdf -include consistent-type
+
+java jena.eyeball -check myConfig.ttl -sign &gt;signedConfig.ttl
+</pre>
+
+  <h3><a name='toc-3'></a>-check specialURL+</h3>
+
+  <p>The <i>-check</i> command checks the specified models for
+  problems. The <i>specialURL</i>s designate the models to be
+  checked. In the simplest case, these are plain filenames,
+  <code>file:</code> URLs, or <code>http:</code> URLs. At least one
+  <i>specialURL</i> must be specified. Each specified model is
+  checked independently of the others.</p>
+
+  <pre>
+-check myModel.ttl
+-check file:///c:/rdf/pizza.owl
+-check http://example.com/rdf/beer.rdf
+</pre>
+
+  <p>If the <i>specialURL</i> is of the form <i>ont:NAME:base</i>,
+  then the checked model is the model <i>base</i> treated as an
+  OntModel with the specification
+  <code>OntModelSpec.<i>NAME</i></code>; see <a href='http://jena.sourceforge.net/ontology/index.html#creatingModels'>the
+  Jena ontology documentation</a> for the available names.</p>
+  <pre>
+-check ont:OWL_MEM_RDFS_INF:myModel.ttl
+-check ont:OWL_DL_MEM_RULE_INF:http://example.com/rdf/beer.rdf
+</pre>
+
+  <p>If the <i>specialURL</i> is of the form <i>ja:R@AF</i>, then
+  the model is that described by the resource <i>R</i> in the Jena
+  <a href='http://jena.sourceforge.net/assembler/index.html'>assembler</a>
+  description file <i>AF</i>. <i>R</i> is prefix-expanded using the
+  prefixes in <i>AF</i>.</p>
+  <pre>
+-check ja:my:root@my-assembly.ttl
+-check ont:OWL_MEM_RDFS_INF:my:root@my-assembly.ttl
+</pre>
+
+  <p>If the URL (or the base) is of the form
+  <i>jdbc:DB:head:model</i>, then the checked model is the one
+  called <i>model</i> in the database with connection
+  <i>jdbc:DB:head</i>. (The database user and password must be
+  specified independently using the <i>jena.db.user</i> and
+  <i>jena.db.password</i> system properties.)</p>
+  <pre>
+-check jdbc:mysql://localhost/test:example
+</pre>
+
+  <h3><a name='toc-4'></a>-config fileOrURL and -root rootURI</h3>
+
+  <p>The <i>-config fileOrURL</i> options specify the Eyeball
+  <a href='http://jena.sourceforge.net/assembler/index.html'>assembler</a>
+  configuration files to load. A single configuration model is
+  constructed as the union of the contents of those files. If this
+  option is omitted, the default configuration file
+  <i>etc/eyeball-config.n3</i> is loaded. See <a href='#inside-configuration'>inside the Eyeball configuration file</a> 
+  for details of the configuration file.</p>
+  <pre>
+-config my-hacked-config-file.n3
+-config etc/eyeball-config.n3 extras.ttl
+</pre>
+
+  <p>The <i>-root rootURI</i> option specifies the root resource in
+  the Eyeball configuration. If this option is omitted,
+  <i>eye:eyeball</i> is used by default. <i>rootURI</i> is
+  prefix-expanded using the prefixes in the configuration file.</p>
+  <pre>
+-root my:root
+-root my:sparse-config
+-root urn:x-hp:eyeball-roots:special
+</pre>
+
+  <h3><a name='toc-5'></a>-set Setting*</h3>
+
+  <p>
+    The <i>-set</i> option allows command-line tweaks to the
+    configuration, <i>eg</i> for enabling checking URIs for
+    empty local names. <i>You will rarely need to use this</i>;
+    it is presented here because of its association with
+    the <code>-config</code> and <code>-root</code> options.
+  </p>
+
+  <p>
+    Each <i>Setting</i> has the form <code>S.P=O</code> and adds 
+    the statement <code>(S' P' O')</code> to the configuration.
+  </p>
+
+  <p>
+    The current Eyeball converts the components of the
+    <code>S.P=O</code> string into RDF nodes <code>S'</code>,
+    <code>P'</code>, <code>O'</code> using some special rules:
+  </p>
+
+  <ul>
+    <li>
+      A component starting with a digit is treated as an
+      xsd:integer literal (and hence should only appear as
+      the object of the setting).
+    </li>
+
+    <li>
+      A component starting with a quote, either <code>"</code>
+      or <code>'</code>, is treated as a literal whose lexical
+      form extends to the matching closing quote. Note:
+      (a) <i>literals with embedded spaces are not supported</i>;
+      (b) your command-line interpreter may treat quotes
+      specially, and to allow the quotes to pass through to
+      Eyeball, you'll have to use another (different) pair of
+      quotes!
+    </li>
+
+    <li>
+      A component starting with <code>_</code> is treated
+      as a blank node with that label.
+    </li>
+
+    <li>
+      Otherwise, the component is treated as a URI reference.
+      If it starts with a prefix (<i>eg</i>, <code>rdf:</code>)
+      that prefix is expanded using the prefixes of the configuration
+      file. If it has no prefix, it is as though the empty prefix
+      was specified: in the default configuration file, that is
+      set to the Eyeball namespace, so it is as though the prefix
+      <code>eye:</code> had been used.
+    </li>
+  </ul>
+
+  <p>
+    For example, to enable the URI inspectors non-default reporting
+    of URIs with empty local names, use:
+  </p>
+  
+  <pre>
+-set URIInspector.reportEmptyLocalNames="'true'"
+</pre>
+
+  <p>
+    Note the nested different quotes required to pass 'true'
+    to Eyeball so that it can interpret this as a literal.
+  </p>
+
+  <h3><a name='toc-6'></a>-include/-exclude shortNames</h3>
+
+  <p>
+    The various Eyeball inspectors are given <i>short names</i> in
+    the configuration file. By default, an Eyeball check uses a
+    specific set of inspectors with short name
+    <i>defaultInspectors</i>. Additional inspectors can be enabled
+    using the <i>-include</i> option, and default inspectors can be
+    disabled using the <i>-exclude</i> option. See below for the
+    available inspectors and their short names, and see <a href='#inspectors-configuration'>inspectors configuration</a> for
+    how to configure inspectors.
+  </p>
+  
+  <pre>
+-include list all-typed
+-exclude cardinality
+-include owl -exclude consistent-type
+</pre>
+
+  <h3><a name='toc-7'></a>-assume Reference</h3>
+
+  <p>The -assume <i>Reference</i>s identifies any assumed schemas
+  used to specify the predicates and classes of the data model. The
+  reference may be a file name or a URL (and may be mapped by the
+  file manager).</p>
+
+  <p>Eyeball automatically assumes the RDF and RDFS schemas, and
+  the built-in XSD datatype classes. The short name <i>owl</i> can
+  be used to refer to the OWL schema, <i>dc</i> to the Dublin Core
+  schema, <i>dcterms</i> to the Dublin Core terms schema, and
+  <i>dc-all</i> to both.</p>
+
+<pre>
+-assume owl
+-assume owl dc-all
+-assume owl my-ontology.owl
+</pre>
+
+  <h3><a name='toc-8'></a>-sign and -accept (experimental)</h3>
+
+  <p>If <i>-sign</i> is specified, Eyeball first does a 
+     <i>-check</i>. If no problem reports are 
+     generated, Eyeball writes a <i>signed</i> version of
+     the current model to the standard output. The signature
+     records the Eyeball configuration used and a weak hash
+     of the model. If the input model is already signed, that
+     signature is discarded before computing the new signature
+     and writing the output.
+  </p>
+
+  <p>
+    If <i>-accept</i> is specified, the model is checked for its 
+    signature. If it is not signed, or if the signature does
+    not match the content of the model -- either the hash fails,
+    or the recorded configuration is not sufficient -- a problem 
+    is reported; otherwise not.
+  </p>
+
+  <p>
+     The intended use of <i>-sign</i> and <i>-accept</i>
+     is that an application can require signed models
+     which have passed some minimum set of inspections.
+     The application code can then rely on the model
+     having the desired properties, without having to
+     run potentially expensive validation checks every
+     time a model is loaded.
+  </p>
+
+  <p>
+    <i>Important</i>. Model signing is intended to catch careless
+    mistakes, not for security against malicious users.
+  </p>
+
+  <h3><a name='toc-9'></a>-version</h3>
+
+  <p>
+    Eyeball will print its version on the standard error
+    stream (currently "<i>Eyeball 2.4 (Nova Embers)</i>").
+  </p>
+  
+  <h3><a name='toc-10'></a>-remark</h3>
+
+  <p>Normally Eyeball issues its report or signed model to
+     the standard output and exits with code 0 (success)
+     or 1 (failure) with no additional output. Specifying
+     <i>-remark</i> causes it to report <i>success</i>
+     or <i>some problems reported</i> to standard error.
+  </p>
+
+
+  <h3><a name='toc-11'></a>-repair and -analyse (experimental)</h3>
+
+  <p>These operations are not currently documented. Try them at
+     your peril: <i>-repair</i> may attempt to update your models.
+  </p>
+
+  <h3><a name='toc-12'></a>-render Name</h3>
+
+  <p>The eyeball reports are written to the standard output; by
+  default, the reports appear as text (RDF rendered by omitting the
+  subjects - which are all blank nodes - and lightly prettifying
+  the predicate and object). To change the rendering style, supply
+  the <i>-render</i> option with the name of the renderer as its
+  value. Eyeball comes with N3, XML, and text renderers; the
+  Eyeball config file associates renderer names with their
+  classes.</p>
+  <pre>
+-render n3
+-render rdf
+</pre>
+
+  <h3><a name='toc-13'></a>setting the proxy</h3>
+
+  <p>
+    If any of the data or schema are identified by an http: URL,
+    and you are behind a firewall, you will need specify the proxy to
+    Java using system properties; one way to do this is by using the
+    Java command line options:
+  </p>
+
+  <pre>
+    -DproxySet=true
+    -DproxyHost=theProxyHostName
+    -DproxyPort=theProxyPortNumber
+</pre>
+
+  <h2><a name='toc-14'></a>inspectors shipped with Eyeball</h2>
+
+  <p>Eyeball comes with a collection of inspectors that do
+  relatively simple checks.</p>
+
+  <h3><a name='toc-15'></a>PropertyInspector (short name: "property")</h3>
+
+  <p>Checks that every predicate that appears in the model is
+  declared in some <i>-assume</i>d schema or
+  <code>owl:import</code>ed model -- that is, is given
+  <code>rdf:type</code> <code>rdf:Property</code> or some subclass
+  of it.</p>
+
+  <h3><a name='toc-16'></a>ClassInspector (short name: "presumed-class")</h3>
+
+  <p>Checks that every resource in the model that is used as a
+  class, <i>ie</i> that appears as the object of an
+  <code>rdf:type</code>, <code>rdfs:domain</code>, or
+  <code>rdfs:range</code> statement, or as the subject or object of
+  an <code>rdfs:subClassOf</code> statement, has been declared as a
+  <code>Class</code> in the <i>-assume</i>d schemas or in the model
+  under test.</p>
+
+  <h3><a name='toc-17'></a>URIInspector (short name: "URI")</h3>
+
+  <p>Checks that every URI in the model is well-formed according to
+  the rules of the Jena IRI library. May apply additional rules
+  specified in the configuration file: see <a href='#uri-configuration'>uri configuration</a> later for details.</p>
+
+  <h3><a name='toc-18'></a>LiteralInspector (short name: "literal")</h3>
+
+  <p>
+    Checks literals for syntactically correct language codes,
+    syntactically correct datatype URIs (using the same rules as the
+    URIInspector), and conformance of the lexical form of typed
+    literals to their datatype.
+  </p>
+
+  <h3><a name='toc-19'></a>PrefixInspector (short name: "prefix")</h3>
+
+  <p>The PrefixInspector checks that the prefix declarations of the
+  model have namespaces that are valid URIs and that if the prefix
+  name is "well-known" (<code>rdf</code>, <code>rdfs</code>,
+  <code>owl</code>, <code>xsd</code>, and <code>dc</code>) then the
+  associated URI is the one usually associated with the prefix.</p>
+
+  <p>The PrefixInspector also reports a problem if any prefix looks
+  like an Jena automatically-generated prefix,
+  <code>j.<i>Number</i></code>. (Jena generates these prefixes when
+  writing RDF/XML if the XML syntactically requires a prefix but
+  the model hasn't defined one.)</p>
+
+  <h3><a name='toc-20'></a>VocabularyInspector (short name: "vocabulary")</h3>
+
+  <p>Checks that every URI in the model with a namespace which is
+  mentioned in some schema is one of the URIs declared for that
+  namespace -- that is, it assumes that the schemas define a closed
+  set of URIs.</p>
+
+  <p>The inspector may be configured to suppress this check for
+  specified namespaces: see <a href='#configure-vocabulary'>vocabulary configuration</a> later.</p>
+
+  <h3><a name='toc-21'></a>OwlSyntaxInspector (short name: "owl")</h3>
+
+  <p>This inspector looks for "suspicious restrictions" which have
+  some of the OWL restriction properties but not exactly one
+  owl:onProperty and exactly one constraint (owl:allValuesFrom,
+  etc).</p>
+
+  <h3><a name='toc-22'></a>SparqlDrivenInspector (short name: "sparql")</h3>
+
+  <p>The SparqlDrivenInspector is configured according to <a href='#SPARQL-driven'>configuring the SPARQL-driven inspector</a>, and
+  applies arbitrary SPARQL queries to the model. The queries can be
+  required to match or prohibited from matching; a problem is
+  reported if the constraint fails.</p>
+
+  <h3><a name='toc-23'></a>AllTypedInspector (short name: "all-typed")</h3>
+
+  <p>
+    Checks that all URI and bnode resources in the model have an 
+    rdf:type property in the model or the schema(s). If there is 
+    a statement in the confiuration with property 
+    <code>eye:checkLiteralTypes</code> and value <code>eye:true</code>, 
+    also checks that every literal has a type or a language. 
+    <i>Not</i> in the default set of inspectors.
+  </p>
+
+  <h3><a name='toc-24'></a>ConsistentTypeInspector (short name: "consistent-type")</h3>
+
+  <p>
+    Checks that every subject in the model can
+    be given a type which is the intersection of the subclasses of
+    all its "attached" types -- a "consistent type".
+  </p>
+
+  <p>
+    For example, if the model contains three types
+    <code>Top</code>, <code>Left</code>, and <code>Right</code>, with
+    <code>Left</code> and <code>Right</code> both being subtypes of
+    <code>Top</code> and with no other subclass statements, then some
+    <code>S</code> with <code>rdf:type</code>s <code>Left</code> and
+    <code>Right</code> would generate this warning.
+  </p>
+
+  <h3><a name='toc-25'></a>CardinalityInspector (short name: "cardinality")</h3>
+
+  <p>
+    Looks for  classes <i>C</i> that are subclasses of cardinality 
+    restrictions on some property <i>P</i> with cardinality range 
+    <i>min</i> to <i>max</i>. For any <i>X</i> of <code>rdf:type</code> 
+    <i>C</i>, it checks that the number of values of <i>P</i> is in 
+    the range <i>min..max</i> and generates a report if it isn't.
+  </p>
+
+  <p>Literals are counted as distinct if their values (not just their
+     lexical form) are distinct. Resources are counted as distinct if
+     they have different case-sensitive URIs: the CardinalityInspector
+     takes no account of <code>owl:sameAs</code> statements. 
+  </p>
+
+  <h3><a name='toc-26'></a>ListInspector (short name: "list")</h3>
+
+  <p>The ListInspector performs two separate checks:
+  </p>
+
+  <ul>
+    <li>looks for lists that are ill-formed by having multiple or
+    missing rdf:first or rdf:rest properties on their elements.
+    </li>
+
+    <li>looks for possible mis-uses of the "typed list" idiom, and
+    reports the types so defined.
+    </li>
+  </ul>
+
+  <p>The <i>typed list idiom</i> is boilerplate OWL for defining
+  a type which is List-of-T for some type T. It takes the form:
+  </p>
+
+  <pre>
+my:EList a owl:Class
+    ; rdfs:subClassOf rdf:List
+    ; rdfs:subClassOf [owl:onProperty rdf:first; owl:allValuesFrom my:Element]
+    ; rdfs:subClassOf [owl:onProperty rdf:rest; owl:allValuesFrom my:EList]
+    .
+</pre>
+
+  <p>
+    The type <code>my:Element</code> is the element type of the
+    list, and the type <code>EList</code> is the resulting typed list.
+    The list inspector checks that all the subclasses of
+    <code>rdf:List</code> (such as <i>EList</i> above) that are also 
+    subclasses of any bnode (such as the two other superclasses of
+    <i>EList) </i>that has any property (<i>eg</i>, <i>owl:onProperty</i>)
+    that has as an object either <code>rdf:first</code> or 
+    <code>rdf:rest</code> is a subclass defined by the full idiom above: 
+    if not, it reports it as a <code> suspectListIdiom</code>.
+  </p>
+
+  <h2><a name='toc-27'></a>Eyeball problem reports</h2>
+
+  <p>Eyeball generates its reports as <i>items</i> in a model. Each
+  item has <code>rdf:type</code> <code>eye:Item</code>, and its
+  other properties determine what problem report it is. The default
+  text renderer displays a prettified form of each item; use
+  <i>-render n3</i> to expose the complete report structure.
+  </p>
+
+  <p>One of the item's properties is its <i>main property</i>,
+  which identifies the problem; the others are qualifications
+  supplying additional detail.
+  </p>
+
+  <h3><a name='toc-28'></a>PropertyInspector: predicate not declared</h3>
+
+  <blockquote>
+    [] eye:unknownPredicate "<i>URIString</i>".
+  </blockquote>
+
+  <p>The predicate with the given URI is not defined in any
+     of the <i>-assumed</i> schemas.
+  </p>
+
+  <h3><a name='toc-29'></a>ClassInspector: class not declared</h3>
+
+  <blockquote>
+    [] eye:unknownClass "<i>URIString</i>".
+  </blockquote>
+
+  <p>The resource with the given URI is used as a Class, but not 
+     defined in any of the <i>-assumed</i> schemas.
+  </p>
+
+  <h3><a name='toc-30'></a>URIInspector: bad URI</h3>
+
+  <blockquote>
+    [] eye:badURI "<i>URIString</i>"; eye:forReason <i>Reason</i>.
+  </blockquote>
+
+  <p>The <i>URIString</i> isn't legal as a URI, or is legal but fails
+     a user-specified spelling constraint. <i>Reason</i> is a 
+     resource or string identifying the reason.
+  </p>
+
+  <table border='1' style='margin-left: 4ex; margin-right: 4ex; font-size: x-small'>
+    <thead>
+      <tr><th>reason</th><th>explanation</th></tr>
+    </thead>
+    <tr>
+      <td>eye:uriContainsSpaces</td>
+      <td>the URI contains unencoded spaces, probably as a result
+      of sloppy use of file: URLs.</td>
+    </tr>
+
+    <tr>
+      <td>eye:uriFileInappropriate</td>
+      <td>a URI used as a namespace is a file: URI, which is
+      inappropriate as a global identifier.</td>
+    </tr>
+
+    <tr>
+      <td>eye:uriHasNoScheme</td>
+      <td>a URI has no scheme field, probably a misused relative
+      URI.</td>
+    </tr>
+
+    <tr>
+      <td>eye:schemeShouldBeLowercase</td>
+      <td>the scheme part of a URI is not lower-case; while
+      technically correct, this is not usual practice.</td>
+    </tr>
+
+    <tr>
+      <td>eye:uriFailsPattern</td>
+      <td>a URI fails the pattern appropriate to its schema (as
+      defined in the configuration for this eyeball).</td>
+    </tr>
+
+    <tr>
+      <td>eye:unrecognisedScheme</td>
+      <td>the URI scheme is unknown, perhaps a misplaced
+      QName.</td>
+    </tr>
+
+    <tr>
+      <td>eye:uriNoHttpAuthority</td>
+      <td>an http: URI has no authority (domain name/port)
+      component.</td>
+    </tr>
+
+    <tr>
+      <td>eye:uriSyntaxFailure</td>
+      <td>the URI can't be parsed using the general URI syntax,
+      even with any spaces removed.</td>
+    </tr>
+
+    <tr>
+      <td>eye:namespaceEndsWithNameCharacter</td>
+      <td>a namespace URI ends in a character that can appear in a
+      name, leading to possible ambiguities.</td>
+    </tr>
+
+    <tr>
+      <td>eye:uriHasNoLocalname</td>
+      <td>a URI has no local name according to the XML
+      name-splitting rules. (For example, the URI
+      <i>http://x.com/foo#12345</i> has no local name because a
+      local name cannot start with a digit.)</td>
+    </tr>
+
+    <tr>
+      <td>"did not match required pattern <i>Tail<sub>i</sub></i> for prefix <i>Head</i>".
+      </td>
+      <td>This badURI starts with <i>Head</i>, but the remainder doesn't
+          match any of the <i>Tail<sub>i</sub></i>s associated with that
+          prefix.
+      </td>
+    </tr>
+
+    <tr>
+      <td>"matched prohibited pattern <i>Tail</i> for prefix <i>Head</i>".
+      </td>
+      <td>This badURI starts with <i>Head</i>, and the remainder matched
+          a prohibited <i>Tail</i> associated with that prefix.
+      </td>
+    </tr>
+  </table>
+
+  <h3><a name='toc-31'></a>LiteralInspector: illegal language code</h3>
+
+  <blockquote>
+    [] eye:badLanguage "<i>badCode</i>"; eye:onLiteral "<i>spelling</i>".
+  </blockquote>
+
+  <p>A literal with the lexical form <i>spelling</i> has the illegal
+     language code <i>badCode</i>.
+  </p>
+
+  <h3><a name='toc-32'></a>LiteralInspector: bad datatype URI</h3>
+
+  <blockquote>
+    [] eye:badDatatypeURI "<i>badURI</i>"; eye:onLiteral "<i>spelling</i>".
+  </blockquote>
+
+  <p>A literal with the lexical form <i>spelling</i> has the illegal
+     datatype URI <i>badURI</i>.
+  </p>
+
+  <h3><a name='toc-33'></a>LiteralInspector: bad lexical form</h3>
+
+  <blockquote>
+    [] eye:badLexicalForm "<i>spelling</i>"; eye:forDatatype "<i>dtURI</i>".
+  </blockquote>
+
+  <p>A literal with the datatype URI <i>dtURI</i> has the lexical form 
+     <i>spelling</i>, which isn't legal for that datatype.
+  </p>
+
+  <h3><a name='toc-34'></a>PrefixInspector: bad namespace URI</h3>
+
+  <blockquote>
+    [] eye:badNamespaceURI "<i>URIString</i>"
+     ; eye:onPrefix "<i>prefix</i>"
+     ; eye:forReason <i>Reason</i>.
+  </blockquote>
+
+  <p>The namespace <i>URIString</i> for the declaration of <i>prefix</i> 
+     is suspicious for the given <i>Reason</i> (see the URIInspector reports
+     for details of the possible reasons).
+  </p>
+
+  <h3><a name='toc-35'></a>PrefixInspector: Jena prefix found</h3>
+
+  <blockquote>
+    [] eye:jenaPrefixFound "<i>j.Digits</i>"; eye:forNamespace "<i>URIString</i>".
+  </blockquote>
+
+  <p>The namespace <i>URIString</i> has an automatically-generated
+     Jena prefix.
+  </p>
+
+  <h3><a name='toc-36'></a>PrefixInspector: multiple prefixes for namespace</h3>
+
+  <blockquote>
+    [] eye:multiplePrefixesForNamespace "<i>NameSpace</i>"
+       ; eye:onPrefix "<i>prefix<sub>1</sub>"</i> ...
+  </blockquote>
+
+  <p>
+     There are multiple prefix declarations for <i>NameSpace</i>,
+     namely, <i>prefix<sub>1</sub></i> etc.
+  </p>
+
+  <h3><a name='toc-37'></a>VocabularyInspector: not from schema</h3>
+
+  <blockquote>
+    [] eye:notFromSchema "<i>NameSpace</i>"; eye:onResource <i>Resource</i>.
+  </blockquote>
+
+  <p>The <i>Resource</i> has a URI in the <i>NameSpace</i>, but isn't declared
+     in the schema associated with that <i>NameSpace</i>.
+  </p>
+
+  <h3><a name='toc-38'></a>OwlSyntaxInspector: suspicious restriction</h3>
+
+  <blockquote>
+    [] eye:suspiciousRestriction <i>R</i>; eye:forReason <i>Reason</i>...
+  </blockquote>
+
+  <p>The presumed restriction <i>R</i> is suspicious for the given <i>Reason</i>s:
+    <ul>
+     <li><code>eye:missingOnProperty</code> -- there is no 
+         <code>owl:onProperty</code> property in this suspicious restriction.
+     </li>
+     <li><code>eye:multipleOnProperty</code> -- there are multiple
+         <code>owl:onProperty</code> properties in this suspicious restriction.
+     </li>
+     <li><code>eye:missingConstraint</code> -- there is no <code>owl:hasValue</code>,
+         <code>owl:allValuesFrom</code>, <code>owl:someValuesFrom</code>, 
+         or <code>owl:[minC|maxC|c]ardinality</code> property in this suspicious
+         restriction.
+     </li>
+     <li><code>eye:multipleConstraint</code> -- there are multiple constraints 
+         (as above) in this suspicious restriction.
+    </li>
+    </ul>
+  </p>
+
+  <p>The restriction <i>R</i> is identified by (a) supplying its immediate properties,
+     and (b) identifying its named equivalent classes and subclasses.
+  </p>
+
+  <h3><a name='toc-39'></a>SparqlDrivenInspector: require failed</h3>
+
+  <blockquote>
+    [] eye:sparqlRequireFailed "<i>message</i>".
+  </blockquote>
+
+  <p>A SPARQL query that was required to succeed against the model did not.
+     The <i>message</i> is either the query that failed or a meaningful
+     description, depending on the inspector configuration.
+  </p>
+
+  <h3><a name='toc-40'></a>SparqlDrivenInspector: prohibit failed</h3>
+
+  <blockquote>
+    [] eye:sparqlProhibitFailed "<i>message</i>".
+  </blockquote>
+
+  <p>A SPARQL query that was required to fail against the model did not.
+     The <i>message</i> is either the query that succeeded or a meaningful
+     description, depending on the inspector configuration.
+  </p>
+
+  <h3><a name='toc-41'></a>AllTypedInspector: should have type</h3>
+
+  <blockquote>
+    [] eye:shouldHaveType <i>Resource</i>.
+  </blockquote>
+
+  <p>The <i>Resource</i> has no <code>rdf:type</code>. Note that
+     when using models with inference, this report is unlikely, since
+     inference may well give the resource a type even if it has
+     no explicit type in the original model.
+  </p>
+
+  <h3><a name='toc-42'></a>ConsistentTypeInspector: inconsistent types for resource</h3>
+
+  <blockquote>
+    [] eye:noConsistentTypeFor <i>URI</i>
+      ; eye:hasAttachedType <i>TypeURI<sub>i</sub></i> ...
+  </blockquote>
+
+  <p>
+    The resource <i>URI</i> has been given the various types 
+    <i>TypeURI<sub>i</sub></i>, but if we assume that subtypes are
+    disjoint unless otherwise specified, these types have no
+    intersection.
+  </p>
+
+  <p>The ConsistentTypeInspector must do at least some type
+  inference. This release of Eyeball compromises by doing RDFS
+  inference augmented by (very) limited union and intersection
+  reasoning, as described in the Jena rules in
+  <code>etc/owl-like.rules</code>, so its reports must be
+  treated with caution. Even with these restrictions, doing type inference
+  over a large model is costly: you may need to suppress it with
+  <code>-exclude</code> until any other warnings are dealt
+  with.
+  </p>
+
+  <p>While, technically, a resource with no attached types at all
+  is automatically inconsistent, Eyeball quietly ignores such
+  resources, since they turn up quite often in simple RDF
+  models.
+  </p>
+ 
+  <h3><a name='toc-43'></a>CardinalityInspector: cardinality failure</h3>
+
+  <blockquote>
+    [] eye:cardinalityFailure <i>Subject</i>; eye:onType <i>T</i>; eye:onProperty <i>P</i>
+  </blockquote>
+
+  <p>
+     The <i>Subject</i> has a cardinality-constrained <code>rdf:type</code> <i>T</i>
+     with <code>owl:onProperty</code> <i>P</i>, but the number of distinct values
+     in the model isn't consistent with the cardinality restriction.
+  </p>
+
+  <p>Additional properties describe the cardinality restriction and the values found:
+
+    <ul>
+      <li><code>eye:numValues</code> <i>N</i>: the number of distinct values
+          for (<i>Subject</i>, <i>P</i>) in the model.
+      </li>
+      <li><code>eye:cardinality</code> 
+         [<code>eye:min</code> <i>min</i>; <code>eye:max</code> <i>max</i>]:
+         the minimum and maximum cardinalities permitted.
+      </li>
+      <li><code>eye:values</code> <i>Set</i>: 
+        A blank node of type <code>eye:Set</code> with an <code>rdfs:member</code>
+        value for each of the values of <i>P</i>.
+      </li>
+    </ul>
+  </p>
+
+  <h3><a name='toc-44'></a>ListInspector: ill-formed list</h3>
+
+  <blockquote>
+    [] eye:illFormedList <i>URI</i>
+     ; eye:because [eye:element <i>index<sub>i</sub></i>; <i>Problem<sub>i</sub></i>]<sub>i</sub> ... 
+  </blockquote>
+
+  <p>The list starting at <i>URI</i> is ill-formed because the element with
+     index <i>index<sub>i</sub></i> had <i>Problem<sub>i</sub></i>. The
+     possible problems are:
+     <ul>
+       <li><code>eye:hasNoRest</code> -- the element has no <code>rdf:rest</code> property.
+       </li>
+       <li><code>eye:hasMultipleRests</code> -- the element has more than one
+           <code>rdf:rest</code> property.
+       </li>
+       <li><code>eye:hasNoFirst</code> -- the element has no <code>rdf:first</code> property.
+       </li>
+       <li><code>eye:hasMultipleFirsts</code> -- the element has more than one
+           <code>rdf:rest</code> property.
+       </li>
+     </ul>
+     
+  </p>
+
+  <h3><a name='toc-45'></a>ListInspector: suspect list idiom</h3>
+
+  <blockquote>
+    [] eye:suspectListIdiom <i>Type</i>.
+  </blockquote>
+
+  <p>
+    The resource <i>Type</i> looks like it's supposed to be a use of the
+    "typed list idiom", but it isn't complete/accurate.
+  </p>
+
+  <h2><a name='toc-46'></a><a name='inside-configuration'>inside the Eyeball configuration file</a></h2>
+
+  <h3><a name='toc-47'></a><a name='load-config-files' id='load-config-files'/>configuration files</h3>
+
+  The Eyeball
+  command-line utility is configured by files (or URLs) specified
+  on the command line: their RDF contents are unioned together into
+  a single config model. If no config file is specified, then
+  <i>etc/eyeball-config.n3</i> is loaded.
+
+  <p>
+    The configuration file is a Jena assembler description 
+    (see <a href='http://jena.sourceforge.net/assembler/index.html'>
+    http://jena.sourceforge.net/assembler/index.html</a>)
+    with added Eyeball vocabulary.
+  </p>
+
+  <p>Eyeball is also configured by the location-mapping file
+  <i>etc/location-mapping.n3</i>. The Eyeball jar contains copies
+  of both the default config and the location mapper; these are
+  used by default. You can provide your own
+  <i>etc/eyeball-config.n3</i> file earlier on your classpath or in
+  your current directory; this config replaces the default. You may
+  provide <i>additional</i> location-mapping files earlier on your
+  classpath or in your current directory.</p>
+
+  <h3><a name='toc-48'></a>configuring schema names</h3>
+
+  To avoid having to quote schema
+  names in full on the Eyeball command line, (collections of)
+  schemas can be given short names.
+
+    <pre>
+[] eye:shortName <i>shortNameLiteral</i>
+    ; eye:schema <i>fullSchemaURL</i>
+    ...
+    .
+</pre>
+
+  <p>
+  A shortname can name several schemas. The Eyeball
+  delivery has the short names <i>rdf</i>, <i>rdfs</i>, <i>owl</i>,
+  and <i>dc</i> for the corresponding schemas (and mirror versions
+  of those schemas so that they don't need to be downloaded each
+  time Eyeball is run.)
+  </p>
+
+  <h3><a name='toc-49'></a><a name='inspectors-configuration'>configuring inspectors</a></h3>
+
+  <p>
+  The inspectors that Eyeball runs
+  over the model are specfied by <i>eye:inspector</i> properties of
+  inspector resources. These resources are identified by
+  <code>eye:shortName</code>s (supplied on the command line). Each
+  such property value must be a plain string literal whose value is
+  the full name of the Inspector class to load and run; see the
+  Javadoc of Inspector for details.
+  </p>
+
+  <p>An inspector resource may refer to other inspector resources
+  to include their inspectors, using either of the two properties
+  <code>eye:include</code> or <code>eye:includeByName</code>. The
+  value of an <code>include</code> property should be another
+  inspector resource; the value of an <code>includeByName</code>
+  property should be the <code>shortName</code> of an inspector
+  resource.</p>
+
+  <h3><a name='toc-50'></a><a name='uri-configuration'>configuring the URI inspector</a></h3>
+
+  <p>As well as applying the standard URI rules, Eyeball allows
+  extra pattern-oriented checks to be applied to URIs. These are
+  specified by <code>eye:check</code> properties of the
+  <code>URIInspector</code> object in the configuration.</p>
+
+  <p>The object of an <code>eye:check</code> property is a bnode
+  with <code>eye:prefix</code>, <code>eye:prohibit</code>, and
+  <code>eye:require</code> properties. The objects of these
+  properties must be string literals.</p>
+
+  <p>If a URI <i>U</i> can be split into a prefix <i>P</i> and
+  suffix <i>S</i>, and there is a <i>check</i> property with that
+  prefix, and either:</p>
+
+  <ul>
+    <li>there's a <i>prohibit</i> property and <i>S</i> matches the
+    object of that property, or</li>
+
+    <li>there's a <i>require</i> property and <i>S</i> does not
+    match the object of that property,</li>
+  </ul>
+
+  <p>then a problem is reported. If there are multiple
+  <code>prohibit</code>s, then a problem is reported if <i>any</i>
+  prohibition is violated; if there are multiple
+  <code>require</code>s, a problem is reported if <i>none</i> of
+  them succeed.
+  </p>
+
+  <pre>
+eye:URIInspector eye:check 
+  [eye:prefix "urn:x-hp:"; eye:prohibit ".*:.*"]
+  ; [eye:prefix "http://example.com/"; eye:require ".*eyeball.*"]
+</pre>The prefixes, requires, and prohibits are treated as Java
+patterns.
+
+  <p>
+    The URI inspector can be configured to report URIs with an
+    empty local name. These arise because the meaning of "local
+    name" comes from XML, and in XML a local name must start with
+    an NCName character, typically a letter but not a digit. Hence
+    URIs like <code>http://example.com/productCode#1829</code> 
+    have an empty local name. This is sometimes confusing.
+  </p>
+
+  <p>
+    To report empty local names, add the property 
+    <code>eye:reportEmptyLocalNames</code> to the inspector
+    <code>eye:URIInspector</code> with the property value
+    <code>true</code>. You may edit the configuration file
+    or use the <code>-set</code> command-line option.
+  </p>
+
+  <h3><a name='toc-51'></a><a name='configure-vocabulary'>configuring the vocabulary inspector</a></h3>
+
+  <p>The vocabulary inspector defaults to assuming that schema
+  namespaces are closed. To disable this for specified namespaces,
+  the inspector object in the configuration can be given
+  <code>eye:openNamespace</code> properties.</p>
+
+  <p>The object of each of these properties must be a resource; the
+  URI of this resource is an open namespace for which the inspector
+  will not report problems.</p>
+  <pre>
+eye:VocabularyInspector eye:openNamespace &lt;http://example.com/examples#&gt;
+</pre>
+
+  <h3><a name='toc-52'></a><a name='SPARQL-driven'>configuring the SPARQL-driven inspector</a></h3>
+
+  <p>The SPARQL inspector object in the configuration may be given
+  <code>eye:sparql</code> properties whose objects are resources
+  specifying SPARQL queries and problem messages.
+  </p>
+  
+  <pre>
+eye:SparqlDrivenInspector eye:sparql [...] 
+</pre>
+
+  <p>The resource may specify a SPARQL query which must succeed in
+  the model, and a message to produce if it does not.
+  </p>
+  <pre>
+eye:SparqlDrivenInspector eye:sparql 
+  [eye:require "select * where {?s ?p ?o}"; eye:message "must be non-empty"]
+</pre>
+
+  <p>If the query is non-trivial, the string may contain a
+     reference to a file containing the query, rather than the entire
+     query.
+  </p>
+
+  <pre>
+eye:require "@'/home/kers/example/query-one.sparql'"
+</pre>
+
+  <p>The quoted filename is read using the Jena file manager and
+     so respects any filename mappings. "@" characters not followed
+     by "'" are not subject to substitution, except that the 
+     sequence "@@" is replaced by "@". 
+  </p>
+
+  <p>Using
+     <code>eye:prohibit</code> rather than <code>eye:require</code>
+     means that the problem is reported if the query succeeds, rather
+     than if it fails.
+  </p>
+
+  <h3><a name='toc-53'></a>configuring renderers</h3>
+
+  <p>
+    The renderer class that Eyeball
+    uses to render the report into text is giving in the config file
+    by triples of the form:
+  </p>
+
+  <pre>
+[]
+  eye:renderer FullClassName
+  ; eye:shortName ShortClassHandler
+</pre>
+
+  <p>
+    The <code>FullClassName</code> is a string literal giving the
+    full class name of the rendering class. That class must implement
+    the <i>Renderer</i> interface and have a constructor that takes a
+    <code>Resource</code>, its configuration root, as its argument.
+  </p>
+
+  <p>The <code>ShortClassHandle</code> is a string literal giving
+  the short name used to refer to the class. The default short name
+  used is <b>default</b>. There should be no more than one
+  <i>eye:shortName</i> statement with the same ShortClassHandle in
+  the configuation file, but the same class can have many different
+  short names.</p>
+
+  <p>The <code>TextRenderer</code> supports an additional property
+  <code>eye:labels</code> to allow the appropriate labels for an
+  ontology to be supplied to the renderer. Each object of a
+  <code>eye:labels</code> statement names a model; all the
+  <code>rdfs:label</code> statements in that model are used to
+  supply strings which are used to render resources.</p>
+
+  <p>The model names are strings which are interpreted by Jena's
+  <code>FileManager</code>, so they may be redirected using Jena's
+  file mappings.</p>
+
+  <h2><a name='toc-54'></a>inside the Eyeball code</h2>
+
+  <p>Eyeball can be used from within Java code; the command line
+  merely provides a convenient external interface.</p>
+
+  <h3><a name='toc-55'></a>creating an Eyeball</h3>
+
+  <p>An Eyeball object has three subcomponents: the assumptions
+  against which the model is to be checked, the inspectors which do
+  the checking, and the renderer used to display the reports.</p>
+
+  <p>The assumptions are bundled into a single OntModel. Multiple
+  assumptions can be supplied either by adding them as sub-models
+  or by loading their content directly into the OntModel.</p>
+
+  <p>The inspectors are supplied as a single Inspector object. The
+  method <code>Inspector.Operations.create(List)</code> creates a
+  single Inspector from a list of Inspectors; this inspector
+  delegates all its inspection methods to all of its
+  sub-inspectors.</p>
+
+  <p>The renderer can be anything that implements the (simple)
+  renderer interface.</p>
+
+  <p>To create an Eyeball:</p>
+
+  <pre>Eyeball eyeball = new Eyeball( inspector, assumptions, renderer );
+</pre>
+
+  <h3><a name='toc-56'></a>to eyeball a model</h3>
+
+  <p>Models to be inspected are provided as OntModels. The problems
+  are delivered to a Report object, where they are represented as
+  an RDF model.</p>
+
+  <blockquote>
+    eyeball.inspect( report, ontModelToBeInspected )
+  </blockquote>
+
+  <p>The result is that same report object. The
+  <i>Report::model()</i> method delivers an RDF model which
+  describes the problems found by the inspection. The inspections
+  supplied in the distribution use the EYE vocabulary, and are used
+  in the standard reports:
+  </p>
+ 
+  <p>Every report item in the model is a blank node with
+  <code>rdf:type eye:Item</code>. See earlier sections for 
+  the descriptions of the properties attached to an Item.
+  </p>
+
+  <h2><a name='toc-57'></a>rebuilding Eyeball</h2>
+
+  <p>
+    The provided ant script can be used to rebuild Eyeball from
+    source:
+  </p>
+
+  <pre>
+ant clean build jar  
+</pre>
+
+  <p>(Omitting <code>clean</code> will do an incremental build, useful
+    for small changes.)
+  </p>
+
+  <p>
+   The libraries required by Eyeball are all in the <code>lib</code>
+   directory, including the necessary Jena jars.
+  </p>
+
+  <h2><a name='toc-58'></a>creating and configuring an inspector</h2>
+
+  <p>
+    To make a new inspector available to Eyeball, a new Inspector
+    class must be created and that class has to be described in
+    the Eyeball configuration.
+  </p>
+
+  <h3><a name='toc-59'></a>creating an Inspector</h3>
+
+  <p>
+    Any inspector must implement the Inspector interface,
+    which has four operations:
+  </p>
+
+  <ul>
+    <li><i>begin( Report r, OntModel assume )</i>:
+      Begin a new inspection. <code>r</code> is the <code>Report</code>
+      object which will accept the reports in this inpsection;
+      <code>assume</code> is the model containing the assumed
+      ontologies. <code>begin</code> is responsible for declaring
+      this inspectors <i>report properties</i>.
+    </li>
+    <li><i>inspectModel( Report r, OntModel m )</i>:
+      Do a whole-model inspection of <code>m</code>, issuing
+      reports to <code>r</code>. 
+    </li>
+    <li><i>inspectStatement( Report r, Statement s )</i>:
+      Inspect the single statement <code>s</code>, issuing
+      reports to <code>r</code>.
+    </li>
+    <li><i>end( Report r )</i>:
+      Do any tidying-up reports required.
+    </li>
+  </ul>
+
+  <p>
+    Typically <code>end</code> and one of <code>inspectModel</code> or
+    <code>inspectStatement</code> do nothing.
+  </p>
+
+  <p>
+    An inspector must also have a constructor that takes a <code>Resource</code>
+    argument. When Eyeball creates the Inspector object, it passes the
+    <code>Resource</code> which is the root of this inspector's
+    configuration. (This is, for example, how the SPARQL-driven inspector
+    receives the query strings to use.)
+  </p>
+
+  <p>
+    Developers may find the class <code>InpsectorBase</code> useful; it
+    has empty implementations for all the <code>Inspector</code> methods.
+    They may also find <code>InspectorTestBase</code> useful when writing
+    their inspector's tests, both for its convenience methods and because
+    it requires that their class has the appropriate constructors.
+  </p>
+
+  <h3><a name='toc-60'></a>reports and report properties</h3>
+
+  <p>
+    Eyeball reports are statements in a report model. To let the
+    renderer know which property of a report is the "main" one,
+    and which order the other properties should appear in, the
+    inspector's <code>begin</code> method should declare the
+    properties:
+  </p>
+
+  <pre>
+r.declareProperty( EYE.badDatatypeURI );
+r.declareOrder( EYE.badLanguage, EYE.onLiteral );
+</pre>
+
+  <p>
+    <code>declareProperty(P)</code> announces that <code>P</code>
+    is a report property of this inspector. <code>declareOrder(F,S)</code>
+    says that both <code>F</code> and <code>S</code> are report properties,
+    and that <code>F</code> should appear before <code>S</code> in the
+    rendered report.
+  </p>
+
+  <p>
+    Reports are made up of <i>report items</i>, which are the subjects
+    of the report properties. To create a report item, use one of
+    <code>reportItem()</code> or <code>reportItem(S)</code>. The
+    second form is appropriate when the report is attached to some
+    statement <code>S</code> of the model being inspected; a report
+    renderer will attempt to display <code>S</code>.
+  </p>
+
+  <p>
+    To add the main property to a report item <code>R</code>, use
+    <code>R.addMainProperty(P,O)</code>; to add non-main properties,
+    use <code>R.addProperty(P,O)</code>.
+  </p>
+
+  <h3><a name='toc-61'></a>configuring an inspector</h3>
+
+  <p>
+    To add an inspector to a configuration file, choose a URI for
+    it (here we're using <code>my:Fresh</code> and assuming
+    a prefix declaration for <code>my:</code>) and a short name
+    (here, "fresh") and add a description to the configuration file:
+  </p>
+
+  <pre>
+my:Fresh a eye:Inspector
+  ; eye:shortName "fresh"
+  ; rdfs:label "fresh checks for my application"
+  ; eye:className "full.path.to.Fresh"
+  .
+</pre>
+
+  <p>
+    Replace <code>full.path.to.Fresh</code> with the full classname
+    of your inspector. Now you can use <code>Fresh</code> by adding
+    <i>-include fresh</i> to the Eyeball command line (and ensuring
+    that the class is on your classpath).
+  </p>
+
+  <p>
+    If you want <code>Fresh</code> to be included by default, then
+    you must add it as an <code>eye:inspector</code> property 
+    of the configuration root, <i>eg</i>:
+  </p>
+
+  <pre>
+eye:eyeball a eye:Eyeball
+  ; eye:inspector
+    eye:PrefixInspector,    # as delivered
+    <span style='background: white'>my:FreshInspector</span>,      # new inspector
+    eye:URIInspector,       # as delivered
+    ...
+</pre>
+
+  <p>
+  </p>
+
+
+</body>
+</html>

Added: jena/Scratch/Eyeball/trunk/doc/eyeball-2.4-index.html
URL: http://svn.apache.org/viewvc/jena/Scratch/Eyeball/trunk/doc/eyeball-2.4-index.html?rev=1398843&view=auto
==============================================================================
--- jena/Scratch/Eyeball/trunk/doc/eyeball-2.4-index.html (added)
+++ jena/Scratch/Eyeball/trunk/doc/eyeball-2.4-index.html Tue Oct 16 15:20:36 2012
@@ -0,0 +1,76 @@
+<html>
+<head>
+<title>Eyeball</title>
+<link type="text/css" rel="stylesheet" href="styles/doc.css">
+</head>
+<body>
+
+<h1>Eyeball: checking RDF/OWL for common problems</h1>
+
+Eyeball is a Jena contrib for checking RDF models (including OWL) for
+common problems. It is user-extensible using plugins. The available 
+documentation for this Eyeball, E2.4, is:
+
+<ul>
+<li>This index and one-minute introduction.
+<li>The <a href="brief.html">brief guide</a>.
+<li>The <i>experimental</i> <a href="gui.html">Eyeball GUI</a>.
+<li>The full <a href="full.html">manual</a>.
+<li>The <a href="javadoc/index.html">javadoc</a>.
+</ul>
+
+You can download Eyeball from the
+<a href="http://sourceforge.net/project/showfiles.php?group_id=40417&package_id=148927">
+Eyeball package page</a>. Eyeball needs Java 5 or later to run.
+
+<h1>one-minute introduction</h1>
+
+<h2>installation</h2>
+
+<p>
+If you haven't already, download Eyeball from the
+<a href="http://sourceforge.net/project/showfiles.php?group_id=40417&package_id=148927">Eyeball package page</a>
+and unzip it into a directory of your choice.
+The download is rather large, because Eyeball 2.4 includes the Jena
+jars so that it runs stand-alone.
+
+<p>If you have Ant installed, run the Eyeball test suite:
+
+<blockquote>
+ant test 
+</blockquote>
+
+<p>
+If it doesn't say that the tests passed, let us know via the jena-dev
+mailing list <i>jena-dev@groups.yahoo.com</i> (registration required)
+and we'll see what we can do to fix the problem.
+
+<p>Ensure all the jars in the Eyeball lib directory are on your classpath.
+(You might find <a href="classpath.text">this list</a> helpful.)
+
+<h2>trying it out</h2>
+
+<p>
+Pick one of your RDF files; we'll call it FOO for now. Run the command-line
+command:
+
+<blockquote>
+java jena.eyeball -check FOO
+</blockquote>
+
+<p>
+You will likely get a whole bunch
+of messages about your RDF. The messages are supposed to be self-explanatory,
+so you may be able to go ahead and fix some problems straight away. If you 
+get a Java error about <b>NoClassDefFoundError</b>, you've forgotten to
+set the classpath up or use the <i>-cp myClassPath</i> option to Java.
+
+<p>(You may also want to try the experimental <a href="gui.html">Eyeball GUI</a>,
+but you'll still need to start it from the command line.)
+
+<p>
+If the messages aren't self-explanatory, or you want more details, 
+you'll want to move on to the <a href="brief.html">brief guide</a>.
+
+</body>
+</html>



Mime
View raw message