DocView and FPC help files released

[Graeme]

I am pleased to announce that fpGUI's DocView is available for download in a convenient binary executable from fpGUI's SourceForge project page. See the URL below. DocView is a cross platform INF help file viewer..

I have also made available RTL, FCL, LCL and fpGUI class documentation in INF help format. The documentation downloads are grouped, so you only need to download what you really need. A nice small download to give you access to help offline.

  http://sourceforge.net/projects/fpgui/files/

Download size:
DocView plus it's help file:
  Linux 32-bit    =  533KB
  Linux 64-bit    =  446KB
  Windows 32-bit  =  367KB

Class Documentation:
  fpGUI      [fpgui-20100826.zip]    = 0.1MB
  RTL + FCL  [rtl_fcl-20100826.zip]  = 1.3MB
  LCL        [lcl-20100826.zip]      = 1.4MB


Why DocView and INF help format?
INF is a very compact and very efficient file format created by IBM and was
originally meant for OS/2. As an example of efficiency, let compare the LCL
documentation. LCL class documentation in INF format is a mere 3.8MB in
size - compare that to the same documentation in HTML format (65MB) or CHM
format (12.1MB).

DocView + INF is a perfect match. Here are some of DocView's features:

* DocView's rich text component is custom built for viewing INF
  documents. It is also very fast. Just view something like
  LCL's Forms.TApplication method overview help and you will see.
  DocView can load it instantly, under a second. Scrolling such a
  large page is no problem either [unlike another help viewer I
  know ;-)].

* DocView can open a single INF file, multiple INF files, or a whole
  directory of INF files. DocView doesn't even blink.

* Opening multiple files means the Table of Content tab appends each
  help files TOC to the list. Indexes get merged as well.

* Searching is lightning fast, and across all open help files.

* Create a "virtual bookshelf" of documentation. Docview can open
  directories, or environment variables pointing to help files.

* DocView is customizable. Change the fonts, adjust the search
  highlighting color, hide the navigation tab etc.

* DocView comes with it's own help file to explain all it's features and
  has multiple examples of how it can be used.

* DocView is very easy to integrate with any programmer editor or IDE.
  No need to have support compiled into a IDE.
  Attached are screenshots of how to set it up with Lazarus IDE and
  MSEide. Simply use the "external tools" feature of each IDE, and pass
  in the current token to edit cursor is on.

* The latest fpdoc (in FPC 2.5.1) has had a major rewrite of the IPF
  output writer. IPF is the markup language (similar to other markup
  languages) used to create INF help files.
  fpGUI's source repository contains the IPF Compiler in binary form,
  for Windows and Linux. It also includes a IPF Reference Guide.

How to setup Docview with Lazarus IDE
1) Select "Tools - Configure external tools".
2) Click the Add button
3) Type "DocView" in the title field
4) Enter the location to the "docview" executable in the Program Filename field.
5) Enter the following in the Parameters field:
      /<path>/<to>/<inf_docs>/ -k $(CurToken)
6) Now setup a keyboard shorcut to launch DocView while you are coding.
    eg:  I used:    Ctrl+F1

Now simply place your editor cursor over any class, property, method etc. and press Ctrl+F1 and DocView will show you the help.

What's to come?
* I have more features planned for DocView. Bookmarks and Annotations
  are fist on my list.

* I'm working on translating the Free Pascal Language Reference document
  to INF format. That way developers have Object Pascal syntax help as
  well in their IDE's of choice.

* Lots more fpGUI class documentation coming.


Please enjoy, and I welcome any feedback.

[Leledumbo]

Rocks! It's just me or it's really much faster than chm viewer (hh.exe / kchm / gnomecjm / xhcm / whatever)? It even supports notes, history, limited section search, etc. The only very minor downside is that it doesn't change cursor to hand when hovering a link (better if it can underline it as well when hovering, so we can distinguish between blue colored text and hyperlinks easily).

[Graeme]

Rocks! It's just me or it's really much faster than chm viewer

Last time I tested (few months ago), docview was about 20x faster that lhelp in loading help content and displaying the first help page. 

As for the mouse cursor over links, somebody else also mentioned it too me. I am working on that, it shouldn't be hard to implement. I'll also add extra custom color options in the "options" dialog - so users can define how they want links to look.

[eastorwest]

1.At start docview does not find a file docview.inf if the path to a folder docview contains spaces and/or not ASCII-characters. (WinXP)
2.Whether there is an opportunity for localization docview?

[Graeme]

1.At start docview does not find a file docview.inf if the path to a folder docview contains spaces and/or not ASCII-characters. (WinXP)

I cannot reproduce. I copied the docview.exe and docview.inf file into the following directory. I double clicked on docview.exe, and it load with the INF file shown. No problems.
"C:\Documents and Settings\Graeme Geldenhuys\My Documents\docview test\"

Could you list the exact path to your docview.exe and docview.inf file, so I can reproduce the directory structure you have.

Whether there is an opportunity for localization docview?

Yes, but I need to move all the UI strings out into a resourcestring section first. It's one of the next items on my todo list. The fpGUI framework itself (including all dialogs, standard button captions etc) are all translated already - currently supporting English, Afrikaans, German, Russian, French, Italian, Portuguese (brazil) and Spanish. I can translate to Afrikaans, but I need others to contribute other languages.

[picstart]

The downloaded docview.exe runs fine stand alone... it shows the lcl rcl etc files. With the lazarus ide 9.26.2 win2k and after adding doc view as an external tool and after assigning a key stroke (alt f1) and with the cursor over a keyword nothing happens when the alt f1 is pressed. Now if I make a typo in a file name like rrl.inf I get an error message when the alt f1 is pressed. Does docview in the ide have dependency issues with the OS or the version of lazarus?

