FAQ

Frequently Asked Questions

Q: How do I change the location of the ‘data’ directory?

There are two ways to do this. The first is only applicable to UNIX systems (MacOS, Linux, Solaris, etc.) and that is to make a symbolic link from $XTF_HOME/data to your data directory, e.g. with this command: ln -s your-data-dir $XTF_HOME/data

The second method works on all operating systems but is more involved.

  1. Edit conf/textIndexer.conf and change “./data” to your data directory.
  2. Run a clean re-index, e.g. bin/textIndexer -clean -index default.
  3. Edit style/dynaXML/docReqParser.xsl and change all lines that contain “data/” to point to your data directory instead. Be sure to include “/” at the end of your directory name.
  4. If you find that images aren’t appearing, you may need to fix the $doc.path variable in style/dynaXML/docFormatter/docFormatterCommon.xsl. The value needs to be a URL (relative or absolute) that browsers can use to reach the data directory for a given object.

Q: How do I add a metadata field?

In brief:

  1. Add a template to your index prefilter(s). This new template should match on the desired elements in your source document and mark them with an xtf:meta attribute.
  2. Add a template to your result formatter (e.g. style/crossQuery/resultFormatter/default/resultFormatter.xsl). This new template should match on your new field in the docHit metadata and produce whatever HTML you like.
  3. If you want the user to be able to search on the new field, add a template to style/crossQuery/resultFormatter/default/search.xsl that produces an HTML text input box.
  4. If you want to be able to use faceted browsing on the new field, see the exercise “Create a hierarchical facet” under Getting Started.

For detailed coverage see “Adding or Marking Metadata” in the textIndexer section of the XTF Programming Guide.

Q: How do I keep multiple distinct collections of material in a single XTF index?

  1. Add a metadata field that distinguishes each document as being part of one collection vs. another. You could do this based on details within the document itself, or its filesystem path, etc.
  2. Give the user a way to select a collection. This could be radio buttons on the search form (style/crossQuery/resultFormatter/default/search.xsl), or a special URL parameter of your choice, or some other special form of URL. Just adding it to the search form may be enough; if not modify the query parser (e.g. style/crossQuery/queryParser/default/queryParser.xsl) to output a query term for your new collection field.

Q: How do I upgrade XTF while keeping my local changes?

This depends on your particular level of customization. In all cases, make a backup of your existing XTF directory before upgrading.

If you have only modified stylesheets and conf files and do not want them to change, simply grab the xtf-core-X.Y.zip (where X.Y is the new version number) and unzip it into your XTF directory. Then run a clean re-index and go.

If you have modified stylesheets/conf files and you do want to incorporate fixes and changes to those files in addition to the XTF core:

  1. Get the current XTF Mercurial repository: hg clone http://xtf.hg.sourceforge.net:8000/hgroot/xtf/xtf
  2. Update the working directory to match the version you originally started with: hg update xtf-Y.Z (where Y.Z is your starting XTF version number)
  3. Create a branch to track your local changes: hg branch your-branch-name
  4. Copy your changed files over the ones in the working directory
  5. Commit the changes made on your branch: hg commit
  6. Merge all changes made between the old XTF release and the new one: hg merge xtf-Y.Z (where Y.Z is the newly released version), or if you want the very latest unreleased changes: hg merge default
  7. If there are any merge conflicts (i.e. changes to the same part of a file by both you and the XTF developers), resolve them manually and then mark the resulting files as resolved: hg resolve -ma
  8. Commit your upgraded branch: hg commit
  9. For future upgrades, you can simply do an “hg pull” to get the latest changes and then start at step 5.

Q: How do I use the new “sub-document” indexing feature, since it’s not documented yet?

At index time put xtf:subDocument=”mySubDocName” attributes on nodes using your prefilter. The indexer will recognize these and make separate searchable groupings in the Lucene index. Each sub-document inherits meta-data from its parent document. It may also specify its own additional meta-data in the usual way (using xtf:meta attributes).

In crossQuery, your results will have a separate <docHit> element for each sub-document matched, and XTF will add a subDocument attribute to the <docHit> telling you sub-doc was hit.

In dynaXML, XTF will add a subDocument attribute to the top-level <xtf:snippet> elements as well.

To restrict full-text search to a particular sub-document only, there is a new query element called <subDocument> with the same syntax and usage as the existing <sectionType> element (i.e. it can only appear within a query on the ‘text’ field). This should be particularly useful in dynaXML when jumping from a crossQuery hit by rank number, as without this the number wouldn’t match up.

Caveat: It is possible to create multiple sub-documents of the same name. It is also possible to have text outside of a sub-document. In these cases, each contiguous section will be a separate search unit, which might not be what the end-user expects. Unless you really want this behavior, care should be taken to put all text with sub-documents and give each sub-document a unique name.