Can we have fpc's doc in chm format? It's easier to navigate and search compare to other formats. :)

-Bee-

has Bee.ography at:
http://beeography.wordpress.com

Bisma Jayadi wrote

Can we have fpc's doc in chm format? It's easier to navigate and search compare to other formats. :)

The reference material: If you complete the chm backend of fpdoc, yes. The manuals: definitely out.

But I don't see how CHM is better than PDF. PDF offers all that CHM offers, plus well-formatted printed output.

Michael.

The reference material: If you complete the chm backend of fpdoc, yes. The manuals: definitely out.

Actually, the HTML is all fine. I just don't like to always back and forth between TOC and the content due its single page nature. It'd be better if the layout is change to 2 page/frame. Left frame for the TOC and the right pane for the content.

But I don't see how CHM is better than PDF. PDF offers all that CHM offers, plus well-formatted printed output.

Every format has its best and worst. If PDF is SO good, how can people think about other alternative formats? ;) No need to discuss more about this. :)

-Bee-

has Bee.ography at:
http://beeography.wordpress.com

I once made a chm from the html files, but the index generated by the help compiler was horrible.

Vincent

But I don't see how CHM is better than PDF. PDF offers all that CHM offers, plus well-formatted printed output.

In my case, I have the impression that CHM is much lighter than PDF (which is logical considering much simplified graphical formatting). Also I like that the characters are in a set that I choose. And normally, I try to resist printing docs anyway.

John

Adrian Maier wrote

Also , it would be nice to be able to copy-paste procedure names and source code examples from the docs .

This can be done with PDF as well.

In the next release, I hope to have a search engine included in the docs. I found one, written in FPC, so that is perfect ! (ioda or something)

Michael.

PDFs are great for printing , but when reading them on-screen the page-oriented-ness
is a little awkward .

Probably the people who are asking for CHM docs are hoping to experience better search capabilities , although the CHM format itself might not guarantee it .

Also , it would be nice to be able to copy-paste procedure names and source code examples
from the docs .

The truly painful experience with the fpc docs is finding a class/procedure that is
performing a certain function and that you haven't used before and that you are not
even sure it exists . The functionality is fragmented into units and the navigation
links requires an advanced understanding about one can expect to find in each unit : before reaching the reference page of a procedure you need to know its exact
name or at least the unit is belongs to .

For instance : some string-related procedures are in the System unit, some in StrUtils , and God knows where else. I am sure that there is some logic (and/or heritage)
in separating them that way, but it's difficult to hunt down all those procedures and
functions throughout the RTL reference manual without proper search and browsing capabilities .

Cheers,
Adrian Maier

Adrian Maier wrote

Probably the people who are asking for CHM docs are hoping to experience better search capabilities , although the CHM format itself might not guarantee it .

fpdoc does support searching, but you need to have your own search engine (backend) hooked up. It's actually mentioned in the documentation, just search for it. ;-) I had a look at this a few months back, because I think searching the Class documentation for any project is very important.

I'll search my email archive for the name of that search engine backend. All I needed to do was reformat some files fpdoc already generates and save it in a format the search engine expects. It would have been a very simple process - not sure why I haven't done it yet.

Regards,
- Graeme -

_______________________________________________
fpGUI - a cross-platform Free Pascal GUI toolkit
http://opensoft.homeip.net/fpgui/

What pdf viewer are you using? I can't do it on Linux with xpdf or kghostview.

Great news !

Any chances to have better navigation in the online HTML docs ? I mean : a better presentation of what the units contain , without being forced to click N times until getting to the list of "Procedures" or "Classes" . As i was explaining : finding items is painful unless you already know the unit .

It could help if it were possible to search for keywords only in the procedure/function/class descriptions ( mailing list results are usually overwhelming and make me prefer trying to google and ask on the mailing list ) .

Graeme Geldenhuys wrote

I'll search my email archive for the name of that search engine backend. All I needed to do was reformat some files fpdoc already

Google's GMail is awesome!!! The search engine is called, Tipue. It's implemented in JavaScript and is pretty easy to add to fpdoc output.

http://sourceforge.net/projects/tipue/

Regards,
- Graeme -

_______________________________________________
fpGUI - a cross-platform Free Pascal GUI toolkit
http://opensoft.homeip.net/fpgui/

