Diff for /bookmarktools/www/documentation.html between versions 1.25 and 1.26

version 1.25, 2009/12/19 10:50:53 version 1.26, 2010/05/01 08:39:21
Line 5 Line 5
         <head>          <head>
                 <title>Bookmark Tools</title>                  <title>Bookmark Tools</title>
                 <link rel="stylesheet" href="project.css" type="text/css" />                  <link rel="stylesheet" href="project.css" type="text/css" />
                                <link href="bookmarktoolsRSS.xml" type="application/rss+xml" rel="alternate" title="Sitewide RSS Feed" />
                <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>          </head>
         <body>          <body>
                <table style="width: 100%;">                <div id="header" style="margin: 0px;">
                        <tbody>                        <div id="header-top">
                                <tr>                                <div id="bookmarkTools-title">Bookmark Tools</div>
                                        <td>                                <div id="bookmarkTools-developer">Developer:&nbsp;<a class="simpleLinkDeveloper" href="mailto:bookmarkTools@gmx.de">Maik Gollnick</a></div>
                                                <div id="main">                        </div>
                                                        <div id="menu-container">                        <div id="header-bottom">
                                                                <a href="http://www.mozdev.org" title="mozdev.org - free project hosting for the mozilla community">                                <ul id="simple-menu">
                                                                        <img src="http://www.mozdev.org/sharedimages/mozdev_tiny.png" width="80" height="15" alt="mozdev.org" />                                        <li class="firstMenuEntry"><a href="index.html" title="Home">Home</a></li>
                                                                </a>                                        <li class="menuEntry"><a href="installation.html" title="Download">Download</a></li>
                                                                <div id="project-head">Bookmark Tools</div>                                        <li class="menuEntry"><a href="documentation.html" title="Documentation" class="current">Documentation</a></li>
                                                                <div id="project-desc">Developer <a class="simpleLink" href="mailto:maik.gollnick@gmx.de">Maik Gollnick</a></div>                                        <li class="menuEntry"><a href="source.html" title="Source Code">Source Code</a></li>
                                                                <ul id="simple-menu">                                        <li class="menuEntry"><a href="bugs.html" title="Bugs">Bugs</a></li>
                                                                        <li><a href="index.html" title="Home">Home</a></li>                                        <li class="menuEntry"><a href="screenshots.html" title="Screenshots">Screenshots</a></li>
                                                                        <li><a href="installation.html" title="Download">Download</a></li>                                </ul>
                                                                        <li><a href="documentation.html" title="Documentation" class="current">Documentation</a></li>                        </div>
                                                                        <li><a href="source.html" title="Source Code">Source Code</a></li>                </div>
                                                                        <li><a href="bugs.html" title="Bugs">Bugs</a></li>                <div id="content">
                                                                        <li><a href="screenshots.html" title="Screenshots">Screenshots</a></li>                        <h2 class="chapterTitle">Documentation</h2>
                                                                        <!--<li style="float: right;"><div style="color: black;">Hits: </div></li>-->                        <div id="content-body">
                                                                </ul>                                <span style="color: red; font-weight: bold;">This page is under construction!</span>
                                                        </div>                        </div>
                                                        <div id="menu-line"></div>                </div>
                                                                        <div id="footer">
                                                        <div id="content">                        <div style="float: left;">
                                                                                                <a href="http://validator.w3.org/check?uri=referer" class="simpleLink">
                                                                <div>                                        <img src="http://www.w3.org/Icons/valid-xhtml10-blue"
                                                                        <h3><a name="Content">Content:</a></h3>                                        alt="Valid XHTML 1.0 Strict" style="border:0;width:88px;height:31px" />
                                                                        <ul>                                </a>
                                                                                <li><strong>USER GUIDE</strong>                        </div>       
                                                                                        <ul>                        <div style="text-align: center; position: absolute; width: 100%;">
                                                                                                <li><a class="simpleLink" href="#">Searching</a></li>                                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>.
                                                                                                <li><a class="simpleLink" href="#">Indexing</a></li>                        </div>
                                                                                        </ul>                        <div style="float: right;">
                                                                                </li>                                <a href="http://jigsaw.w3.org/css-validator/check/referer" class="simpleLink">
                                                                                <li><strong>XPCOM</strong>                                        <img style="border:0;width:88px;height:31px"
                                                                                        <ul>                                        src="http://jigsaw.w3.org/css-validator/images/vcss-blue"
                                                                                                <li><a class="simpleLink" href="#HowToIndex">HowTo use the index component</a></li>                                        alt="Valid CSS!" />
                                                                                                <li><a class="simpleLink" href="#HowToTidy">HowTo use the tidy component</a></li>                                </a>
                                                                                        </ul>                        </div>       
                                                                                </li>                </div>
                                                                                <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, otherwise it was found in the browsers history. 
                                                                                </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 indexing bookmarks, but the following process 
                                                                                        helps to setup the index as fast as possible. After install you should enter 
                                                                                        the option panel under '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>          </body>
 </html>  </html>

Removed from v.1.25  
changed lines
  Added in v.1.26


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