Documentation strangeness

classic Classic list List threaded Threaded
21 messages Options
12
Reply | Threaded
Open this post in threaded view
|

Documentation strangeness

John Coppens
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
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Documentation strangeness

Graeme Geldenhuys-2
On 3 April 2010 17:33, John Coppens <[hidden email]> 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



--
Regards,
  - Graeme -


_______________________________________________
fpGUI - a cross-platform Free Pascal GUI toolkit
http://opensoft.homeip.net/fpgui/
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Documentation strangeness

Michael Van Canneyt


On Sat, 3 Apr 2010, Graeme Geldenhuys wrote:

> On 3 April 2010 17:33, John Coppens <[hidden email]> 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.
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Documentation strangeness

Graeme Geldenhuys-2
On 3 April 2010 18:10, Michael Van Canneyt <[hidden email]> 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).


--
Regards,
  - Graeme -


_______________________________________________
fpGUI - a cross-platform Free Pascal GUI toolkit
http://opensoft.homeip.net/fpgui/
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Documentation strangeness

Graeme Geldenhuys-2
In reply to this post by Michael Van Canneyt
On 3 April 2010 20:36, Marco van de Voort <[hidden email]> 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.


--
Regards,
  - Graeme -


_______________________________________________
fpGUI - a cross-platform Free Pascal GUI toolkit
http://opensoft.homeip.net/fpgui/
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Documentation strangeness

Jonas Maebe-2

On 03 Apr 2010, at 22:48, 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_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Documentation strangeness

John Coppens
In reply to this post by Michael Van Canneyt
On Sat, 3 Apr 2010 20:36:56 +0200 (CEST)
[hidden email] (Marco van de Voort) wrote:

> 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

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
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Documentation strangeness

Michael Van Canneyt
In reply to this post by Jonas Maebe-2


On Sun, 4 Apr 2010, Jonas Maebe wrote:

>
> On 03 Apr 2010, at 22:48, 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).

Okular also searches very fast.

Michael.
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Documentation strangeness

Michael Van Canneyt
In reply to this post by John Coppens


On Sun, 4 Apr 2010, John Coppens wrote:

> On Sat, 3 Apr 2010 20:36:56 +0200 (CEST)
> [hidden email] (Marco van de Voort) wrote:
>
>> 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
>
> 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?

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.
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Documentation strangeness

John Coppens
On Sun, 4 Apr 2010 12:24:36 +0200 (CEST)
Michael Van Canneyt <[hidden email]> wrote:

> 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
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Documentation strangeness

Graeme Geldenhuys-2
In reply to this post by Michael Van Canneyt
On 4 April 2010 12:24, Michael Van Canneyt <[hidden email]> 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.


--
Regards,
  - Graeme -


_______________________________________________
fpGUI - a cross-platform Free Pascal GUI toolkit
http://opensoft.homeip.net/fpgui/
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Documentation strangeness

Graeme Geldenhuys-2
In reply to this post by Michael Van Canneyt
On 4 April 2010 12:11, Michael Van Canneyt <[hidden email]> 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.


--
Regards,
  - Graeme -


_______________________________________________
fpGUI - a cross-platform Free Pascal GUI toolkit
http://opensoft.homeip.net/fpgui/
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Documentation strangeness

Michael Van Canneyt


On Sun, 4 Apr 2010, Graeme Geldenhuys wrote:

> On 4 April 2010 12:11, Michael Van Canneyt <[hidden email]> 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.
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Documentation strangeness

Graeme Geldenhuys-2
On 4 April 2010 18:21, Michael Van Canneyt <[hidden email]> 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.


--
Regards,
  - Graeme -


_______________________________________________
fpGUI - a cross-platform Free Pascal GUI toolkit
http://opensoft.homeip.net/fpgui/
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Documentation strangeness

Michael Van Canneyt


On Mon, 5 Apr 2010, Graeme Geldenhuys wrote:

> On 4 April 2010 18:21, Michael Van Canneyt <[hidden email]> 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.
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Documentation strangeness

Graeme Geldenhuys-2
On 05/04/2010, 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. ;-)


--
Regards,
  - Graeme -


_______________________________________________
fpGUI - a cross-platform Free Pascal GUI toolkit
http://opensoft.homeip.net/fpgui/
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Documentation strangeness

John Coppens
In reply to this post by Graeme Geldenhuys-2
On Mon, 5 Apr 2010 00:07:07 +0200
Graeme Geldenhuys <[hidden email]> wrote:

> 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
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Documentation strangeness

Graeme Geldenhuys-2
On 5 April 2010 16:19, John Coppens <[hidden email]> 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.

--
Regards,
  - Graeme -


_______________________________________________
fpGUI - a cross-platform Free Pascal GUI toolkit
http://opensoft.homeip.net/fpgui/
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Documentation strangeness

John Coppens
On Mon, 5 Apr 2010 17:25:44 +0200
Graeme Geldenhuys <[hidden email]> wrote:

> 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
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Documentation strangeness

Marco van de Voort
In our previous episode, John Coppens said:
> Graeme Geldenhuys <[hidden email]> wrote:
>
> > 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 ;-)

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.
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
12