[Graeme]

Does docview in the ide have dependency issues with the OS or the version of lazarus?

DocView has no problems with Win2k, and no dependencies on Lazarus. The oldest Lazarus I have is v0.9.28.3, and with it, there is no problems. I use Ctrl+F1 as shortcuts, but any shortcut not conflicting in Lazarus IDE should work.

Does Lazarus v0.9.26.2 have the $curtoken() macro? This is important, because that macro gets translated to the text under the editor cursor, and gets passed as a keyword to DocView to search for.

Also note that even in latest v0.9.29 there is a bug is Lazarus IDE. Setting up external tools with shortcuts, Lazarus IDE never detects any keyboard shortcut conflicts. So make sure no other action in Lazarus IDE is using Alt+F1. That is why I chose Ctrl+F1 because I know that by default nothing uses that shortcut in Lazarus IDE.

Just to reiterate, the DocView setup as external tools, should have parameters as follows:

  <environment_variable> -k $CurToken()

Where <environment_variable> points to a directory containing INF files.

or

  <dir_path_to_help_files> -k $CurToken()

Where <dir_path_to_help_files> is a directory location containing INF help files.

[picstart]

$CurToken() is in the list of macros under tools config external docview  edit
Changing key I've tried a dozen or so Ex alt ctrl z. Again nothing happens and there is no error to indicate an issue its as if lazarus ide won't run docview.exe in a shell.

[frost_asm]

1.At start docview does not find a file docview.inf if the path to a folder docview contains spaces and/or not ASCII-characters. (WinXP)

to Graeme
Path like this "D:\Documents and Settings\frost\Рабочий стол\docview" russian "Рабочий стол"

The downloaded docview.exe runs fine stand alone... it shows the lcl rcl etc files. With the lazarus ide 9.26.2 win2k and after adding doc view as an external tool and after assigning a key stroke (alt f1) and with the cursor over a keyword nothing happens when the alt f1 is pressed. Now if I make a typo in a file name like rrl.inf I get an error message when the alt f1 is pressed. Does docview in the ide have dependency issues with the OS or the version of lazarus?

I had a similar problem. As I understand Lazarus runs docview but somehow it does not show window.
I solved this problem like this: created a bat file docview.cmd with the content
start docview.exe lcl.inf-k "%1"
and put it in a folder docview
Lazarus wrote in settings such
"C:\lazarus\tools\docview\docview.cmd"
in parameters "$ (CurToken)"

to Graeme
It would be good, if one copy of the program was opened only, during realization of new search

[Graeme]

Again nothing happens and there is no error to indicate an issue its as if lazarus ide won't run docview.exe in a shell.

OK, I downloaded 0.9.26.2 and ran it on win2k in a VM session. I see what you mean. The taskmanager shows docview is running, but nothing is displayed.

I found the bug in Lazarus external tools code. See the unit ide\exttooldialog.pas line 341

Code: [Select]

TheProcess.ShowWindow := swoHide;My first reaction is WTF?? No wonder external tools don't work. Simply comment out that line, or change swoHide to swoShowNormal. Recompile Lazarus IDE, and external tools will now work.

The help says that swoHide will hide the application's main form! As I said, WTF? Why would Lazarus developers want to hide the main form of all external tools?!? This makes no sense at all. The same problem is in 0.9.28.3.  I'll query this bug in the Lazarus mailing list.

[Graeme]

to Graeme
Path like this "D:\Documents and Settings\frost\Рабочий стол\docview" russian "Рабочий стол"

Thanks, I'll copy and paste that the name to create such directories. I don't even know how to type them.    I'll test and fix whatever is needed. fpGUI did have a Russian use at one point in time, and we did fix quite a few file handling routines - maybe something crept in by accident.

I solved this problem like this: created a bat file docview.cmd with the content
start docview.exe lcl.inf-k "%1"
and put it in a folder docview
Lazarus wrote in settings such
"C:\lazarus\tools\docview\docview.cmd"
in parameters "$ (CurToken)"

Thanks for the work around, I'll add it to the DocView documentation. I found the cause of the problem (a bug in Lazarus code), as my previous reply mentions. I'll query with the Lazarus developers what their thinking was for hiding the main form of all external tools. Weird!

It would be good, if one copy of the program was opened only, during realization of new search

This is already on my todo list and will be in the next DocView release. I am planning full two-way communication between app and docview. App must can tell docview what to display, and docview must can tell app some information (eg: in a tutorial style help. User read help on next action, now app should go there).

[picstart]

Graeme
commenting out TheProcess.ShowWindow := swoHide; fixed my issue. Thank you for researching this.

[Graeme]

Glad I could help.

Seeing that the issue was still in v0.9.29 as well, I submitted a patch to Lazarus Mantis, so that option is now user selectable. Lets hope the patch makes it into the next Lazarus release.

[hvh]

Will docview also work with Windows7 x64.

[Graeme]

The only very minor downside is that it doesn't change cursor to hand when hovering a link

I have implemented cursor feedback over links today. I also implemented 'user selectable fonts' (now actually working) and 'mouse wheel scroll distance' customization. Also some minor improvements in INF topic rendering. Next step is kinetic scrolling.   

These will all be in the next binary release (no idea when that will be). If you want it sooner, you can grab a copy of the source code from the fpGUI repository and build it from there.

  http://opensoft.homeip.net/fpgui/#Sourcecode