Sign in Join

Live chat for Free Pascal, Lazarus, Delphi and every Pascal programmer.

Mailing lists / fpc-pascal / 2026-09

Docs - structural change

16 messages · 8 people · –

Reply by email Subscribe to this list Your subscription

Read-only archive. Use j and k to move between messages.

Michael Van Canneyt

Hi,

It always bothered me that it is cumbersome to navigate the docs - the standard tex4ht mechanism is too bare-bones.

So I added some postprocessing to add a (optional) sidebar:

https://www.freepascal.org/~michael/docs-demo/docs/sidebar/

Which makes navigation more comfortable.

It loads the sidebar at runtime with some javascript, to avoid bloating every page with the same sidebar HTML.

Comments, suggestions welcome.

(site might be slow currently, seems we're being visited by some bots...)

Michael.

Reply by email

Tomas Hajny
to Michael Van Canneyt

On 2026-09-09 23:09, Michael Van Canneyt via fpc-pascal wrote:

Hi Michael,

Show quoted text 16 lines
It always bothered me that it is cumbersome to navigate the docs - the standard tex4ht mechanism is too bare-bones. So I added some postprocessing to add a (optional) sidebar: https://www.freepascal.org/~michael/docs-demo/docs/sidebar/ Which makes navigation more comfortable. It loads the sidebar at runtime with some javascript, to avoid bloating every page with the same sidebar HTML. Comments, suggestions welcome. (site might be slow currently, seems we're being visited by some bots...)

It looks nice and is certainly useful. There's just one caveat - could you please check whether HTML files created this way are still usable in our IDE? It isn't critical if not as long as the CHM version of all the help files is provided as an alternative (and it works correctly with that version), but if the direct HTML files aren't supported as the help in the IDE any longer, we should communicate it clearly (especially considering the fact that some users might have this configured for their existing installations, but also for new installations).

Tomas

Reply by email

Unknown author
to Michael Van Canneyt: It always bothered me that it is cumbersome to navigate the docs - the standard tex4ht…

One other issue

https://www.freepascal.org/~michael/docs-demo/docs/sidebar/ref/refse12.html#x25-240003.1

The "this section contains" has almost the same look as code samples. Well actually, it doesn't have all around border, but that is hardly distinguishable.

I am not sure how it might best be displayed, but one possibility might be to loose the background color?

Reply by email

Michael Van Canneyt
to Tomas Hajny: It looks nice and is certainly useful. There's just one caveat - could you please check…
Tomas Hajny wrote 29 lines
On 2026-09-09 23:09, Michael Van Canneyt via fpc-pascal wrote: Hi Michael, > It always bothered me that it is cumbersome to navigate the docs - the > standard tex4ht mechanism is too bare-bones. > > So I added some postprocessing to add a (optional) sidebar: > > https://www.freepascal.org/~michael/docs-demo/docs/sidebar/ > > Which makes navigation more comfortable. > > It loads the sidebar at runtime with some javascript, to avoid bloating > every page with the same sidebar HTML. > > Comments, suggestions welcome. > > (site might be slow currently, seems we're being visited by some bots...) It looks nice and is certainly useful. There's just one caveat - could you please check whether HTML files created this way are still usable in our IDE? It isn't critical if not as long as the CHM version of all the help files is provided as an alternative (and it works correctly with that version), but if the direct HTML files aren't supported as the help in the IDE any longer, we should communicate it clearly (especially considering the fact that some users might have this configured for their existing installations, but also for new installations).

As I understood it, the IDE uses CHM files, but all this is disabled for CHM. So we should be OK.

But to make sure I tested, and the help pages still display. It's as expected: The sidebar and the theme switching buttons are created and enabled using Javascript; since there is no javascript, the IDE simply sees the original HTML.

Michael.

Reply by email

Tomas Hajny
to Michael Van Canneyt

On 2026-09-10 09:18, Michael Van Canneyt via fpc-pascal wrote:

Hi Michael,

.
.

As I understood it, the IDE uses CHM files, but all this is disabled for CHM. So we should be OK.

IDE uses whatever is supplied / configured by the user as long as it is one of the supported formats (that includes HTML). If the HTML format of our docs wasn't supported any longer, we should let our users know.

But to make sure I tested, and the help pages still display. It's as expected: The sidebar and the theme switching buttons are created and enabled using Javascript; since there is no javascript, the IDE simply sees the original HTML.

Good, thanks for checking it!

Tomas

Reply by email

Ched
to Tomas Hajny

Dear All,

About IDE: a long lasting question about 3.2.2 in my mind... why are WRITE and READ highlighted, but neither WRITELN nor READLN ?

Well, I have to test the new RC ! Thank you so much for this update and the hard work behond that !!!

Cheers, Ched'

Le 10.09.2026 à 08:12, Tomas Hajny via fpc-pascal a écrit :

Show quoted text 25 lines
On 2026-09-10 09:18, Michael Van Canneyt via fpc-pascal wrote: Hi Michael,  .  . > As I understood it, the IDE uses CHM files, but all this is disabled for CHM. > So we should be OK. IDE uses whatever is supplied / configured by the user as long as it is one of the supported formats (that includes HTML). If the HTML format of our docs wasn't supported any longer, we should let our users know. > But to make sure I tested, and the help pages still display. It's as expected: The sidebar and the > theme switching buttons are created and enabled using Javascript; since there is no javascript, the IDE > simply sees the original HTML. Good, thanks for checking it! Tomas _______________________________________________ fpc-pascal maillist  -  https://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal

Reply by email

Marco van de Voort
to Tomas Hajny: . . IDE uses whatever is supplied / configured by the user as long as it is one of the…

Op 10-9-2026 om 10:12 schreef Tomas Hajny via fpc-pascal:

Show quoted text 8 lines
> As I understood it, the IDE uses CHM files, but all this is disabled > for CHM. > So we should be OK. IDE uses whatever is supplied / configured by the user as long as it is one of the supported formats (that includes HTML). If the HTML format of our docs wasn't supported any longer, we should let our users know.

Afaik CHM is preferred since about 2.4.4/3.0.0. I don't have any info if it works at all anymore and all the umpteen workarounds for lfn/path separators etc.

Reply by email

Tomas Hajny
to Marco van de Voort
Marco van de Voort wrote 13 lines
Op 10-9-2026 om 10:12 schreef Tomas Hajny via fpc-pascal: >> As I understood it, the IDE uses CHM files, but all this is disabled >> for CHM. >> So we should be OK. > > IDE uses whatever is supplied / configured by the user as long as it > is one of the supported formats (that includes HTML). If the HTML > format of our docs wasn't supported any longer, we should let our > users know. Afaik CHM is preferred since about 2.4.4/3.0.0. I don't have any info if it works at all anymore and all the umpteen workarounds for lfn/path separators etc.

Apart from both of us knowing that CHM should be preferred, where exactly is it documented as such? File readme.txt supplied with the last release states about the IDE: "context sensitive help supports help files in HTML, Windows HLP and Borland TPH format". Our documentation (user manual - user.pdf) states in the chapter related to IDE: ------
The IDE contains a help system which can display the following file formats:
- TPH The help format for the Turbo Pascal help viewer.
- INF The OS/2 help format.
- NG The Norton Guide Help format.
- HTML HTML files
=======

And a bit later: "The Free Pascal documentation in HTML format can be added to the IDE’s help system. This way the documentation can be viewed from within the IDE."

And while you ask - as far as I can see, the HTML version still seems to work correctly in the IDE.

Tomas

Reply by email

Marc Weustink
to Unknown author: One other issue https://www.freepascal.org/~michael/docs-demo/docs/sidebar/ref/refse12.htm…
Martin Friebe wrote 11 lines
One other issue https://www.freepascal.org/~michael/docs-demo/docs/sidebar/ref/ refse12.html#x25-240003.1 The "this section contains" has almost the same look as code samples. Well actually, it doesn't have all around border, but that is hardly distinguishable. I am not sure how it might best be displayed, but one possibility might be to loose the background color?

IMO this belongs to the sidebar too. Now when clicking for instance Integers, the page scrolls and no idea how to get back.

Marc

Reply by email

Gene Buckle
to Michael Van Canneyt: It always bothered me that it is cumbersome to navigate the docs - the standard tex4ht…
Michael Van Canneyt wrote 18 lines
Hi, It always bothered me that it is cumbersome to navigate the docs - the standard tex4ht mechanism is too bare-bones. So I added some postprocessing to add a (optional) sidebar: https://www.freepascal.org/~michael/docs-demo/docs/sidebar/ Which makes navigation more comfortable. It loads the sidebar at runtime with some javascript, to avoid bloating every page with the same sidebar HTML. Comments, suggestions welcome.

Ok, this is hilarious.  I *just* replied with a "nice to have" about this exact thing!  Get out of my head! :D

Excellent work as always.

g.

Proud owner of F-15C 80-0007 http://www.f15sim.com - The only one of its kind. http://www.diy-cockpits.org/coll - Go Collimated or Go Home. I'm not crazy, I'm plausibly off-nominal! ScarletDME - The red hot Data Management Environment A Multi-Value database for the masses, not the classes. https://github.com/geneb/ScarletDME - Get it _today_!

Reply by email

Marco van de Voort
to Tomas Hajny: Apart from both of us knowing that CHM should be preferred, where exactly is it…

Op 10-9-2026 om 14:44 schreef Tomas Hajny via fpc-pascal:

Show quoted text 12 lines
>> >> IDE uses whatever is supplied / configured by the user as long as it >> is one of the supported formats (that includes HTML). If the HTML >> format of our docs wasn't supported any longer, we should let our >> users know. > > Afaik CHM is preferred since about 2.4.4/3.0.0. I don't have any info > if it works at all anymore and all the umpteen workarounds for > lfn/path separators etc. Apart from both of us knowing that CHM should be preferred, where exactly is it documented as such?

The fact that 3.2.4 RCs come with them integrated and preinstalled on Windows?  The fact that the IDE says to download the CHMs if they are not?

That doesn't say the rest is deprecated, but it does make clear what is preferred.

Show quoted text 12 lines
File readme.txt supplied with the last release states about the IDE: "context sensitive help supports help files in HTML, Windows HLP and Borland TPH format". Our documentation (user manual - user.pdf) states in the chapter related to IDE: ------ The IDE contains a help system which can display the following file formats: - TPH The help format for the Turbo Pascal help viewer. - INF The OS/2 help format. - NG The Norton Guide Help format. - HTML HTML files =======

Well, fix that then :-)

