Hi people,

I was using the Pascal reference manual, and found that 'fi' was replaced by some strange character... Modifiers came out as Modi�ers etc. This seems to have happened all over the document at:

http://community.freepascal.org:10000/docs-html/ref/ref.html

This is just a little frustrating, but maybe it's an easy thing to avoid and regenerate the document. If it's more work-intensive, I offer my help in editing...

John

John Coppens wrote

I was using the Pascal reference manual, and found that 'fi' was replaced by some strange character... Modifiers came out as Modi�ers etc. This seems to have happened all over the document at:

Clearly the export as HTML from LaTeX doesn't support the 'fi' ligature. The 'f' and 'i' becomes one character. The actual LaTeX documentation (*.tex) files has it as 'f' and 'i', so there is no need for fixing the documentation - it's just the HTML export that is buggy.

Here is an example of what should have happened.
http://sayamindu.randomink.org/conv_guide/ch01s02.html

I am aware of the ligature problem; The main problem is that it requires re-configuration of tex4ht to fix it. I did it once, maybe an update destroyed this work :/

The good news is that the PDF documentation is correct, and is still - as it always been - the preferred format.

Michael.

Michael Van Canneyt wrote

The good news is that the PDF documentation is correct, and is still - as it always been - the preferred format.

On a side note: The INF version of the Language Reference is also correct. Just a few more sections to complete, then I'll make it publicly available - including the binary DocView (INF viewer).

In our previous episode, Michael Van Canneyt said:

The refered documentation (on the FPC community server) is from 2006:

Reference guide for Free Pascal, version 2.2
Document version 2.0
August 2006

Micha�l Van Canneyt

The good news is that the PDF documentation is correct, and is still - as it always been - the preferred format.

The PDF is mostly good for printing, nothing else.

I don't print the docs at each release.

Marco van de Voort wrote

The PDF is mostly good for printing, nothing else.

I must agree. PDF's looks good on paper, but is terrible to search on screen (very slow), hyperlinks/cross-linking is not always available, no context sensitive help integration from IDE's etc. The INF versions solve all those issues and has much better screen format/layout than the CHM versions.

Graeme Geldenhuys wrote

I must agree. PDF's looks good on paper, but is terrible to search on screen (very slow)

That depends on the PDF reader. Searching is virtually instantaneous on Mac OS X with its default PDF reader (but it's indeed fairly slow with at least Acrobat Reader).

Jonas

Yep... But that is the manual which is on-line at the moment. I thought it would be up-to-date, but it seems the 2.4 package has a much newer html version.

Wouldn't it be advisable (and probably save a lot of questions) to get the online version updated?

John

Okular also searches very fast.

Michael.

The online version is up to date. That is, the one on

ftp://ftp.freepascal.org/pub/fpc/docs-pdf/user.pdf

or

http://www.freepascal.org/docs-html/user/user.html

if you prefer HTML.

The community version ("with comments") should be simply deleted;
it causes only confusion and more work without any benefit.

I have removed the links to them.

Michael.

The community version ("with comments") should be simply deleted; it causes only confusion and more work without any benefit. I have removed the links to them.

Proof of concept: I hadn't found the 'good' one - just the old version. Thanks for deleting ;-)

John

Michael Van Canneyt wrote

The community version ("with comments") should be simply deleted; it causes only confusion and more work without any benefit.

+1 for the confusion bit.

I have removed the links to them.

A good decision.

Michael Van Canneyt wrote

> > That depends on the PDF reader. Searching is virtually instantaneous on > Mac OS X with its default PDF reader (but it's indeed fairly slow with at > least Acrobat Reader).

I guess Mac has better PDF support than any other platform. Acrobat Reader on Linux is slow to start up, does not come standard with Linux distros, is a rather large download.

Okular also searches very fast.

I have never heard of Okular, but a quick Google search reveals it's part of KDE apps. I use Evince (included with Ubuntu) or Acrobat Reader to view or print PDF's. Each have there own strengths, but no single one is a clear winner.

I must admit, I haven't used FPC's PDF or HTML docs in some time. The INF versions are very near 100% complete, so they already fulfil my documentation needs and integrate well with Lazarus IDE and MSEide.

The disadvantage being that they are not updated when the documentation is updated.

That said, weren't you going to send me a patch to implement INF support in fpdoc ?

Michael.

Michael Van Canneyt wrote

The disadvantage being that they are not updated when the documentation is updated.

Luckily (no offence meant) the documentation doesn't change that much or that quickly. I'll probably keep to the same release cycle as FPC - whenever a new FPC is released, release new FPC INF docs too.

That said, weren't you going to send me a patch to implement INF support in fpdoc ?

Yes, it's still on my todo list.

One day, you should publish this list.

Careful, you might create a black hole when doing so... ;)

Michael.

Michael Van Canneyt wrote

> Yes, it's still on my todo list. One day, you should publish this list.

:-) By the sounds of things, I don't think your list is going to be much smaller than mine. ;-)