I use 'evince' which is the standard PDF viewer with Ubuntu. I can copy any text I want. As far as I remember 'xpdf' also allows coping text, but it uses the old 'middle mouse button' to paste the text. Some older X11 apps don't support the usual KDE or Gnome copy and paste style. Simple highlight the text with the mouse, open gEdit and Middle click (mouse wheel click) in gEdit.

Regards,
- Graeme -

_______________________________________________
fpGUI - a cross-platform Free Pascal GUI toolkit
http://opensoft.homeip.net/fpgui/

Here is a sample search page of Tipue working with the fpGUI docs. The tip_data.js file is what needs to be generated.

If you specify --html-search=../search.html in the fpdoc command line, it will add a Search link in the header of your generated HTML files.

Regards,
- Graeme -

_______________________________________________
fpGUI - a cross-platform Free Pascal GUI toolkit
http://opensoft.homeip.net/fpgui/

I'm still unable to to copy text in xpdf. But I've just installed evince and copying text
works . Thanks for telling me about it , Graeme !

> This can be done with PDF as well. What pdf viewer are you using? I can't do it on Linux with xpdf or kghostview.

xpdf: like on any other x11 app: left mouse button to copy, middle mouse button to paste. It's a little bit akward that you mark a block instead of consecutive text, but one gets used to that. Acrocread does that better.

*ghostview: i don't think it's possible to c&p
text from ghostview based pdf viewers, as ghostview (comming from ps) does not have a notion of text
within a file but of arbitrarily positioned glyphs.

Attila Kinali

I use acroread.

I'm not planning to change the structure of the pages. At most an index page per unit will be added.

But I expect the search engine to solve this kind of issue.

Michael.

Before I found ioda, I looked at this too but it's a very limited engine.

It's only plus is that it works in JavaScript, but I suspect that this can be remedied for ioda as well, as long as you can read the data files.

Michael.

Ahem. Can you imagine what would happen if I would create a full-text search data result file for the FPC docs ?? You could go and have a cup of coffee while your browser tries to parse the thing...

... Only to find it stopped with an 'out of memory' error. So it had better be a damn good cup of coffee :-)

Michael.

Michael Van Canneyt wrote

... Only to find it stopped with an 'out of memory' error. So it had better be a damn good cup of coffee :-)

My thoughts exactly. At least you will have an excuse to get a cup of coffee. ;-)
fpGUI is a lot smaller so should still be possible. None the less, I do agree - Tipue will only be viable for smaller projects.

Regards,
- Graeme -

_______________________________________________
fpGUI - a cross-platform Free Pascal GUI toolkit
http://opensoft.homeip.net/fpgui/

Adrian Maier wrote

On Dec 3, 2007 1:04 PM, Michael Van Canneyt wrote: > On Mon, 3 Dec 2007, Adrian Maier wrote:

.
.

.
.

Some time ago I started some kind of "unit categorization" (http://wiki.freepascal.org/Unit_categorization) aiming to help with finding the right unit for a particular task. Obviously, it's just a start and doesn't include anything from FCL, packages, etc., but it may still help new users to find their way around.

I'm not sure whether this found its way into the docs, though.

Tomas

Graeme Geldenhuys wrote

fpGUI is a lot smaller so should still be possible. None the less, I do agree - Tipue will only be viable for smaller projects.

Just for interest sake... I generated full text search with fpDoc & Tipue for the fpGUI project.
That's if anybody wanted to see how Tipue works for smaller scale projects.

http://opensoft.homeip.net/fpgui/docs/index.html

I wrote a very simplistic parser to generate the tip_data.js file. It runs through the *.cnt files that fpdoc generates and then reads out the Short Description from the HTML files. I have 9000+ html pages and it took under a second to generate the Tipue data file.

Regards,
- Graeme -

_______________________________________________
fpGUI - a cross-platform Free Pascal GUI toolkit
http://opensoft.homeip.net/fpgui/

I once made a chm from the html files, but the index generated by the help compiler was horrible.

Agree. However, I was finally able to finish this job last night. It took me about 6 hours to re-arrange the index files, manually. For everyone who is interested, fpc docs in chm format can be downloaded at: http://www.esnips.com/doc/04496e39-6105-423d-b571-b0766990b060/fpc-2.2.0-docs (5.8 MB compressed)

The source was taken from fpc's html files converted to chm using winCHM. As a bonus, I included fpc/lazarus class diagram with the chm. I also had removed all unfinished pages (html files with no content but they are there). Hopefully, next fpc release would be able to provide chm format like this automagically so I don't need to do this again. :-D

Hope this helps.

-Bee-

has Bee.ography at:
http://beeography.wordpress.com

I'm still unable to to copy text in xpdf. But I've just installed evince and copying text works . Thanks for telling me about it , Graeme !

xPDF version 3.01 permits copying. It's a little awkward, as the selection box is a graphic rectangle. But with a little experience, copying works fine (paste with middle button), and xpdf is sooo fast!

John

Can we provide this file on fpc's doc ftp?

-Bee-

has Bee.ography at:
http://beeography.wordpress.com

why not giving it a try ? :-) I'm downloading

