Annotation of bookmarktools/www/documentation.html, revision 1.23

1.18      maik        1: <?xml version="1.0" encoding="UTF-8"?>
                      2: <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
                      3: 
                      4: <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
1.16      maik        5:        <head>
1.19      maik        6:                <title>Bookmark Tools</title>
1.18      maik        7:                <link rel="stylesheet" href="project.css" type="text/css" />
1.16      maik        8:                
1.18      maik        9:                <meta http-equiv="Content-Type" content="text/html" />
1.16      maik       10:                <meta content="text/css" http-equiv="Content-Style-Type" />
                     11:                
                     12:                <script type="text/javascript" src="scripts/shCore.js"></script>
                     13:                <script type="text/javascript" src="scripts/shBrushBash.js"></script>
                     14:                <script type="text/javascript" src="scripts/shBrushCpp.js"></script>
                     15: 
                     16:                <script type="text/javascript" src="scripts/shBrushCSharp.js"></script>
                     17:                <script type="text/javascript" src="scripts/shBrushCss.js"></script>
                     18:                <script type="text/javascript" src="scripts/shBrushDelphi.js"></script>
                     19:                <script type="text/javascript" src="scripts/shBrushDiff.js"></script>
                     20:                <script type="text/javascript" src="scripts/shBrushGroovy.js"></script>
                     21:                <script type="text/javascript" src="scripts/shBrushJava.js"></script>
                     22: 
                     23:                <script type="text/javascript" src="scripts/shBrushJScript.js"></script>
                     24:                <script type="text/javascript" src="scripts/shBrushPhp.js"></script>
                     25:                <script type="text/javascript" src="scripts/shBrushPlain.js"></script>
                     26:                <script type="text/javascript" src="scripts/shBrushPython.js"></script>
                     27:                <script type="text/javascript" src="scripts/shBrushRuby.js"></script>
                     28:                <script type="text/javascript" src="scripts/shBrushScala.js"></script>
                     29: 
                     30:                <script type="text/javascript" src="scripts/shBrushSql.js"></script>
                     31:                <script type="text/javascript" src="scripts/shBrushVb.js"></script>
                     32:                <script type="text/javascript" src="scripts/shBrushXml.js"></script>
                     33:                
                     34:                <link type="text/css" rel="stylesheet" href="styles/shCore.css"/>
                     35:                <link type="text/css" rel="stylesheet" href="styles/shThemeDefault.css"/>
                     36:                
                     37:                <script type="text/javascript">
                     38:                        SyntaxHighlighter.config.clipboardSwf = 'scripts/clipboard.swf';
                     39:                        SyntaxHighlighter.all();
                     40:                </script>
                     41:        </head>
                     42:        <body>
1.18      maik       43:                <table style="width: 100%;">
                     44:                        <tbody>
                     45:                                <tr>
                     46:                                        <td>
                     47:                                                <div id="main">
                     48:                                                        <div id="menu-container">
                     49:                                                                <a href="http://www.mozdev.org" title="mozdev.org - free project hosting for the mozilla community">
                     50:                                                                        <img src="http://www.mozdev.org/sharedimages/mozdev_tiny.png" width="80" height="15" alt="mozdev.org" />
                     51:                                                                </a>
                     52:                                                                <div id="project-head">Bookmark Tools</div>
                     53:                                                                <div id="project-desc">Developer <a class="simpleLink" href="mailto:maik.gollnick@gmx.de">Maik Gollnick</a></div>
                     54:                                                                <ul id="simple-menu">
                     55:                                                                        <li><a href="index.html" title="Home">Home</a></li>
                     56:                                                                        <li><a href="installation.html" title="Download">Download</a></li>
                     57:                                                                        <li><a href="documentation.html" title="Documentation" class="current">Documentation</a></li>
                     58:                                                                        <li><a href="source.html" title="Source Code">Source Code</a></li>
                     59:                                                                        <li><a href="bugs.html" title="Bugs">Bugs</a></li>
                     60:                                                                        <li><a href="screenshots.html" title="Screenshots">Screenshots</a></li>
1.21      maik       61:                                                                        <!--<li style="float: right;"><div style="color: black;">Hits: </div></li>-->
1.18      maik       62:                                                                </ul>
                     63:                                                        </div>
                     64:                                                        <div id="menu-line"></div>
