|
here is the faq.htm as promised.
JB
|
DQSD Frequently Asked Questions
Last updated: 29-June-2002
This feature was added and released in version 3.0.
This feature was added and released in version 3.0.
You can the latest released version at http://www.dqsd.net
and the latest beta version at http://sourceforge.net/projects/dqsd.
You can reload the DQSD toolbar by typing ! in the search window and pressing
the ENTER key.
XP has a "lock taskbar" feature set by default. Right click on your taskbar and
uncheck Lock taskbar. Then you can drag DQSD all you need and you can disable
showing the name (search), etc... When you get it like you want it, you can
lock the taskbar again.
- Ctrl-Enter - Adds www. prefix and/or .com suffix to string if necessary and launches URL. Like IE key-binding (only better since the prefix/suffix are only add if needed).
- Shift-Enter - Always opens a new window for the search regardless of the reuseWindowMode setting. This works only when IE is the default browser.
- Ctrl-B / F8 - Search the search history for the current text. (user configurable in localprefs.js)
- Shift-Ctrl-B / Shift-F8 - Search the history for the current text as a prefix. (user configurable in localprefs.js)
- Win-S - Make the search bar active (i.e., make it have the current focus). (user configurable in localprefs.js)
- F1 - Display menu.
- Ctrl-P / Up - Display previous search in history.
- Ctrl-N / Down - Display next search in history.
Right-click on the shoe to the left and choose 'Close Toolbar'. Then
find the uninstaller under the control panel. Some people find the control
panel entry, but they don't know they need to close DQSD before
uninstalling.
To be perfectly safe, 1. close it, 2. reboot the computer, 3. install the
upgrade.
Enter ? as the search or select 'Help / About...' from the menu. The
About Box that appears lists all the current searches.
Searches are defined by XML files in the 'searches' subdirectory.
You need to be comfortable hacking on HTML forms and a bit of JavaScript to add
a search site to the search bar.
If you are, here's what you do:
If you are, here's what you do:
- Take a look at the original HTML form for the search, and create your own HTML form to do the same thing, but where you make all the input fields hidden instead of visible (i.e., change the type to "hidden"). Be sure to be explicit about the "action" of the form (it has to be an absolute URL).
- Write a JavaScript function that takes one text parameter and assigns values the hidden fields of your form, and then submits it. By convention, if the text parameter is blank, you should open a window into a useful page that helps you launch the search -- typically the home page of the search. If there are multiple fields in the form, then your JavaScript should use a regular expression of some kind to pull apart the single text field to fill in the multiple form fields. The easiest way to do this is with the 'parseArgs' function, which will handle the parsing for optional 'switches' and their values.
- Paste your new HTML form and your new JavaScript function into its own XML file (SEARCHNAME).xml in the searches sub-directory - copy the bits of xml from an existing search xml file - and include the attribute indicating your JavaScript function name, a short name for the search, a long description, a link to a description of the search engine, your name, and so on. Be sure to follow XML rules - all your attributes need to be quoted, remember the trailing slash in the INPUT tag, etc...
- You can test your xml syntax by opening the xml file directly in IE. It will tell you if you've got a simple syntax error.
- Once your xml file is in good shape, you can "activate" your changes by typing "!" alone in the search bar. This causes it to reload itself.
- Test things out. It usually takes some twiddling to make sure your shortcut works, and that you can also see your new search described in the "?" about box.
- Then post your new search onto the Source Forge mailing list to share it with the world! :-)
Here is some information about the XML:
- Your search will be callable using the function="..." name. E.g., if function="foo" then you can do the search saying "foo bar". So pick a good short name for your JavaScript function.
- Every search's NAME attribute will be displayed if the search is put on the menu, so keep it short and descriptive, like a menu item.
- If you include a LINK attribute, then the link will appear in the ? help box for the search.
- The DESCRIPTION attribute is also included in the ? help box.
- The CATEGORY attribute defines the name of the category in which the search appears in the ? help box.
-
The CONTRIBUTOR attribute is for your name, and the EMAIL attribute is for your
email address.
E-mail it as an attachment to the
DQSD Users Group
Searches can be downloaded from Source Forge at
http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/dqsd/dqsd/searches/
Aliases are simply other names for existing searches. Aliases are
defined in aliases.txt and/or localaliases.txt, but localaliases.txt is meant
to be the user-defined file, and it won't be overwritten on an install.
Aliases also provide substitution of '%s' (no quotes) with the actual search
string. This allows some custom searches to be added very quickly
just by adding the URL with '%s' in the query string. Aliases are also
referred to as Shortcuts.
There is currently no way to undefine an alias in aliases.txt without removing
it from aliases.txt. (I'm sure this will be fixed in an upcoming
release.)
An alias must be defined before it can be referenced from another alias. For
example these two lines in the localaliases.txt file will show two shortcuts in
the helpbox:
- dqsdcvs|http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/dqsd/dqsd/
- dqsd|dqsdcvs
But these two lines will only show the dqsdcvs one:
- dqsd|dqsdcvs
- dqsdcvs|http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/dqsd/dqsd/
The same two lines, but the second set sets an alias to call another alias that hasn't been defined yet.
Configuration settings for DQSD are defined in the preferences.js file. User
overriding settings are defined in localprefs.js. These files have
definitions to control the look and behavior of the toolbar. As new features
are added which require new configuration settings, new entries will appear in
the preferences.js included in DQSD releases. The preferences.js file
gets overwritten during the upgrade process. For this reason the user
should make the desired configuration changes to the localprefs.js file.
Preferences.js is included in the DQSD release bundle, therefore changes made
to the preferences.js file will be lost when a new DQSD release is installed.
Preference changes should be made to localprefs.js to be retained from release
to release.
Autocomplete requires two configuration settings to be specifically set in the
preference files. By default DQSD does not enable the autocomplete
functionality. 'autocomplete' must be set to 'true" and 'multiline' must be set
to 'false'.
Style settings for DQSD are defined in the search.css file. User overriding
settings are defined in localsearch.css These files have definitions to
control the look and styles of the toolbar. As new features are added which
require new style settings, new entries will appear in the search.css included
in DQSD releases. The search.css file gets overwritten during the upgrade
process. For this reason the user should make the desired configuration
changes to the localsearch.css file.
Search.css is included in the DQSD release bundle, therefore changes made to
the search.css file will be lost when a new DQSD release is installed. Style
changes should be made to localsearch.css to be retained from release to
release.
Ground rules for checkins into CVS:
- If you want to merge in some changes, just let Dave know which SourceForge account needs CVS write access. Access is no problem if you're going to contribute; just don't abuse it.
- When you do commit a change, please let Dave and the DQSD Users Group know.
- If you're going to do major rearrangement, broadcast your intent to the DQSD Developers Group ahead of time.
- If you're adding novel functionality, please consider including an option for preferences.js to turn it off. Also please consider making the default "off" until it's completely tested and polished.
- Small changes should have small diffs. Please do not use a wysiwyg HTML editor that will introduce diffs on every line, or your checkin will be backed out.
-
In the code, please mimic the prevailing convention for tabbing and spacing:
- No tab characters in code please. Use spaces instead. (The exception is where tabs have semantics of course). Code should be indented 2 spaces per level.
- Please, no space characters after a ( or before a ).
- Curlies for a {multiline block} should be on their own line and unindented (just their contents are indented).
-
Also please mimic the prevailing convention for packaging:
- Sources should be included in the distribution itself since this is the easiest way to conform to the GPL. So all source files should be listed in "search.nsi"; i.e., you shouldn't need CVS to get a working build.
- Please keep "build.cmd" working. In particular this means that DQSDTools.mak needs to be kept up to date. Also, any files that are automatically generated by the build should be deleted by "clean.cmd".
- Keep new sources, except for those that are being used at runtime, underneath src/.
- Keep in mind that you are editing other people's code and that other people will edit your stuff. Please don't be offended if your code is changed or even disabled. Be nice!
- Dave may decide to turn your access off if things become unmanageable, or if you don't make checkins for a while.
Ten steps to a working build of DQSD from SourceForge:
Alternate CVS Utilities:
- Make sure you're using Windows 2000 or better.
- Install cygwin from http://cygwin.com/setup.exe.
- Install Microsoft Visual C++ 6.0.
- Install NSIS - http://http://www.nullsoft.com/free/nsis/.
- Make sure that MSVC and NSIS are on your path (you can try using Control Panel/System Properties/Environment Variables).
-
From your cygwin prompt, type the following to checkout:
- cd ~
- cvs -d:pserver:[EMAIL PROTECTED]:/cvsroot/dqsd login
- cvs -d:pserver:[EMAIL PROTECTED]:/cvsroot/dqsd co
- dqsd
-
And whenever you want to get the latest:
- cd ~/dqsd
- cvs update -dP
-
Type the following to build:
- cd ~/dqsd
- src/build.cmd
- In the end, you should get a dqsd/dqsd.exe.
- To go back to pristine sources, run src/clean.cmd
Alternate CVS Utilities:
- WinCVS is a GUI front-end to CVS that you can use. You can pull the latest version here: http://sourceforge.net/projects/cvsgui
- Check out Tortoise CVS. It adds the most basic/common CVS command functionality to Explorer, so you can update, commit, add, diff, etc.. with a right click from an Explorer window. Get it here: http://www.wincvs.org/TortoiseCVS/index.shtml
At times users may want to add more functionality than is
possible or makes sense with a single .XML search file. Also, it may not make
sense to have this new feature be installed for all users. If so, the ability
to add add-ons allows for multiple files to be packaged together in an optional
installation package. Add-ons are installed in the 'addon' subdirectory.
When a new feature is not really a search, and/or it requires
more than just a single XML file, and/or it doesn't have general appeal (i.e.,
not many will use it) it should be an optional add-on.
The best place to learn about creating add-ons is to look at the current addon
examples (googlespell, etc), and use them as a template for your own.