2007/12/4, Bee :

I have almost completed the patch to add chm as an output option for fpdoc.

And before anyone gets their hopes up, to make chm's searchable you have to at creation time generate a special file that is contained in the chm. To me it's relatively difficult and I never implemented it.

Short version: chm's made with the current chm writing code cannot be searched with the helpviewer.

That having been said, If a viewer is written for chm files (there is reader code with fpc too) perhaps a database file created with some search engine (like ioda) can be included and integrated so searching is possible.

Michael, are the manuals written in rtf? why couldn't they be in a chm file?

Regards,

Andrew Haines

Michael Van Canneyt wrote: Michael, are the manuals written in rtf?

They are in LaTeX with specialized environments.

Attached is a patch to add chm output to fpdoc. I edited Makefile.fpc to require the "package" chm. Also a patch for chmwriter.pas with some minor changes that were needed.

Regards,

Andrew

I tried it, and a bit strange was the fact that when opened from a network drive, the treeview loaded, but all the content was IE's page not found page.

The same .chm copied to C:\ worked.

A known security issue of M$.

Go figure...

Michael.

Nice. Thank you.

Andrew Haines wrote

Attached is a patch to add chm output to fpdoc. I edited Makefile.fpc to require the "package" chm. Also a patch for chmwriter.pas with some minor changes that were needed.

Don't apply this patch. I have improved it a bit and now fpdoc (here) can autogenerate a TOC. Later this morning I will work on autogenerating an Index.

Currently for the TOC I have:

Classes and Objects, by Unit
UnitName1
TClass1
TClass2
UnitName2
TClass40
TClass41

Alphabetical Classes and Objects
TC
TClass1
TClass2
TS
TSimpleClass

Routines, by Unit
Unit1
AddNumbers
ConvertSomething
Unit2
JumpUpAndDown

Alphabetical Routines Listing
A
AddNumbers
C
ConvertSomething
J
JumpUpAndDown

Is there another way to sort that someone can think of? If it's not too time consuming I'll do it.

For the Index I have the following plan for layout:

Abs function
ColumnClick
TCustomListView
Read
TStream
TMemoryStream
Read method
TCustomListView
ActionChange
AddItem
ColumnClick
TMemoryStream
Read
Write
TStream
Read
Write
vsIcon
Write
TMemoryStream
TStream
Write method

The Index will have all classes, enums, consts, procedures and functions listed in alphabetical order in the above format.

Andrew

Great news !
Is this TOC page available in all formats, or just for chm ? I would for obvious reasons prefer the first ;-)

The Index will have all classes, enums, consts, procedures and functions listed in alphabetical order in the above format.

This is enough, I think...

Great work !

Michael.

Thank you very much for all your efforts.. I just downloaded and began to use it at once.

The TOC is not made to be generically usable sorry :(

Okay, here's the patch. it adds the ability to have fpdoc output chm's which have an autogenerated toc and index.

to import the .xct files from another package/chm looks like this: --import=/path/to/rtl.xct,ms-its:rtl.chm::/
--import=/path/to/fcl.xct,ms-its:fcl.chm::/

There's a seriously huge improvement in speed of the chm code when compiled with -Ooregvar. I added it to the Makefile.fpc in the packages/chm directory. I guess the Makefile will have to be regenerated.

Regards,

Andrew

PS you can have a peek at some chm's I made with fpdoc here: http://hainesservice.com/andrew/chms/ they are all crosslinked.

Andrew Haines wrote

There's a seriously huge improvement in speed of the chm code when compiled with -Ooregvar. I added it to the Makefile.fpc in the packages/chm directory.

That must not be done. When compiled for a release, -O2 is used which automatically includes -Ooregvar. Otherwise, no specific optimisation switches must be added because it makes debugging more difficult and is also inconsistent with all other Makefiles.

Jonas

A pity, more work for me... :-)