1.16      maik       65:                                                        
1.18      maik       66:                                                        <div id="content">
                     67:                                                                
                     68:                                                                <div>
                     69:                                                                        <h3><a name="Content">Content:</a></h3>
                     70:                                                                        <ul>
1.23    ! maik       71:                                                                                <li><strong>USER GUIDE</strong>
        !            72:                                                                                        <ul>
        !            73:                                                                                                <li><a class="simpleLink" href="#">Searching</a></li>
        !            74:                                                                                                <li><a class="simpleLink" href="#">Indexing</a></li>
        !            75:                                                                                        </ul>
        !            76:                                                                                </li>
1.18      maik       77:                                                                                <li><strong>XPCOM</strong>
                     78:                                                                                        <ul>
1.19      maik       79:                                                                                                <li><a class="simpleLink" href="#HowToIndex">HowTo use the index component</a></li>
                     80:                                                                                                <li><a class="simpleLink" href="#HowToTidy">HowTo use the tidy component</a></li>
1.18      maik       81:                                                                                        </ul>
                     82:                                                                                </li>
                     83:                                                                                <li><strong>OTHER</strong></li>
                     84:                                                                        </ul>
                     85:                                                                        <br />
                     86:                                                                </div>
                     87: 
                     88:                                                                <div class="separator"></div>
                     89:                                                                        