Show quoted text 7 lines
And a bit later: "The Free Pascal documentation in HTML format can be added to the IDE’s help system. This way the documentation can be viewed from within the IDE." And while you ask - as far as I can see, the HTML version still seems to work correctly in the IDE.

On what target? The problems with html were highly target specific, specially on real dos (not under w9x). Actually the direct impetus to push for CHM as default back then was testing a FPC release in plain dos that took HALF AN HOUR to install, all due to extracting the plain html help.

I can't deprecate the rest, but IMHO the fact that there is zero feedback on them in about a decade says IMHO says enough.

Reply by email

Tomas Hajny
to Marco van de Voort
Marco van de Voort wrote
Op 10-9-2026 om 14:44 schreef Tomas Hajny via fpc-pascal:

.
.

Show quoted text 6 lines
> Apart from both of us knowing that CHM should be preferred, where > exactly is it documented as such? The fact that 3.2.4 RCs come with them integrated and preinstalled on Windows?  The fact that the IDE says to download the CHMs if they are not?

Indeed, it says so if you go to Contents or Index. It doesn't say anything like that if you go to Help->Files.

More importantly - we're about to release 3.2.4 _and_ redesign the WWW site. However, the link provided in the IDE will stop working after the WWW site redesign. I guess we should still fix it for the final release in this case? @Michael? I know that this isn't a regression in RC2, but it is something that we should probably take care of in the context of the WWW site redesign (together with updating the links in the readme.txt and FAQ files which are both also distributed with the release)?

