L.s.

I've made a few scripts that
(1) fix (some of) the html output of tex4ht. (fpcdocs/relinkdocs.pp) (2) compress them to chm with generated toc and searchability (fpcdocs/compilelatexchm.pp)

This enabled me to compile the most recent docs to a fairly usable CHM format:

http://www.stack.nl/~marcov/doc-chm.zip

Notes:
* scripts require 2.3.1 r13357 or newer to compile
* scripts only tested on windows, but don't expect problems on *nix.
* The CHMs have no "index" page yet. The latex index is apparantly not translated by tex4ht.
* the list of tables is still broken.
* The title of the file is hardcoded on the cmdline.
* The scripts are not fully recursive, and only add html files. Be careful if you try to modify them to fit all three manuals in one file.
* (prog only) paragraph 0.1 has no chapter and is appended to "Contents", which is the same as the normal main index page. (on which the TOC is based)
* I consider these scripts, so errorhandling and verbosity is minimal for now.

Usage of the scripts
* create or download the unfixed docs generated by tex4ht
* In a directory that has the docs in user/ prog/ and ref/ run relinkdocs
* move the user-fixed/ prog-fixed/ ref-fixed dirs to a new dir, and rename them back to prog/ user/ and ref/ (these paths will be visible in the CHM)
* Use the compilelatexchm script as follows:
compilelatexchm prog "Programmer's guide"
compilelatexchm ref "Reference guide"
compilelatexchm user "User's guide"

(The second parameter is the title of the generated CHM, the first is both path (in case of prog: prog/ and base prefix prog<x>,html))

Wow this is great! Thanks!

I just fixed a bug in lhelp that allows your TOC links to work correctly if "#" is in the link name.

Regards,

Andrew

In our previous episode, Andrew Haines said:

I hope it is reproducable over time.

I just fixed a bug in lhelp that allows your TOC links to work correctly if "#" is in the link name.

Some of them could be trimmed. For now I left it original, but I don't know if hiding the next/prev buttons is so useful.

I also saw that some of the appendices only have a "prev" button, not allowing to iterate through them forward. However that seems to be a problem of the original document.

Btw, could you have a look at this:
http://bugs.freepascal.org/view.php?id=13540

and see if you notice anything particular?

Sure, I will try to look after work today. Though I remember being slightly confused as to how the quickref was wrong. The MS reader seemed not to use it so I never fixed it.

Regards,

Andrew

I made some changes and *think* I have fixed the problem in r13476 and r13477. Both the ms reader and 7-zip are happy now. Afaict the quickref section is 100% now.

Regards,

Andrew

http://www.stack.nl/~marcov/doc-chm.zip

Great work !

I d/lded and on my Suse Linux box, the chm is loaded by "Okular"

Same does claim that most of the lines in the "Contents" pages are links and some (e.g. 1.1.6) are not.

