TSE: How to convert TSE help .hlp files?

[knud van eeden]

TSE: How to convert TSE help .hlp files?

Hello,

a. I checked the 'help' sub directory in TSE, where there are 2 files default:

1. compile.hlp

2. tsehelp.hlp

b. Opened these in TSE, but it shows these are binary files (see screenshot)

   and look like they are (zip) compressed or similar.

c. Now Carlo (Hogeveen) and as far as I known e.g. Chris (Antos) have e.g. converted successfully these .hlp files.

Contents of TSE's compile.hlp file

https://ecarlo.nl/tse/files/compile.html

https://ecarlo.nl/tse/files/Hlp2txt.zip

Hlp2txt.zip

v3.0.3

17 Sep 2022

Windows TSE PRo v4 upwards,

Linux TSE Beta v4.41.12 upwards

Hlp2txt generates a readable help file from TSE's built-in Help system, either in HTML or PLAIN TEXT format, and either using UTF-8, ASCII or OEM character encoding.

The main changes for version 3 are:

In the HTML version of the manual links are now identical to those of TSE's Help. This means no more missing links and no more excessive linking wherever a topic's name, word or phrase is used.

The HTML manual now has actual bold and italic text where the Help uses colors for these.

The manual now includes the Help's InfoBoxes as "Info->..." topics.

The manual now also includes those not-indexed topics that are linked to from indexed topics.

The tool no longer supports the unused "Word" and "Generic" text formats. You can still open the full HTML file in Word.

Macro programmers: Technical notes about what I discovered about the insides of the Help are described in the source code in a "technical info" section, and here on the site are two tools that helped with this discovery and with verification of its correctness.

v3.0.3 Fixed incompatibility with TSE's '-i' command line option and the TSELOADDIR environment variable.

d. I checked hlp2txt.s, but did not immediately where was looked for.

e. Now my question is how can one convert these .hlp files to text?

   Any information about the .hlp format (e.g. Backus Naur Form, RailRoad diagram, ...)?

   Possible (easy) algorithms to use for the conversion from .hlp to text?

   Maybe (simple) examples of conversion of .hlp to text are available somewhere?

   Documentation somewhere about this conversion from .hlp to text?

Just some general information about this would thus be nice to know.

Thanks

with friendly greetings

Knud van Eeden

[Carlo Hogeveen]

Knud,

By now I know a lot about TSE’s Help system, but still mostly from an outside viewpoint.
As far as I glimpsed, a simple explanation of its insides is not possible.
I did glimpse , that the reason the .hlp files look binary, is that they are compressed with a custom program we do not have access to.

I can start you off with an intro to the outsiders algorithm that Hlp2txt uses to convert tsehelp.hlp to text or HTML:
Interactively TSE’s Help allows us to copy a Help topic with the <Grey+> key.
Hlp2txt uses PushKey()s to get a copy of TSE’s Index.
Then for each topic it finds in the Index, it uses PushKey()’s to get the topic.
You can copy/paste a plane text version of each topic this way, without any links and formatting.
Trick: Retrieving a topic also loads it in TSE buffer 8 *with* link-codes and formatting codes.
This buffer can be safely viewed with my "Hidden" tool or edited with Semware's "buffer" tool.
What these codes are can be found in Hlp2txt’s technical documentation.

My upcoming eHelp extension, an “in development” version of which is on my website, takes this a step further.
It contains a separate tool that creates one partially-XML-like tsehelp.ehelp file that contains both tsehelp.hlp and compile.hlp, and contains help-elements that cannot be found in TSE’s Help Index, like “redirects” and help topics for menu-options.

I stop at spilling technical details, because I gather that was not your question.

Given the above approach, I have not needed or tried to reverse-engineer the .hlp format, with the exception of some very specific technical detail that I needed, to understand why TSE's Help works differently for the Index topic.

Carlo