Show quoted text 17 lines
That doesn't say the rest is deprecated, but it does make clear what is preferred. > File readme.txt supplied with the last release states about the IDE: > "context sensitive help supports help files in HTML, Windows HLP and > Borland TPH format". Our documentation (user manual - user.pdf) states > in the chapter related to IDE: > ------ > The IDE contains a help system which can display the following file > formats: > - TPH The help format for the Turbo Pascal help viewer. > - INF The OS/2 help format. > - NG The Norton Guide Help format. > - HTML HTML files > ======= Well, fix that then :-)

;-) Somehow, it came across my mind too. ;-) Will do.

Show quoted text 12 lines
> And a bit later: "The Free Pascal documentation in HTML format can be > added to the IDE’s help system. This way the documentation can be > viewed from within the IDE." > > And while you ask - as far as I can see, the HTML version still seems > to work correctly in the IDE. On what target? The problems with html were highly target specific, specially on real dos (not under w9x). Actually the direct impetus to push for CHM as default back then was testing a FPC release in plain dos that took HALF AN HOUR to install, all due to extracting the plain html help.

Very true - it wouldn't work on anything without LFN support, and extracting and especially indexing the help in this format takes forever. I tested it under Win32. But that wasn't my point - the HTML format should either stay supported, or get documented and announced as not supported any longer rather than breaking the support silently (which fortunately didn't happen, but I wasn't sure about that originally and thus asked).