But it does not follow the links :(.

Thanks,
-Michael

In our previous episode, Michael Schnell said:

Maybe it stumbles on the labels. I'll try to generate the next batch without labels in the main contents page.

Note that they do work under Windows, so it might be an Okular problem.

In our previous episode, Andrew Haines said:

Good. I'll regen the CHMs today or in the weekend, and also add the fpdoc chms, so that there is a full set. I'll strip some of the labels from the main URLs, to see if that increases compatibility with the various Linux readers.

Marco van de Voort wrote

Note that they do work under Windows, so it might be an Okular problem.

I never used Okular with a chm before, so you might be right.

I'll test with a different chm, soon.

-Michael

In our previous episode, Marco van de Voort said:

I updated the docs, and, for convenience I added the fpdoc based docs and fpdoc.chm too.

The archive is still at

http://www.stack.nl/~marcov/doc-chm.zip

but now swollen to +/- 10MB, however this is mostly due to the fact that I also included the LCL and .xcts. A typical FPC release would be in the magnitude of 4-5MB both in ZIP as unpacked. (compare, doc-html.zip is now 10MB _packed_ and tens of MB's uncompressed)

Changes:
- fpdoc based chms added, as well as fpdoc manual itself, hopefully with crossreferences and fulltext search.
- recompiled everything after Andrew Haines' chm package fixes last night.
- Added a script, fixdocs.sh to the fpcdocs repository which should somewhat automate the generation. Note that it hardly does any error checking.

The rest of my notes are at:

http://wiki.freepascal.org/chm_backend_for_fpdoc#compiling_and_TOC_generation

Marco van de Voort wrote

I updated the docs, and, for convenience I added the fpdoc based docs and fpdoc.chm too.

Thanks Marco!

magnitude of 4-5MB both in ZIP as unpacked. (compare, doc-html.zip is now 10MB _packed_ and tens of MB's uncompressed)

Just thought I would let you know, I downloaded the doc-html.tar.gz, extracted it, and then repacked it using 7-zip. As a solid archive I got it down to 1.9MB!

7-zip has been around for quite some time. Maybe the releases can drop the standard .zip and replace that with .7z

I noticed most of the .tar.gz is even smaller than the .zip archives. Just my 2c worth... :-)

Regards,
- Graeme -

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

We are aware of this.

But .7z is not really a well-established standard. Even FPC doesn't have a handler for it. By contrast, .zip is handled natively on most platforms.

Ease of use in this case supercedes compactness...

Michael.

In our previous episode, Graeme Geldenhuys said:

Depacking a html zip on a slow machine takes over tens of minutes already. 7zip would make it worse.

The whole idea is to get rid of the depacked files all together, and a solid archive is useless as help format.

7-zip has been around for quite some time. Maybe the releases can drop the standard .zip and replace that with .7z

Maybe. Just provide a FPC implementation of the depacker for use in the various installers, and we can test with it. If the memory and CPU requirements are doable, why not?

I noticed most of the .tar.gz is even smaller than the .zip archives. Just my 2c worth... :-)

.tar.gz's are solid in a way too, so that is no surpise in this case.

Marco van de Voort wrote

Depacking a html zip on a slow machine takes over tens of minutes already. 7zip would make it worse.

Hey, it's quicker than compiling FPC. ;-)

The whole idea is to get rid of the depacked files all together, and a solid archive is useless as help format.

True, but I thought I would mention that I used solid archive mode (optional of course) simply so that it could be compared to .tar.gz which is also a solid archive.

Maybe. Just provide a FPC implementation of the depacker for use in the various installers, and we can test with it.

I remember looking into this about a year ago. I used Total Commander with the 7-zip plugin, which is written in Delphi. And yes, it's a native pascal implementation, not a wrapper to the 7-zip .dll's.

I'll see if I can track down the code and see what open source license was used.

.tar.gz's are solid in a way too, so that is no surpise in this case.

Not everybody has fast internet connections and others like me, only have a certain amount of bandwidth available in 30 days. So I would take the extra 3 minutes unpacking the archive any day over the size (11MB vs 1.9MB is a huge difference). But yes, I get what you are saying about getting rid on unpacked help altogether.

Regards,
- Graeme -

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

How you don't get depressed of seeing your TODO list grow by the day is a mystery to me. :(

My current theory is that you rely on the many-worlds interpretation of quantum physics: in each world one of your copies does 1 thing on the TODO list. Only problem is: the many worlds don't converge so the list as a whole is never solved in 1 world :(

Michael.

In our previous episode, Graeme Geldenhuys said:

> Depacking a html zip on a slow machine takes over tens of minutes already. > 7zip would make it worse. Hey, it's quicker than compiling FPC. ;-)

Well, that's why people install releases, so they don't have to :-)

Yes. But the unix case is more difficult even, since there are no binary installers there. So there it will have to wait till the relevant distro's/OSes have 7zip in base.

The whole point of .tar.gz (and the shellscript installer) is that it is always available.

Wouldn't hurt. But mostly worthwhile for windows/dos. Less for *nix and OS X (Jonas, correct me if I'm wrong)

My P233 (that I use for win98/dos compat) did 40minutes to unpack the html docs, and then 10+ minutes to index. Moreover, it is the system with the smallest HD, so the CHM helps there too. And the CHM archive is more 5MB.

The problem, as always in the size discussions, is that you can't be onedimensional and focus on size alone. Then it will just hurt the people with the embedded distro's, heaps of problems mount on the ackward OSes (read: Dos).

And of course people actually seeing such change all the way through after the initial suggestion is another main problem. Most people only want to "fix" their own usecase, and forget about the rest. Think about stuff like:

- the in-pascal decompressor.
- fixing the textmode installer
- fixing all makefiles and related stuff. Also in the other repositories. ( fpcdocs, fpcbuild)
- testbuilding releases. (as I'm now doing for chm)
- being release manager for the release that introduces it, and fixing the inevitable fallout.

Btw, if size is really a problem, consider generating the docs yourself. SVN has low overhead after the first time, and if you have a half decent linux distro (e.g. from a magazine) it is quite doable. Actually, that's how I got involved in docs building (in the nineties with the dreaded latex2html) in the first place. I assume GIT is not that much worse than SVN in this regard. ( :-) )

Marco van de Voort wrote

after the initial suggestion is another main problem. Most people only want to "fix" their own usecase, and forget about the rest. Think about stuff like:

OK, that is a very valid point. :-) Making such a change would have a bit of a ripple effect. Either way, I'll try and track down the 7zip code and see if we can add it to FCL. Baby steps. ;-)

Btw, if size is really a problem, consider generating the docs yourself.

I have tried this before and had to luck. I vaguely remember Michael mention a few months back that he improved the Makefile or something in the docs project. Maybe it's worth trying to build the docs again. I always have a copy of that repository floating around somewhere.

Regards,
- Graeme -

Michael Van Canneyt wrote

How you don't get depressed of seeing your TODO list grow by the day is a mystery to me. :(

Oh I do, but I think I found a way to manage my depression. ;-) I tackle it like I do with Test-Driven Development. Tiny steps! Don't look at sure, keep adding new todo items to the
list, but only attend to one at a time. That way I keep chipping away at the overall list and eventually (I think) I'll get to them all. :-)

of quantum physics: in each world one of your copies does 1 thing on

I stopped worrying about my clones a while back. ;-)

Regards,
- Graeme -