Luckily (no offence meant) the documentation doesn't change that much or that quickly. I'll probably keep to the same release cycle as FPC - whenever a new FPC is released, release new FPC INF docs too.

Hi Graeme,

Sorry for my ignorance - what are INF files? Google seems confused too.

John

John Coppens wrote

Sorry for my ignorance - what are INF files? Google seems confused too.

INF files are compiled (binary) IPF [Information Presentation Facility] help files. It is the help file and digital document format originally created by IBM for the OS/2 operating system. IPF is a very easy to learn mark-up language specifically designed for documentation and produces very good text layout. INF can be used as a help file or as a digital book (similar to PDF).

For the fpGUI Toolkit project, I looked for a cross-platform help file format that I can use for the fpGUI project itself and that developers could use to implement help for their own projects/applications. I needed something that is a single file (so no raw HTML), that is very fast and compact. I evaluated various help file formats and decided to use INF.

Since then, I created a add-on for FPC's fpdoc program to generate IPF output for class documentation. I also implemented a cross-platform INF viewer called fpGUI DocView. The Open Watcom project implemented a open source IPF Compiler (wipfc) which runs under OS/2, DOS, Windows and Linux. wipfc is a 1MB download. At a later date I'll implement my own IPF Compiler in Object Pascal which can hopefully be included with FPC.

I also translated the FPC Language Reference (latex) document to INF format, so now language reference, class documentation (RTL & FCL0 help is available in IDE's like Lazarus or MSEide. DocView is very easy to integrate with these IDE's via their 'external tools' options
- no need to write some add-on plugin/package for the IDE's.

Docview supports: Table of Contents, runtime generated Index or can use the Index included in the INF file, bookmarks, inline annotations, full text searching, search keyword highlighting, reading multiple INF files together as one help file (all done at runtime), font substitution, exporting articles to text etc.

Wikipedia has some information on IPF.
http://en.wikipedia.org/wiki/Information_Presentation_Facility

I'm busy redesigning the fpGUI website which will then include more information regarding INF and DocView and some screenshots.

Wikipedia has some information on IPF. http://en.wikipedia.org/wiki/Information_Presentation_Facility

Thanks for the extensive answer, Graeme!

I'm sure the selection of IPF/INF caused some discussion at the time, particularly at a time where xml is the magic recipe for everything ;-)

Greetings,
John

In our previous episode, John Coppens said:

The library documentation is in XML format, from which other formats can be generated.

The other docs are in LaTeX, which is a bit problematic to transform.

John Coppens wrote

I'm sure the selection of IPF/INF caused some discussion at the time, particularly at a time where xml is the magic recipe for everything ;-)

As Marco said, the class documentation is in XML and gets transformed to other "final" formats via the 'fpdoc' tool.

IPF is a easy to understand mark-up language - similar to HTML, just shorter to type. IPF is also dedicated to documentation/books only, and describes the various text (similar to LaTeX). Later I'll implement some help authoring tool (if the need arises). MSEide already has syntax highlighting for IPF, which helps a lot in authoring help.