Every developer who once used Qt library knows about Qt Assistant application which come among with the library. In short, Qt Assistant is an API documentation browser with contents tree, index and full text search. The application does great job navigating you through Qt library and tools documentation. But alas it can not neither browse nor index KDE libraries API documentation and DevHelp (GTK and GNOME API) documentation.

Of course, separate browsing tool is available for DevHelp and KDE API documentation can be viewer simply in the web browser. But when we develop we want simple and uniform access to all documentation we use, don't we? Yes, we want and therefore KDevelop IDE provides you with the solution: KDevelop Assistant application (KDevAssistant, kdevassistant from the command line).

What can KDevAssistant do? It can:

• display documentation contents tree;

• access documentation index;

• perform full text search.

And it currently supports following documentation formats:

• Qt DCF format (Qt library API and tools documentation);

• Doxygen .tag format (KDE libraries documentation and other generated by doxygen with tags);

• DevHelp format (GTK, GNOME API documentation and other generated for devhelp);

• CHM format (rarely used rival documentation format ;) );

• KDevelopTOC format (for online html documentation);

• Custom format (anything that can be viewed - pdf, html, txt, etc.).

Detailed information about KDevAssistant capabilities is summarized in the table below:

Screenshots:

Installation

KDevAssistant application comes with KDevelop IDE distribution. If you have KDevelop version >= 3.1 installed then you have KDevAssistant as well.

KDevelop downloads:
Recent version: http://www.kdevelop.org/index.html?filename=HEAD/download.html
Stable version: http://www.kdevelop.org/index.html?filename=download.html

During the first run KDevAssistant tries to find automatically available documentation. It currently can autodetect Qt, KDE libraries and DevHelp documentation.

If you want to perform autodetection after the first run then:

• close KDevAssistant;

• edit $HOME/.kde/share/config/docqtpluginrc, $HOME/.kde/share/config/docdoxygenpluginrc and $HOME/.kde/share/config/docdevhelppluginrc files and remove:
  [General]
  Autosetup=true
  lines.

Of course, manual settings are possible at any time with configuration dialog.

Usage

KDevAssistant can be always used as a standalone GUI application but at the same time it exports some of its functionality with DCOP. What does that mean for you? This means that once you have KDevAssistant running you can perform certain actions from an external editor or a command line. KDevelop IDE itself uses DCOP to communicate with KDevAssistant when it told to do so ("Settings -> Configure KDevelop -> Documentation -> Other -> Use KDevelop Assistant to browse documentation" setting). You can configure your editor or IDE to communicate with KDevAssistant in the similar way through DCOP.

Short description of available DCOP interfaces and their functions:

• KDevDocumentation interface:

  • void lookupInIndex() - opens documentation index page;

  • void lookupInIndex(QString term) - opens documentation index page and looks up the term in the index;

  • void findInFinder() - opens "finder" wizard page;

  • void findInFinder(QString term) - opens "finder" wizard page and tries to search term in all available sources of documentation (TOCs, indices, man and info pages, Google);

  • void searchInDocumentation() - opens documentation full text search page;

  • void searchInDocumentation(QString term) - opens documentation full text search page and performs the full text search;

  • void infoPage() - opens "Show Infopage" dialog and asks for a term;

  • void infoPage(QString term) - opens info page of a term (equal to 'info:/term' in konqueror or 'info term' in console);

  • void manPage() - opens "Show Manpage" dialog and asks for a term;

  • void manPage(QString term) - opens man page of a term (equal to 'man:/term' in konqueror or 'man term' in console);

• KDevPartController interface:

  • void showDocument(QString url, bool newwin) - shows the document (of any format) with given url (opens a new tab if newwin is true).

Examples of using DCOP functions from the shell:

#runs KDevAssistant and remembers it's dcop id
export KDEVASSISTANT=`dcopstart kdevassistant`

#looks up for 'QString' in the documentation index
dcop $KDEVASSISTANT KDevDocumentation 'lookupInIndex(QString term)' QString

#searches for 'QString' in the full text search database
dcop $KDEVASSISTANT KDevDocumentation 'searchInDocumentation(QString term)' QString

#opens man page for gcc
dcop $KDEVASSISTANT KDevDocumentation 'manPage(QString term)' gcc

#opens info page for autoconf
dcop $KDEVASSISTANT KDevDocumentation 'infoPage(QString term)' autoconf

#opens a text file 
dcop $KDEVASSISTANT KDevPartController showDocument "$HOME/.profile" true

Vim and Emacs can be configured to talk with KDevAssistant using DCOP too, but don't ask me how ;) - I'm not a Vim or Emacs expert :) Volunteers?

KDevelop and KDevAssistant

You might ask why KDevAssistant looks like the main KDevelop IDE application. The answer is simple - they are using the same plugins and "shell" (implementation of KDevelop plugin architecture among with the main window). Indeed, kdevassistant and kdevelop applications differ only by main.cpp files. The rest is the same. KDevAssistant loads only documentation and file selector plugins while KDevelop IDE usually loads more plugins.

This is possible because KDevelop aims to be not an application but a common platform to build plugin-based IDE-like applications. More information about KDevelop Platform will be available in further issues of "KDevelop TechNotes".

Discuss this article: http://www.kdevelop.org/phorum5/read.php?2,26441

© 2004 by Alexander Dymo mailto:adymo@kdevelop.org.

Permission to copy, publish and modify this document without restrictions is granted.

Everybody is welcome to share KDevelop knowledge and experience. We accept any materials for the future issues of KDevelop TechNotes.

Reviews:

30.11.2004 - first revision.

01.12.2004 - corrected links.