I can't deprecate the rest, but IMHO the fact that there is zero feedback on them in about a decade says IMHO says enough.

Out of curiousity - how much feedback did you get about the CHM files recently? Isn't it more because most people use Lazarus or other editors rather than the text mode IDE? Obviously, that doesn't mean that we should stop supporting the IDE, just that the amount of feedback to the help format in IDE may not be directly specifically related to the format.

Tomas

Reply by email

Michael Van Canneyt
to Tomas Hajny
Tomas Hajny wrote 18 lines
On 2026-09-10 19:40, Marco van de Voort via fpc-pascal wrote: > Op 10-9-2026 om 14:44 schreef Tomas Hajny via fpc-pascal: . . >> Apart from both of us knowing that CHM should be preferred, where >> exactly is it documented as such? > > The fact that 3.2.4 RCs come with them integrated and preinstalled on > Windows?  The fact that the IDE says to download the CHMs if they are > not? Indeed, it says so if you go to Contents or Index. It doesn't say anything like that if you go to Help->Files. More importantly - we're about to release 3.2.4 _and_ redesign the WWW site. However, the link provided in the IDE will stop working after the WWW site redesign. I guess we should still fix it for the final release in this case?

Should not be necessary, I plan to install some redirects on the site at the apache level so the most important URLs keep working.

What is the page that is recommended in the IDE ?
Because I didn't see any dialog when I tested.

Michael.

Reply by email

Marco van de Voort
to Tomas Hajny: . . Indeed, it says so if you go to Contents or Index. It doesn't say anything like that…

Op 10-9-2026 om 20:40 schreef Tomas Hajny via fpc-pascal:

Show quoted text 5 lines
More importantly - we're about to release 3.2.4 _and_ redesign the WWW site. However, the link provided in the IDE will stop working after the WWW site redesign.

The IDE says here:

-----

 To keep the size of the FPC download reasonably low, the CHM help files  which are necessary for the IDE help to function, are omitted.  To get these docs, go to https://www.freepascal.org/down/docs/docs.var and get
 doc-chm.zip
 for your version. Extract the CHM files and add them to the IDE using Help|Files.
 ------

Afaik rc2 is the same.

Show quoted text 6 lines
  I guess we should still fix it for the final release in this case? @Michael? I know that this isn't a regression in RC2, but it is something that we should probably take care of in the context of the WWW site redesign (together with updating the links in the readme.txt and FAQ files which are both also distributed with the release)?

Yes. Update as much as possible. Don't mention things that haven't been tested for decade.

Show quoted text 8 lines
Very true - it wouldn't work on anything without LFN support, and extracting and especially indexing the help in this format takes forever. I tested it under Win32. But that wasn't my point - the HTML format should either stay supported, or get documented and announced as not supported any longer rather than breaking the support silently (which fortunately didn't happen, but I wasn't sure about that originally and thus asked).

And my point is that if it isn't actively supported, remove it from documentation for now, even if you don't remove the support.

Show quoted text 5 lines
> I can't deprecate the rest, but IMHO the fact that there is zero > feedback on them in about a decade says IMHO says enough. Out of curiousity - how much feedback did you get about the CHM files recently?

CHM ide, one or two per year. CHM in general, about 8-10.

Isn't it more because most people use Lazarus or other editors rather than the text mode IDE?

Yes. Lately people seem to slowly discover CHM as doxygen backend. There are even post rc2 fixes.

Obviously, that doesn't mean that we should stop supporting the IDE, just that the amount of feedback to the help format in IDE may not be directly specifically related to the format.

I keep those apart. But one an year is still more than none in a decade.

Reply by email

Tomas Hajny
to Michael Van Canneyt: Should not be necessary, I plan to install some redirects on the site at the apache level…
Michael Van Canneyt wrote
On Thu, 10 Sep 2026, Tomas Hajny via fpc-pascal wrote:

.
.

Show quoted text 11 lines
> More importantly - we're about to release 3.2.4 _and_ redesign the WWW > site. However, the link provided in the IDE will stop working after > the WWW site redesign. I guess we should still fix it for the final > release in this case? Should not be necessary, I plan to install some redirects on the site at the apache level so the most important URLs keep working. What is the page that is recommended in the IDE ? Because I didn't see any dialog when I tested.

See Marco's response. Note that the readme.txt files refers as well to http(s)://lists.freepascal.org/mailman/listinfo

However, there are also references like: 'There is a link to documentation of Win32/Win64 API provided by MS on page "More information" available on the FPC web site' in readme.txt and FAQ which wouldn't be fixed by any Apache redirection, thus reviewing and updating these texts would be neceesary in any case.

Tomas

Reply by email

Vincent Snijders
to Michael Van Canneyt: It always bothered me that it is cumbersome to navigate the docs - the standard tex4ht…

Op 09-09-2026 om 23:09 schreef Michael Van Canneyt via fpc-pascal:

Show quoted text 18 lines
Hi, It always bothered me that it is cumbersome to navigate the docs - the standard tex4ht mechanism is too bare-bones. So I added some postprocessing to add a (optional) sidebar: https://www.freepascal.org/~michael/docs-demo/docs/sidebar/ Which makes navigation more comfortable. It loads the sidebar at runtime with some javascript, to avoid bloating every page with the same sidebar HTML. Comments, suggestions welcome.

Not directly related to the sidebar, but on
https://www.freepascal.org/~michael/docs-demo/docs/sidebar/ref/refsu5.html#x27-310003.1.2 de range of comp is shown as -2ˆ6 4+1 .. 2¡ˆ6 3-1. On https://www.freepascal.org/daily/doc/ref/refsu5.html it looks better, but not exactly like -2^64+1 .. 2^63-1. Are you sure lower bound is correct? I would expect it to be -2^63.

Vincent

Reply by email