File:  [mozdev] / bookmarktools / www / documentation.html
Revision 1.24: download - view: text, annotated - select for diffs - revision graph
Mon Dec 14 19:02:47 2009 UTC (9 years, 3 months ago) by maik
Branches: MAIN
CVS tags: HEAD
- some spelling mistakes removed
- ready for version 1.06

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
	<head>
		<title>Bookmark Tools</title>
		<link rel="stylesheet" href="project.css" type="text/css" />
		
		<meta http-equiv="Content-Type" content="text/html" />
		<meta content="text/css" http-equiv="Content-Style-Type" />
		
		<script type="text/javascript" src="scripts/shCore.js"></script>
		<script type="text/javascript" src="scripts/shBrushBash.js"></script>
		<script type="text/javascript" src="scripts/shBrushCpp.js"></script>

		<script type="text/javascript" src="scripts/shBrushCSharp.js"></script>
		<script type="text/javascript" src="scripts/shBrushCss.js"></script>
		<script type="text/javascript" src="scripts/shBrushDelphi.js"></script>
		<script type="text/javascript" src="scripts/shBrushDiff.js"></script>
		<script type="text/javascript" src="scripts/shBrushGroovy.js"></script>
		<script type="text/javascript" src="scripts/shBrushJava.js"></script>

		<script type="text/javascript" src="scripts/shBrushJScript.js"></script>
		<script type="text/javascript" src="scripts/shBrushPhp.js"></script>
		<script type="text/javascript" src="scripts/shBrushPlain.js"></script>
		<script type="text/javascript" src="scripts/shBrushPython.js"></script>
		<script type="text/javascript" src="scripts/shBrushRuby.js"></script>
		<script type="text/javascript" src="scripts/shBrushScala.js"></script>

		<script type="text/javascript" src="scripts/shBrushSql.js"></script>
		<script type="text/javascript" src="scripts/shBrushVb.js"></script>
		<script type="text/javascript" src="scripts/shBrushXml.js"></script>
		
		<link type="text/css" rel="stylesheet" href="styles/shCore.css"/>
		<link type="text/css" rel="stylesheet" href="styles/shThemeDefault.css"/>
		
		<script type="text/javascript">
			SyntaxHighlighter.config.clipboardSwf = 'scripts/clipboard.swf';
			SyntaxHighlighter.all();
		</script>
	</head>
	<body>
		<table style="width: 100%;">
			<tbody>
				<tr>
					<td>
						<div id="main">
							<div id="menu-container">
								<a href="http://www.mozdev.org" title="mozdev.org - free project hosting for the mozilla community">
									<img src="http://www.mozdev.org/sharedimages/mozdev_tiny.png" width="80" height="15" alt="mozdev.org" />
								</a>
								<div id="project-head">Bookmark Tools</div>
								<div id="project-desc">Developer <a class="simpleLink" href="mailto:maik.gollnick@gmx.de">Maik Gollnick</a></div>
								<ul id="simple-menu">
									<li><a href="index.html" title="Home">Home</a></li>
									<li><a href="installation.html" title="Download">Download</a></li>
									<li><a href="documentation.html" title="Documentation" class="current">Documentation</a></li>
									<li><a href="source.html" title="Source Code">Source Code</a></li>
									<li><a href="bugs.html" title="Bugs">Bugs</a></li>
									<li><a href="screenshots.html" title="Screenshots">Screenshots</a></li>
									<!--<li style="float: right;"><div style="color: black;">Hits: </div></li>-->
								</ul>
							</div>
							<div id="menu-line"></div>
							
							<div id="content">
								
								<div>
									<h3><a name="Content">Content:</a></h3>
									<ul>
										<li><strong>USER GUIDE</strong>
											<ul>
												<li><a class="simpleLink" href="#">Searching</a></li>
												<li><a class="simpleLink" href="#">Indexing</a></li>
											</ul>
										</li>
										<li><strong>XPCOM</strong>
											<ul>
												<li><a class="simpleLink" href="#HowToIndex">HowTo use the index component</a></li>
												<li><a class="simpleLink" href="#HowToTidy">HowTo use the tidy component</a></li>
											</ul>
										</li>
										<li><strong>OTHER</strong></li>
									</ul>
									<br />
								</div>

								<div class="separator"></div>
									
								<br />

								<h3><a href="#Content"><img src="./images/back.png" alt="back" title="back" /></a><a>User Guide: Searching</a></h3>
								<ul>
									<li>
										<h4>General</h4>
										<div>
											Not every search pattern is accepted by clucene. In case of invalid queries an
											error will be thrown. To avoid this situation the following rules should be maintained:
											<ul>
												<li>queries don't start with wildcards</li>
												<li>query length should be greater than 2</li>
												<li>only us-ascii characters (8-bit) supported</li>
											</ul>
										</div>
									</li>
									<li>
										<h4>Queries</h4>
										<div>
											The indexer is based on a c++ port of apaches lucene project. Therefore it
											supports the whole query syntax, too. Mostly following wildcards can be useful:
											
											<br /><br />
											'*': Looks for terms with 0 or more characters.
											<div class="example">
											
												<h4>Example (works):</h4>
													eigenf* or eigenf*s
												<h4>Example (don't works):</h4>
													*faces or *
											</div>
											<br />
											'?': Looks for terms that match that with the single character replaced.
											<div class="example">
												<h4>Example (works):</h4>
													eigenf?ces or eigenface?
												<h4>Example (don't works):</h4>
													?igenfaces or ?
											</div>
											The query parser includes a lot of useful wildcards to create an
											efficient search request. For more details see <a class="simpleLink" href="http://lucene.apache.org/java/2_3_2/queryparsersyntax.html">query parser</a>.
										</div>
									</li>
									<li>
										<h4>Address Bar Support</h4>
										<div>
											From version 1.05 bookmark tools supports searching via address bar. Practically, this means that
											you can enter every pattern (see section above) directly into the urlbar text field. Note, index
											results are marked with a magnifier.
										</div>
										<h4>Example</h4>
										<img src="./tutorial/tut_urlbar.png" alt="back" title="back" style="border: 1px solid black; margin-bottom: 20px;" />
									</li>
									<li style="clear: both;">
										<h4>Finding relevant results</h4>
										<div>
											Each query returns a descending sorted list of search results. The sort property <strong>score</strong> is a factor
											that describes the relevance of a clucene document. In other words, each returned bookmark is characterized
											by a value that specifies how interesting is a result related to a query. Normally this value has data type float in range of
											[0..1] but the extension displays a score with 0 to 100 as integer. Therefore a number like e.g. 0.0012312 results
											in a score value 0 and isn't shown.
											<br /><br />
											Note, the urlbar hides every score value by default.
										</div>									
									</li>
									<li style="clear: both;">
										<h4>Sidebar features</h4>
										<div>
											The extended sidebar helps you to find bookmarks in your folder tree. If a search result is selected it is
											displayed in the book tab below. Remember, in case of duplicates the first entry, that equals the selected
											bookmark, will be shown.
										</div>									
									</li>
								</ul>
								
								<br />
								<br />
								<!--
								<h3><a href="#Content"><img src="./images/back.png" alt="back" title="back" /></a><a name="">User Guide: Indexing</a></h3>
								<ul>
									<li>
										<h4>Best Practice</h4>
										<div>
											It doesnt matter in which way you index bookmarks, but the following process
											helps to setup the index as fast as possible. After install you should enter
											the option panel under 'Extras/BookmarkTools/Configure..' and activate 'manual'
											as build type. Now switch to the manage panel and push build to start indexing. 
											After this the list labeled with 'Index' should display all successfully indexed 
											bookmarks. Now return to the option panel and set build type 'automatically' to
											force an index update every week(default).
											<br /><br />
											Note, restarting firefox is required.
										</div>
									</li>
									<li>
										<h4>Update Index Data</h4>
										<div>
											
										</div>
									</li>
									<li>
										<h4>Which kind of bookmarks are added to the index?</h4>
										<div>
											
										</div>
									</li>
								</ul>-->
								
								
								
								<br style="clear: both; margin-top: 10px;" />
								<div class="separator"></div>
								<br />
								
								<h3><a href="#Content"><img src="./images/back.png" alt="back" title="back" /></a><a name="HowToIndex">HowTo use the index component (uses clucene-core-0.9.20)</a></h3>
								<h4>Writing::</h4>
								<pre class="brush: js font-size: 80%">

									//initialize file object (location: profile directory)
									var file = Components.classes["@mozilla.org/file/directory_service;1"]
												.getService(Components.interfaces.nsIProperties)
												.get("ProfD", Components.interfaces.nsIFile);

									file.append("index"); //folder named 'index'
									
									if(!file.exists() || !file.isDirectory()) 
										file.create(Components.interfaces.nsIFile.DIRECTORY_TYPE, 0777);

									//initialize xpcom
									var writer = Components.classes["@bookmarktools.mozdev.org/search/indexWriter;1"].createInstance();
									writer = writer.QueryInterface(Components.interfaces.ICLWriter);
									
									//set path
									writer.setPath(file.path);
									
									//create index document
									var cl_document = new Object();
									cl_document.primaryKey = "key0";						//this shoud be a unique key
									cl_document.name = "first document";					//document name
									cl_document.content = "Hello World!";					//some content
									
									//append document
									writer.appendDocument(
										cl_document.primaryKey,
										cl_document.name,
										cl_document.content
									);
									
									//optimize data
									writer.optimize();
									
								</pre>

								<h4>Searching::</h4>
								<pre class="brush: js font-size: 80%">

									//initialize xpcom
									var reader = Components.classes["@bookmarktools.mozdev.org/search/indexReader;1"].createInstance();
									reader = reader.QueryInterface(Components.interfaces.ICLReader);
									
									//set path
									reader.setPath(file.path); //see section 'Writing'
									
									if(reader.exists()){ //check for index data
										
										var query = "Hell*";
										var results = Components.classes["@mozilla.org/array;1"]
														.createInstance(Components.interfaces.nsIMutableArray);
										reader.search(query, results);
										
										var e = results.enumerate();
										while (e.hasMoreElements()) {
											var resultNode = e.getNext().QueryInterface(Components.interfaces.IResultNode);
											
											//Object: resultNode
											//-> resultNode.primaryKey
											//-> resultNode.score
											alert(resultNode.primaryKey + "\n" + resultNode.score);
										}
										
									}else {
										//display message or do nothing
									}
									
								</pre>

								<h4>Lookup::</h4>
								<pre class="brush: js font-size: 80%">

									//initialize xpcom
									var reader = Components.classes["@bookmarktools.mozdev.org/search/indexReader;1"].createInstance();
									reader = reader.QueryInterface(Components.interfaces.ICLReader);
									
									//set path
									reader.setPath(file.path); //see section 'Writing'
									
									var results = Components.classes["@mozilla.org/array;1"]
													.createInstance(Components.interfaces.nsIMutableArray);
									reader.lookup(results);
									
									var e = results.enumerate();
									while (e.hasMoreElements()) {
										var lookupNode = e.getNext().QueryInterface(Components.interfaces.ILookupNode);
										
										//Object: lookupNode
										//-> lookupNode.primaryKey
										//-> lookupNode.name
										alert(lookupNode.primaryKey + "\n" + lookupNode.name);
									}

								</pre>

								<h4>Delete documents::</h4>
								<pre class="brush: js font-size: 80%">

									//initialize xpcom
									var writer = Components.classes["@bookmarktools.mozdev.org/search/indexWriter;1"].createInstance();
									writer = writer.QueryInterface(Components.interfaces.ICLWriter);
									
									//set path
									writer.setPath(file.path); //see section 'Writing'
									
									//delete documents with index 0, 5 and 2
									var docs = [0, 5, 2];
									writer.deleteDocument(docs, docs.length);

								</pre>

								<br />

								<div class="separator"></div>
								
								<h3><a href="#Content"><img src="./images/back.png" alt="back" title="back" /></a><a name="HowToTidy">HowTo use the tidy component (uses ctidy version 060405)</a></h3>
								<h4>Cleanup::</h4>
								<pre class="brush: js font-size: 80%">

									//initialize xpcom
									var tidy = Components.classes["@bookmarktools.mozdev.org/repair/tidy;1"].createInstance();
									tidy = tidy.QueryInterface(Components.interfaces.ITidy);
									
									var src = "
									&lt;html&gt;
										&lt;head&gt;&lt;/head&gt;
										&lt;body
											broken body tag &amp; no entity
										&lt;/body&gt;
									&lt;/html>";
									
									//result contains the repaired html/xhtml/xml source
									//otherwise a error message returned
									var result = tidy.cleanup(src);
									
									if(result == "Tidy: no output"){
										alert("error returned");
									}else {
										alert(result);
									}
									
								</pre>
						
							</div>
						</div>
					</td>
				</tr>
				<tr>
					<td>
						<div id="footer">
							<table>
								<tr>
									<td>
										<a href="http://validator.w3.org/check?uri=referer">
											<img src="http://www.w3.org/Icons/valid-xhtml10-blue"
											alt="Valid XHTML 1.0 Strict" height="31" width="88" />
										</a>
									</td>
									<td style="width: 100%;">
										<div style="text-align: center;">
											Project hosted on <a class="simpleLink" href="http://www.mozdev.org/">mozdev.org</a>.<br/> <a class="simpleLink" href="http://www.mozdev.org/copyright.html">Copyright</a> &copy; 2004. All rights reserved. <a class="simpleLink" href="http://www.mozdev.org/community/terms.html">Terms of Use</a>.
										</div>
									</td>
									<td>
										<a href="http://jigsaw.w3.org/css-validator/check/referer">
											<img style="border:0;width:88px;height:31px"
											src="http://jigsaw.w3.org/css-validator/images/vcss-blue"
											alt="Valid CSS!" />
										</a>
									</td>
								</tr>
							</table>
						</div>
					</td>
				</tr>
			</tbody>
		</table>
	</body>
</html>

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>