If you pass the CommandLine option --use-tipue-search to pasdoc (or check the Use tipue search engine box in PasDocGui) then additional things (some code in the navigation frame, and some additional files) will be added to the HtmlOutput. These things will provide a "Search" box on the navigation frame that allows full text search on the generated documentation.
The search engine used is tipue. It is a lightweight JavaScript search engine. But you don't have to know how it works – including this search engine in pasdoc is a matter of only passing --use-tipue-search option to pasdoc, everything else is done by pasdoc automatically and you get a working search engine in your documentation.
Contents
Tipue is client-side engine
You must be aware that tipue is a client-side engine (since it uses JavaScript). This means that the whole work is done on the client-side, i.e. by your webbrowser. This means that if you place your documentation on the internet for online browsing, then every user browsing this documentation will have to download the whole index data of your documentation (well, unless he has JavaScript disabled in his browser). And this index data may be large, if you have a large documentation.
So if you place your html documentation online, you should be cautious about the size of the generated index data file, tip_data.js. It really depends on the size of your documentation – it may be small, it may be huge, so I will not give you any general advice here like "use it!" or "don't use it!".
See also ToDoSearch.
Details on how index data is generated by pasdoc
- every item gets a separate entry in the index data,
its URL is the base filename + its #anchor
the short description in the index data is taken from AbstractDescription
longer content in the index data is taken from DetailedDescription + Authors + Params + Returns + Raises etc.
Pages like AllUnits, AllIdentifiers etc. are not put in index at all (they only confuse the search engine, since they contain only some mixed parts from all other pages).
Old issue: Generating index data with Endsheet
At the beginning, when this option was implemented for the first time, users had to manually generate the index data using some external program, like Endsheet. This is no longer needed, not even advised, since pasdoc generates really good index data. But you can do this, if you really want. Here are instructions how:
After generating your documentation with pasdoc:
Switch temporarily to Windows
Run Endsheet, open navigation.html of generated documentation (don't open index.html – Endsheet can't follow links from a frameset).
Run indexing in Endsheet, save the index to the tip_data.js file (remember to select "Tipue data file" as file type)
Then you have to open tip_data.js in a text editor and convert all filenames to contain only base filenames, i.e. no paths. I have no idea why Endsheet writes all filenames with full path (this is unsuitable if you want to move the directory with your documentation around, this is unsuitable if you want to place your documentation online on the internet, this breaks links under Windows since they are not preceeded by file:///).
As you can see there are some flaws in Endsheet. Let me add some more:
The short descriptions of pages (displayed under page titles on results page) are useless. E.g. they start with text like Class TTexDocGeneratorDescriptionHierarchyFieldsMethodsPropertiesUnit .... Partially this is Endsheet stupidity (it glues words together, even though they are in separate table cells in HTML file).
But a description like Class TTexDocGenerator Description Hierarchy Fields Methods Properties Unit ... would also he hardly useful. And this time it's not the fault of Endsheet. These are just the first words in each html file... This can be solved only by generating index data in pasdoc.
Links with anchors (you know, page.html#anchor) are not indexed as separate URLs. In fact, Endsheet does not understand the anchors concept – it seems that Endsheet simply tries to open a file with # in the filename, and of course fails. Anyway, it's negotiable whether Endsheet could generate something sensible for anchors anyway, since Endsheet must deal with general HTML pages. However, in the case of pasdoc pages, anchors divide a page into logical pieces. So this is again something that can be solved only by generating index data in pasdoc.