|
|
NeoLight
From NeoWiki
| Revision as of 06:31, 29 April 2005 (edit) Waldo ( | contribs) m (link to spotlight at apple) ← Previous diff |
Revision as of 06:32, 29 April 2005 (edit) (undo) Waldo ( | contribs) (mild grammar changes) Next diff → |
||
| Line 16: | Line 16: | ||
| ==Licensing== | ==Licensing== | ||
| - | NeoLight is being released under the GNU Lesser General Public License. While I would have preferred to use a GPL style license like the main NeoOffice project, LGPL is necessary in this case as the Spotlight importers are shared libraries loaded into closed source applications. Using LGPL allows for the executable code of NeoLight to be used by Spotlight without "infecting" Mac OS X with GPL requirements. | + | NeoLight is being released under the GNU Lesser General Public License. While I would have preferred to use a GPL-style license like the main NeoOffice project, LGPL is necessary in this case as the Spotlight importers are shared libraries loaded into closed-source applications. Using LGPL allows for the executable code of NeoLight to be used by Spotlight without "infecting" Mac OS X with GPL requirements. |
| ==Installation Requirements== | ==Installation Requirements== | ||
Revision as of 06:32, 29 April 2005
Contents |
NeoLight
Edward Peterlin 4/29/05
What is NeoLight?
NeoLight is an abbreviation I've come up with for "NeoOffice Spotlight Importer". This importer allows Spotlight to index metadata and content within the files created by NeoOffice. Through Spotlight integration, searching across multiple NeoOffice documents can be done in a nice, Mac-like fashion.
Today is the first development release of the NeoLight plugin. This release aims to be the start of an addition that will be included with future builds of NeoOffice/J. The purposes of this release are:
- Allow testers who have Tiger to begin assessing the utility of the plugin.
- Allow developers access to the source code to bugfix and improve the plugin.
- Research what other types of metadata may wish to be extracted from documents.
- Get people excited enough to help add support for OpenDocument formatted documents.
Licensing
NeoLight is being released under the GNU Lesser General Public License. While I would have preferred to use a GPL-style license like the main NeoOffice project, LGPL is necessary in this case as the Spotlight importers are shared libraries loaded into closed-source applications. Using LGPL allows for the executable code of NeoLight to be used by Spotlight without "infecting" Mac OS X with GPL requirements.
Installation Requirements
- Mac OS X 10.4 "Tiger"
- NeoOffice/J (or OpenOffice.org X11...see below)
- patience
Downloading
The NeoLight plugin can be downloaded as a single installer package:
http://trinity.neooffice.org/downloads/neolight_installer.pkg.tgz
- 43K in size
- MD5 sum : 8436e94ca1e6956a3277db0cf12e2f33
A reference Info.plist is also provided:
http://trinity.neooffice.org/downloads/neolight_neoj_Info.plist.gz
- < 1K in size
- MD5 sum : 0fc545f35af027424d7fc8f6ea41eaa0
Installing
In order to install the NeoLight plugin, you will be required to edit the Info.plist of NeoOffice/J. The changes required for Spotlight support will be integrated into future patch and/or final releases of NeoOffice/J once these plist additions have been verified to not cause harm on systems older then 10.4.
You should edit the Info.plist before attempting to index documents with Spotlight.
Editing the Info.plist
Throughout its system, Spotlight identifies files by UTI types. Because Mac OS X does not have built-in types for OpenOffice.org formatted files, they must be defined by an installed application to avoid having Spotlight assign them dynamically generated UTI types (which cannot reliably be mapped to a Spotlight importer).
NeoLight assigns the following UTI types to files:
- org.neooffice.writer - Writer "sxw" files
- org.neooffice.calc - Calc "sxc" files
- org.neooffice.impress - Impress "sxi" files
- org.neooffice.draw - Draw "sxd" files
In order to define these types, the NeoOffice/J Info.plist must have a "UTExportedTypeDeclarations" dictionary added to its root. The "neolight_neoj_Info.plist.gz" file link above includes a 1.1 Release Candidate Info.plist file with these changes already applied. To install it, copy that Info.plist over the appropriate file within the NeoOfficeJ application bundle.
After you either copy over the Info.plist or do the edits manually, you should rebuild your LaunchServices database to make sure the UTI types take.
It is also possible to perform these edits manually using the Property List Editor (or your favorite text editor). The contents of the appropriate dictionary to add are:
<key>UTExportedTypeDeclarations</key> <array> <dict> <key>UTTypeConformsTo</key> <array> <string>public.content</string> <string>public.data</string> </array> <key>UTTypeDescription</key> <string>NeoOffice/J Draw</string> <key>UTTypeIdentifier</key> <string>org.neooffice.draw</string> <key>UTTypeReferenceURL</key> <string>http://xml.openoffice.org/xml_specification.pdf</string> <key>UTTypeTagSpecification</key> <dict> <key>public.filename-extension</key> <array> <string>sxd</string> </array> <key>public.mime-type</key> <string>application/vnd.sun.xml.draw</string> </dict> </dict> <dict> <key>UTTypeConformsTo</key> <array> <string>public.content</string> <string>public.data</string> </array> <key>UTTypeDescription</key> <string>NeoOffice/J Impress</string> <key>UTTypeIdentifier</key> <string>org.neooffice.impress</string> <key>UTTypeReferenceURL</key> <string>http://xml.openoffice.org/xml_specification.pdf</string> <key>UTTypeTagSpecification</key> <dict> <key>public.filename-extension</key> <array> <string>sxi</string> </array> <key>public.mime-type</key> <string>application/vnd.sun.xml.impress</string> </dict> </dict> <dict> <key>UTTypeConformsTo</key> <array> <string>public.content</string> <string>public.data</string> </array> <key>UTTypeDescription</key> <string>NeoOffice/J Calc</string> <key>UTTypeIdentifier</key> <string>org.neooffice.calc</string> <key>UTTypeReferenceURL</key> <string>http://xml.openoffice.org/xml_specification.pdf</string> <key>UTTypeTagSpecification</key> <dict> <key>public.filename-extension</key> <array> <string>sxc</string> </array> <key>public.mime-type</key> <string>application/vnd.sun.xml.calc</string> </dict> </dict> <dict> <key>UTTypeConformsTo</key> <array> <string>public.content</string> <string>public.data</string> </array> <key>UTTypeDescription</key> <string>NeoOffice/J Writer</string> <key>UTTypeIdentifier</key> <string>org.neooffice.writer</string> <key>UTTypeReferenceURL</key> <string>http://xml.openoffice.org/xml_specification.pdf</string> <key>UTTypeTagSpecification</key> <dict> <key>public.filename-extension</key> <array> <string>sxw</string> </array> <key>public.mime-type</key> <string>application/vnd.sun.xml.writer</string> </dict> </dict> </array>
Installing the NeoLight Plugin
To install the NeoLight Importer Plugin, simply extract and double-click the neolight_installer.pkg.tgz linked to above. After clicking through the requisite license agreements, it will install the neolight plugin named "neolight.mdimporter" within the "/Library/MDImporters" directory. This will make the NeoLight importer available for all users on the machine.
Testing Your Installation
If you have the Tiger Developer's Tools installed, you can verify proper loading of the plugin from a Terminal after installation using the following command:
/Developer/Tools/mdimport -L
You should see "/Library/MDImporters/neolight.mdimporter" in the list if all has been installed well.
To test whether installation was successful:
- Launch NeoOffice/J
- Create a new empty Writer document.
- Go to File > Properties.
- Add in a "Title" for the document with a relatively unused nonsense word (e.g. "interzone")
- Notice that the title from the properties dialog goes into the document's titlebar.
- Save the doc to a known location with a filename that does not contain your nonsense word.
- Start a new Spotlight search.
- Type the nonsense word you used above.
If the neolight plugin is installed properly, the doc you just saved should show up in the search results. If it doesn't, open a Terminal and type the followng:
/Developer/Tools/mdimport -d3 /path/to/test/doc.sxw
Check to make sure the doc is of type "org.neooffice.writer". If it is, look in the keys for the "Title" key and you should see your nonsense word. If you do, then everything is installed correctly.
If when you type the above the doc is of type "dyn.a3f42morehexgarbageinherefoo" then LaunchServices hasn't mapped the extension to the UTI type. Either the update to the Info.plist is misapplied or you may need to rebuild your LaunchServices database.
What does NeoLight Import?
NeoLight currently handles all four types of major OOo/NeoOffice documents in a single plugin. It will extract the following:
- standard OOo metadata (generally accessible and editable through File > Properties)
- title
- author/last edited
- keywords
- description
- comments
- text content from Writer documents for indexing
- textual display content of all cells of a Calc document for indexing
- content of bullets, titles, and other text areas for indexing from Impress and Draw documents.
Once the NeoLight plugin is installed, it should be possible to search OOo formatted documents by these criteria within Spotlight enabled applications.
Using NeoLight to Index OpenOffice.org Documents
NeoLight is not specific to NeoOffice and can index any OpenOffice.org 1.x formatted document. To enable indexing of OpenOffice.org documents if you do not use NeoOffice/J, some application will need to have its Info.plist edited to provide the UTI types listed above. If you use OpenOffice.org Mac OS X (X11), you may want to consider assigning this to the Start OpenOffice.org application Info.plist file (or the Info.plist of whatever launcher you are using).
Known Issues
- This is completely untested and unreviewed! Prior to the release of Mac OS X 10.4, it was not possible to release source code publicly due to Apple NDA requirements.
- The UTI types are required to be defined before files are manually indexed using mdimport -d3. Files that get forcefully indexed prior to the UTI types being defined will get the wrong UTI type in the Spotlight metadata database. Although the type tree gets updated to reflect the proper mapping to the org.neooffice types, the raw type remains fixed to the dynamically generated dyn UTI type and the file cannot be indexed. Workaround is to copy the file to a new file and re-index again.
- I have been unable to verify if the text content provided in the kMDItemTextContent key is in fact getting indexed. This key does not show up in the list for mdimport -d3 or -d4. I am unsure if this is a limitation of the build of Tiger on which NeoLight was developed and tested (WWDC 2004).
- Content is being extracted in UTF-8 encoding, where possible. I am unsure if OOo 1.x files can go Unicode and if I need to handle that differently.
Getting the Source Code
The source code is in the NeoOffice CVS repository. To checkout the source code do the following:
csh setenv CVSROOT :pserver:anoncvs@anoncvs.neooffice.org:/cvs cvs login
use anoncvs as the cvs password
cvs co neolight
This will checkout the neolight module that has the source code for the plugin. Simply open the neolight.xcode project in Xcode and away you go!
Source Code Structure
In general, the source code is split up into the following files:
- common - These contain utility code used across all the file types and common metadata extraction (all the OpenOffice.org file types have the same meta.xml format)
- writer - Contains functions for SXW file parsing.
- calc - Contains functions for SXC file parsing.
- impress - Contains functions for SXI file parsing (and SXD)
- main - CFPlugin foundational code and dispatch of metadata extraction to appropriate handler based on UTI type
All of the functions are commented with Doc++/JavaDoc style comments, so you should be able to run a documentation generator on the code to browse through it.
While all of the files are technically Objective-C++, no Cocoa is used in the plugin. It is all CoreFoundation based and I'm essentially using the language as a "better C". Since plugins are supposed to be lightweight, it simply made more sense to re-use the CoreFoundation utilities then to make any grand scheme.
Issues and Feedback
Please note any issues here or in the NeoLight Development forum on http://trinity.neooffice.org