1.19      maik       90:                                                                <br />
1.18      maik       91: 
1.23    ! maik       92:                                                                <h3><a href="#Content"><img src="./images/back.png" alt="back" title="back" /></a><a>User Guide: Searching</a></h3>
        !            93:                                                                <ul>
        !            94:                                                                        <li>
        !            95:                                                                                <h4>General</h4>
        !            96:                                                                                <div>
        !            97:                                                                                        Not every search pattern is accepted by clucene. In case of invalid queries an
        !            98:                                                                                        error will be thrown. To avoid this situation the following rules should be maintained:
        !            99:                                                                                        <ul>
        !           100:                                                                                                <li>queries don't starts with wildcards</li>
        !           101:                                                                                                <li>query length should be greater then 2</li>
        !           102:                                                                                                <li>only us-ascii characters (8-bit) supported</li>
        !           103:                                                                                        </ul>
        !           104:                                                                                </div>
        !           105:                                                                        </li>
        !           106:                                                                        <li>
        !           107:                                                                                <h4>Queries</h4>
        !           108:                                                                                <div>
        !           109:                                                                                        The indexer is based on the c++ port of apaches lucene project. Therefore it
        !           110:                                                                                        supports the whole query syntax, too. Mostly following wildcards are useful:
        !           111:                                                                                        
        !           112:                                                                                        <br /><br />
        !           113:                                                                                        '*': Looks for terms with 0 or more characters.
        !           114:                                                                                        <div class="example">
        !           115:                                                                                        
        !           116:                                                                                                <h4>Example (works):</h4>
        !           117:                                                                                                        eigenf* or eigenf*s
        !           118:                                                                                                <h4>Example (don't works):</h4>
        !           119:                                                                                                        *faces or *
        !           120:                                                                                        </div>
        !           121:                                                                                        <br />
        !           122:                                                                                        '?': Looks for terms that match that with the single character replaced.
        !           123:                                                                                        <div class="example">
        !           124:                                                                                                <h4>Example (works):</h4>
        !           125:                                                                                                        eigenf?ces or eigenface?
        !           126:                                                                                                <h4>Example (don't works):</h4>
        !           127:                                                                                                        ?igenfaces or ?
        !           128:                                                                                        </div>
        !           129:                                                                                        The query parser includes a lot of useful wildcards to create a
        !           130:                                                                                        efficient search request. For more details see <a class="simpleLink" href="http://lucene.apache.org/java/2_3_2/queryparsersyntax.html">query parser</a>.
        !           131:                                                                                </div>
        !           132:                                                                        </li>
        !           133:                                                                        <li>
        !           134:                                                                                <h4>Address Bar Support</h4>
        !           135:                                                                                <div>
        !           136:                                                                                        From version 1.05 bookmark tools supports searching via address bar. Practically, this means that
        !           137:                                                                                        you can enter every pattern (see section above) directly into the urlbar text field. Note, index
        !           138:                                                                                        results are marked with a magnifier.
        !           139:                                                                                </div>
        !           140:                                                                                <h4>Example</h4>
        !           141:                                                                                <img src="./tutorial/tut_urlbar.png" alt="back" title="back" style="border: 1px solid black; margin-bottom: 20px;" />
        !           142:                                                                        </li>
        !           143:                                                                        <li style="clear: both;">
        !           144:                                                                                <h4>Finding relevant results</h4>
        !           145:                                                                                <div>
        !           146:                                                                                        Each query returns a descending sorted list of search results. The sort property <strong>score</strong> is a factor
        !           147:                                                                                        that describes the relevance of a clucene document. In other words, each returned bookmark is characterized
        !           148:                                                                                        by a value that specifies how interesting is a result related to a query. Normally this value has data type float in range of
        !           149:                                                                                        [0..1] but the extension displays a score with 0 to 100 as integer. Therefore a number like e.g. 0.0012312 results
        !           150:                                                                                        in a score value 0 and isn't shown.
        !           151:                                                                                        <br /><br />
        !           152:                                                                                        Note, the urlbar hides every score value by default.
        !           153:                                                                                </div>                                                                  
        !           154:                                                                        </li>
        !           155:                                                                        <li style="clear: both;">
        !           156:                                                                                <h4>Sidebar features</h4>
        !           157:                                                                                <div>
        !           158:                                                                                        The extended sidebar helps you to find bookmarks in your folder tree. If a search result is selected it is
        !           159:                                                                                        displayed in the book tab below. Remember, in case of duplicates the first entry, that equals the selected
        !           160:                                                                                        bookmark, will be shown.
        !           161:                                                                                </div>                                                                  
        !           162:                                                                        </li>
        !           163:                                                                </ul>
        !           164:                                                                
        !           165:                                                                <br />
        !           166:                                                                <br />
        !           167:                                                                <!--
        !           168:                                                                <h3><a href="#Content"><img src="./images/back.png" alt="back" title="back" /></a><a name="">User Guide: Indexing</a></h3>
        !           169:                                                                <ul>
        !           170:                                                                        <li>
        !           171:                                                                                <h4>Best Practice</h4>
        !           172:                                                                                <div>
        !           173:                                                                                        It doesnt matter in which way you index bookmarks, but the following process
        !           174:                                                                                        helps to setup the index as fast as possible. After install you should enter
        !           175:                                                                                        the option panel under 'Extras/BookmarkTools/Configure..' and activate 'manual'
        !           176:                                                                                        as build type. Now switch to the manage panel and push build to start indexing. 
        !           177:                                                                                        After this the list labeled with 'Index' should display all successfully indexed 
        !           178:                                                                                        bookmarks. Now return to the option panel and set build type 'automatically' to
        !           179:                                                                                        force an index update every week(default).
        !           180:                                                                                        <br /><br />
        !           181:                                                                                        Note, restarting firefox is required.
        !           182:                                                                                </div>
        !           183:                                                                        </li>
        !           184:                                                                        <li>
        !           185:                                                                                <h4>Update Index Data</h4>
        !           186:                                                                                <div>
        !           187:                                                                                        
        !           188:                                                                                </div>
        !           189:                                                                        </li>
        !           190:                                                                        <li>
        !           191:                                                                                <h4>Which kind of bookmarks are added to the index?</h4>
        !           192:                                                                                <div>
        !           193:                                                                                        
        !           194:                                                                                </div>
        !           195:                                                                        </li>
        !           196:                                                                </ul>-->
        !           197:                                                                
        !           198:                                                                
        !           199:                                                                
        !           200:                                                                <br style="clear: both; margin-top: 10px;" />
        !           201:                                                                <div class="separator"></div>
        !           202:                                                                <br />
        !           203:                                                                
1.19      maik      204:                                                                <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>
                    205:                                                                <h4>Writing::</h4>
                    206:                                                                <pre class="brush: js font-size: 80%">
                    207: 
                    208:                                                                        //initialize file object (location: profile directory)
                    209:                                                                        var file = Components.classes["@mozilla.org/file/directory_service;1"]
                    210:                                                                                                .getService(Components.interfaces.nsIProperties)
                    211:                                                                                                .get("ProfD", Components.interfaces.nsIFile);
1.18      maik      212: 
1.19      maik      213:                                                                        file.append("index"); //folder named 'index'
                    214:                                                                        
                    215:                                                                        if(!file.exists() || !file.isDirectory()) 
                    216:                                                                                file.create(Components.interfaces.nsIFile.DIRECTORY_TYPE, 0777);
1.18      maik      217: 
1.19      maik      218:                                                                        //initialize xpcom
                    219:                                                                        var writer = Components.classes["@bookmarktools.mozdev.org/search/indexWriter;1"].createInstance();
                    220:                                                                        writer = writer.QueryInterface(Components.interfaces.ICLWriter);
                    221:                                                                        
                    222:                                                                        //set path
                    223:                                                                        writer.setPath(file.path);
                    224:                                                                        
                    225:                                                                        //create index document
                    226:                                                                        var cl_document = new Object();
                    227:                                                                        cl_document.primaryKey = "key0";                                                //this shoud be a unique key
                    228:                                                                        cl_document.name = "first document";                                    //document name
                    229:                                                                        cl_document.content = "Hello World!";                                   //some content
                    230:                                                                        
                    231:                                                                        //append document
                    232:                                                                        writer.appendDocument(
                    233:                                                                                cl_document.primaryKey,
                    234:                                                                                cl_document.name,
                    235:                                                                                cl_document.content
                    236:                                                                        );
                    237:                                                                        
                    238:                                                                        //optimize data
                    239:                                                                        writer.optimize();
                    240:                                                                        
                    241:                                                                </pre>
1.18      maik      242: 
1.19      maik      243:                                                                <h4>Searching::</h4>
                    244:                                                                <pre class="brush: js font-size: 80%">
1.18      maik      245: 
1.19      maik      246:                                                                        //initialize xpcom
                    247:                                                                        var reader = Components.classes["@bookmarktools.mozdev.org/search/indexReader;1"].createInstance();
                    248:                                                                        reader = reader.QueryInterface(Components.interfaces.ICLReader);
                    249:                                                                        
                    250:                                                                        //set path
                    251:                                                                        reader.setPath(file.path); //see section 'Writing'
                    252:                                                                        
                    253:                                                                        if(reader.exists()){ //check for index data
1.18      maik      254:                                                                                
1.19      maik      255:                                                                                var query = "Hell*";
1.18      maik      256:                                                                                var results = Components.classes["@mozilla.org/array;1"]
                    257:                                                                                                                .createInstance(Components.interfaces.nsIMutableArray);
1.19      maik      258:                                                                                reader.search(query, results);
1.18      maik      259:                                                                                
                    260:                                                                                var e = results.enumerate();
                    261:                                                                                while (e.hasMoreElements()) {
1.19      maik      262:                                                                                        var resultNode = e.getNext().QueryInterface(Components.interfaces.IResultNode);
1.18      maik      263:                                                                                        
1.19      maik      264:                                                                                        //Object: resultNode
                    265:                                                                                        //-> resultNode.primaryKey
                    266:                                                                                        //-> resultNode.score
                    267:                                                                                        alert(resultNode.primaryKey + "\n" + resultNode.score);
1.18      maik      268:                                                                                }
1.19      maik      269:                                                                                
                    270:                                                                        }else {
                    271:                                                                                //display message or do nothing
                    272:                                                                        }
                    273:                                                                        
                    274:                                                                </pre>
1.18      maik      275: 
1.19      maik      276:                                                                <h4>Lookup::</h4>
                    277:                                                                <pre class="brush: js font-size: 80%">
1.18      maik      278: 
1.19      maik      279:                                                                        //initialize xpcom
                    280:                                                                        var reader = Components.classes["@bookmarktools.mozdev.org/search/indexReader;1"].createInstance();
                    281:                                                                        reader = reader.QueryInterface(Components.interfaces.ICLReader);
                    282:                                                                        
                    283:                                                                        //set path
                    284:                                                                        reader.setPath(file.path); //see section 'Writing'
                    285:                                                                        
                    286:                                                                        var results = Components.classes["@mozilla.org/array;1"]
                    287:                                                                                                        .createInstance(Components.interfaces.nsIMutableArray);
                    288:                                                                        reader.lookup(results);
                    289:                                                                        
                    290:                                                                        var e = results.enumerate();
                    291:                                                                        while (e.hasMoreElements()) {
                    292:                                                                                var lookupNode = e.getNext().QueryInterface(Components.interfaces.ILookupNode);
                    293:                                                                                
                    294:                                                                                //Object: lookupNode
                    295:                                                                                //-> lookupNode.primaryKey
                    296:                                                                                //-> lookupNode.name
                    297:                                                                                alert(lookupNode.primaryKey + "\n" + lookupNode.name);
                    298:                                                                        }
                    299: 
                    300:                                                                </pre>
                    301: 
                    302:                                                                <h4>Delete documents::</h4>
                    303:                                                                <pre class="brush: js font-size: 80%">
                    304: 
                    305:                                                                        //initialize xpcom
                    306:                                                                        var writer = Components.classes["@bookmarktools.mozdev.org/search/indexWriter;1"].createInstance();
                    307:                                                                        writer = writer.QueryInterface(Components.interfaces.ICLWriter);
                    308:                                                                        
                    309:                                                                        //set path
                    310:                                                                        writer.setPath(file.path); //see section 'Writing'
                    311:                                                                        
                    312:                                                                        //delete documents with index 0, 5 and 2
                    313:                                                                        var docs = [0, 5, 2];
                    314:                                                                        writer.deleteDocument(docs, docs.length);
1.18      maik      315: 
1.19      maik      316:                                                                </pre>
1.18      maik      317: 
1.19      maik      318:                                                                <br />
1.18      maik      319: 
1.19      maik      320:                                                                <div class="separator"></div>
                    321:                                                                
                    322:                                                                <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>
                    323:                                                                <h4>Cleanup::</h4>
                    324:                                                                <pre class="brush: js font-size: 80%">
                    325: 
                    326:                                                                        //initialize xpcom
                    327:                                                                        var tidy = Components.classes["@bookmarktools.mozdev.org/repair/tidy;1"].createInstance();
                    328:                                                                        tidy = tidy.QueryInterface(Components.interfaces.ITidy);
                    329:                                                                        
                    330:                                                                        var src = "
                    331:                                                                        &lt;html&gt;
                    332:                                                                                &lt;head&gt;&lt;/head&gt;
                    333:                                                                                &lt;body
                    334:                                                                                        broken body tag &amp; no entity
                    335:                                                                                &lt;/body&gt;
                    336:                                                                        &lt;/html>";
                    337:                                                                        
                    338:                                                                        //result contains the repaired html/xhtml/xml source
                    339:                                                                        //otherwise a error message returned
                    340:                                                                        var result = tidy.cleanup(src);
                    341:                                                                        
                    342:                                                                        if(result == "Tidy: no output"){
                    343:                                                                                alert("error returned");
                    344:                                                                        }else {
1.22      maik      345:                                                                                alert(result);
1.19      maik      346:                                                                        }
1.18      maik      347:                                                                        
1.19      maik      348:                                                                </pre>
                    349:                                                
1.18      maik      350:                                                        </div>
                    351:                                                </div>
                    352:                                        </td>
                    353:                                </tr>
                    354:                                <tr>
                    355:                                        <td>
                    356:                                                <div id="footer">
                    357:                                                        <table>
                    358:                                                                <tr>
                    359:                                                                        <td>
                    360:                                                                                <a href="http://validator.w3.org/check?uri=referer">
                    361:                                                                                        <img src="http://www.w3.org/Icons/valid-xhtml10-blue"
                    362:                                                                                        alt="Valid XHTML 1.0 Strict" height="31" width="88" />
                    363:                                                                                </a>
                    364:                                                                        </td>
                    365:                                                                        <td style="width: 100%;">
                    366:                                                                                <div style="text-align: center;">
                    367:                                                                                        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>.
                    368:                                                                                </div>
                    369:                                                                        </td>
                    370:                                                                        <td>
                    371:                                                                                <a href="http://jigsaw.w3.org/css-validator/check/referer">
                    372:                                                                                        <img style="border:0;width:88px;height:31px"
                    373:                                                                                        src="http://jigsaw.w3.org/css-validator/images/vcss-blue"
                    374:                                                                                        alt="Valid CSS!" />
                    375:                                                                                </a>
                    376:                                                                        </td>
                    377:                                                                </tr>
                    378:                                                        </table>
                    379:                                                </div>
                    380:                                        </td>
                    381:                                </tr>
                    382:                        </tbody>
                    383:                </table>
1.16      maik      384:        </body>
1.18      maik      385: </html>

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