Hi,
Disclaimer:
:-) Please note, this in only a testing release (not even beta yet) to get some feedback on the DocView program and the layout of Free Pascal's RTL and FCL help. I have rewritten the fpdoc IPF output writer from scratch to improve the help layout.
At the url below, is an archive with DocView and RTL & FCL inf help files. Linux 32bit only at the moment (sorry). You simply need to double click the 'docview' executable and open one of the INF files. There are install instructions if you wanted to integrate DocView with Gnome Desktop (I still need to figure out KDE & Windows).
http://opensoft.homeip.net/~graemeg/docview_2009-10-28.tar.bz2 (file size: 1.6MB)
Any feedback you can give regarding the INF documentation layout or DocView itself would be much appreciated.
IPF layout notes:
------------------
1) I like the PDF output and modeled fpdoc IPF output according to that.
2) extra Topics in units are reordered to appear after the unit's Overview section.
3) I merged the "used units" and "Overview" sections into one help topic.
4) Enumerated types or constants listings are not formatted yet. Neither is table output. These are next on my list.
5) I found that if I do a search for a keyword (example 'SysUtils') and click on one of the return results, sometimes the topic page is blank. That is because for example the "Overview" topic was in a separate TOC node, one level down. To resolve this, I removed the "overview" (general description) nodes in TOC and merged it with the actual unit, section nodes in TOC treeview. I'll try and explain visually.
eg: It used to be like this:
FCL <-- blank topic
+- Overview
+- unit 'SysUtils' <-- blank topic
+- Additional Topics here
+- Units used
+- Overview
+- Constants & vars
+- Procedures
...and I now made it like this...
FCL <-- overview is here
+- unit 'SysUtils' <-- units & overview is here +- Additional Topics here
+- Constants & vars
+- Procedures
DocView notes (and known problems)
----------------------------------
1) DocView is far from complete and still contains many bugs. :-) Normal disclaimers apply.
2) Some topics fail to load, but this is much less than before. I'm working on fixing this.
3) Searching still needs to be improved slightly - to improve it's accuracy.
4) If no Index exists in the INF file, one will be ) If Index exists (it might be small), so by default the INF's index is merged with a manually created Index resulting in a more complete one. This is a user selectable option.
6) TOC treeview tracks where you are as you browse topics.
7) I often found I wanted to know where in the docs I am without switching to treeview. The status bar now shows your current location.
8) Hyperlinks are still a "hit & miss" feature. Mouse click location is not always 100% accurate, so try clicking on the first half of a hyperlink (words highlighted in blue). I only got basic hyperlinking working last night in the RichTextView component. :-)
9) Scrolling and Resizing is still sluggish.
10) History, Annotations and customizable Font resize/substitutions are not implemented yet. All of these are almost done.
Nice DocView features so far:
-----------------------------
1) Merge help files at runtime using any of the following methods. a) From the command line:
$ docview /path/to/file.inf+/path/to/2ndfile.inf b) Via a directory:
$ docview /path/to/help/files/
c) Via an environment variable:
$ export BOOKSHELF=/opt/help/inf/
$ docview BOOKSHELF
d) Via a directory and file combo:
$ docview /opt/fcl.inf+/path/to/more/help/
2) Show some command line options
$ docview -h
3) Finding a topic ID doesn't work, but Searching does. eg:
$ docview rtl.inf -s <keyword>4) Pretty easy Lazarus integration without modifying Lazarus source code. Similar instructions apply for MSEide integration.
5) Search text is highlighted after a search. This will be user customizable (including the colour) in the future.
6) You can specify more advanced search text. eg:
+GUID -String -Create
This will find all help topics containing the word "GUID", but that doesn't contain the words "String" or "Create".
7) Help topics can be saved to a text file. Escaped or non-Escaped text is user selectable via the docview.ini file. Soon I will have a Settings dialog where all these options can be customized without editing text files.
Lazarus integration:
--------------------
* I have setup an environment variable called FPCHELP which points to both rtl & fcl INF files. I could have used a directory as well.
* I then used option 3) above in the Lazarus External Tools and assigned it the keyboard shortcut Ctrl+F1
* Also part of the external tools setup. Tell Lazarus to pass the current token as a search term to DocView. See the screenshot included in the archive.
* Now while you are coding, press Ctrl+F1 to get help on the current keyword. No internet required! :-)
I would appreciate any feedback you can give regarding DocView itself (features you would like, etc..) and all importantly, the layout of the FPC documentation.
I already received suggestions for FPC doc layout changes:
* Related Topics as a listing in a unit's overview page.
* Inheritance tree in overview page
* Class Declaration as is shown in HTML output.
Have fun! :)