I removed the optimization. As Jonas pointed out, you should not add this by default. It will be added automatically when making a release anyway.

The patch is applied, and I also removed the conditional define which you put in.

PS you can have a peek at some chm's I made with fpdoc here: http://hainesservice.com/andrew/chms/ they are all crosslinked.

How do I view this on a Linux KDE system ?

Michael.

Michael Van Canneyt wrote

How do I view this on a Linux KDE system ?

you can use xchm or gnochm and I think there is a kde variant too, though I don't know it's name.

Andrew

After some searching: kchmviewer, and chmsee for GTK.

Thanks.

Michael.

Andrew Haines wrote

PS you can have a peek at some chm's I made with fpdoc here: http://hainesservice.com/andrew/chms/ they are all crosslinked.

With kchmviewer I get the following errors:

An error occurred while loading ms-its:/home/michael/Documents/fcl.chm::/streamio/assignstream.html: The file or folder ms-its:/home/michael/Documents/fcl.chm::/streamio/assignstream.html does not exist

Same for every other page, even the index page.

With chmsee, I can load the initial page, but the first 5 units or so cannot be found. Others seem to work well. So it seems that there are some glitches in the file generation.

Nevertheless, the basic functionalities seem to be there, so kudos to you... :)

Michael.

Maybe your download is corrupted somehow... I just downloaded kchmviewer and chmsee and it works fine here. Also the MS reader which seems to be the most picky reads the file.

Andrew

Hm.
I just re-downloaded, and have the same problems, with both programs, for all files :/ I also just downloaded some ISO images, and those came through without a glitch, so I'm not entirely convinced it is the download (unless something is wrong with the files on your site..)

Ah well, the mysteries of internet :/

Michael.

I downloaded the files and they are ok.

Looking at the log it looks like you've only downloaded the lcl.chm file again, Maybe your browser is caching. try using wget.

wget http://hainesservice.com/andrew/chms/fcl.chm
wget http://hainesservice.com/andrew/chms/rcl.chm
wget http://hainesservice.com/andrew/chms/lcl.chm

Andrew

Maybe you are both simply using different versions of kchmviewer and chmsee?

Jonas

I downloaded them, installed kchmviewer 3.1 (ubuntu gutsy) and got:

An error occurred while loading
ms-its:/home/mattias/file:/home/mattias/pascal/docs/rtl.chm::/index.html: Could not read file
ms-its:/home/mattias/file:/home/mattias/pascal/docs/rtl.chm::/index.html.

Similar errors for the other two files.

Mattias

Ok, well I've put the original chm files in a couple of tar.bz2 files on that page. So if they still don't work I'm stumped.

Andrew

I uploaded md5's for the chms as well

$ md5sum -c *.MD5
./fcl.chm: OK
./lcl.chm: OK
./rtl.chm: OK

Why do you believe that the .chm files can be read by all viewers?

Mattias

Hi,

If use kchmviewer, try:
Settings->Change Settings->Version-Specific settings: select "QTextBrowser-base widget", instead of "KHTMLPart-base widget".

HTH,
Funky Beast

Sorry, Same problem. I'm also using kchmviewer 3.1, as Mattias...

Michael.

Michael Van Canneyt wrote

Sorry, Same problem. I'm also using kchmviewer 3.1, as Mattias...

Perhaps some path is hard coded into the files, and it exists for Andrew (it's his system, after all) and doesn't for anyone else.

Jeff.

xchm can read them.

Mattias

Okay, I've regenerated the files with a 32bit version of fpdoc and put them at the link below. the md5's are different and also diff says the files differ. The new files are the same size as the old ones. The only thing different is fpdoc(32 bit instead of 64) I've not updated fpc or anything.

http://hainesservice.com/andrew/chms/

Can anyone recommend a program to compare files that can tell me the places at which they are different? Thanks

Regards,
Andrew

Seems the only difference is the timestamp :) so it still won't work likely if it didn't before.

Andrew

Apart from many other tools, you could e.g. use
my bincomp
(http://www.volweb.cz/xhajt03/bincomp.zip).
Compile it for your platform and run, it should
be more or less self-explaining. I've only used
it under OS/2, DOS and Win32 so far, but it
should hopefully work on other platforms too.

Tomas