TOC mods instructions

Top  Previous 

 

TOC mods for H&M

 

This program tocmods.exe will modify the TOC file from H&M Webhelp to add mouse-over tooltips and/or icons to any TOC item, and to divide the TOC into sections with coloured backgrounds and headings.

It is suitable for use with all H&M skins or none, except the Premium Pack Version 3 skins.  

The program is a simple Windows executable. It doesn't need to be installed. Save it anywhere you like on your computer or a memory stick and just run it.

It is not signed, so you will need to click through the usual Windows security warnings when you run it the first time.

I have not included a DPI-aware manifest, so on a 4K screen it will be fuzzy until you manually change its compatibility settings to over-ride the Windows High-DPI scaling.
 

DOWNLOAD FROM: http://85a.co.uk/toc_mods/tocmods.exe

 
At present it is a manual program with a user interface as below. I will shortly also create a silent version which can be added to the H&M publishing tasks to run automatically after publishing your project.

On start-up it looks like this:
 

tocmods0

 
As a starting point you need a txt file containing the path to your project output folder on a single line. You can create that in any text editor, or use the simple editor in this program.

1. To do the latter, read the terms of use, and then click the [clear this] button.

2. Enter on the top line the path to the project output folder. This can be copied and pasted from the Compiler Messages in H&M after publishing your project to Webhelp. Make sure it is the top line with no blank lines above it.

For example:
 

tocmods1

 
Leave H&M running with the project displayed in your browser via its mini-server, so that you can see the effect of your mods as you make them.

3. Then click the [3. save mods] button. You can save the file anywhere you like with any name you like, but it would make sense to call it something like project_name_toc_mods.txt and put it in your project folder.

If you prefer to use some other text editor, do the same thing using that editor.


Now ready to start.

4. Click the [1. edit mods] button and re-open the file which you just saved.

Using the path on the top line, the program will find your TOC file and create a list of topic file names/topic IDs, each one followed by an "=" character, like this:
 

tocmods2

 
5. For each topic add the required mods for that topic after the "=" character. See below for the mods format. For example you might add:
 

tocmods3

 
The program can be maximized to full screen if you need more space. If you prefer to do the work in some other text editor, you can copy and paste from this simple one as you wish. Right-click on it for options.

6. Click the [3. save mods] button to update your mods file, or create a new one.

When this file is next opened, the list will be re-created from the TOC, showing any subsequent new topics or re-ordered topics. The mods will remain linked to their respective topics (provided the topic ID hasn't been changed).

7. Click the [4. modify TOC] button once only to make these changes to your TOC. Refresh your browser to see the effects.

8. If not to your liking, click the [restore original TOC] button before trying again.

9. Every time you re-publish your project, it will be necessary to re-run this program, open the mods file, and modify the TOC. This process can be automated by adding the silent version of this program to the H&M Build Events.


Mods format:

The mods for each topic item is a string all on one line divided into 4 fields. The fields are separated by pipe characters "|" (vertical bar characters - Shift+Backslash, keyboard bottom left).

The string is made up as follows:

tooltip text|icon file name|css for new background section|html for a heading

If it is desired to omit one of the fields, enter the corresponding number of preceding | characters accordingly. Trailing | characters are not needed. So for example to add a tooltip and insert a heading, you would use:

tooltip text|||html for a heading

Or to start a new section only, you would use:

||css for new background section

(The red colour is for clarity here, the file is in plain text.)

1. The 1st field tooltip text can be any text you wish, but must not contain a | character.

2. The 2nd field icon file name should be the name of an image file. Don't forget to add it to your Baggage files if it is not already part of your project. The file name must not contain a | character.

3. The 3rd field css for new background section is the CSS for an HTML <div> element to create a coloured section beginning at this topic item. The CSS must not contain a | character. Enter only the CSS, do not enter the <div> element tags.

For example:

   background-color:yellow; border-top:2px solid gray; margin:0px; padding-top:6px; padding-bottom:4px;

starts a new section having a background colour of yellow (note spelling of color) -- sets a top separator line as a solid grey border line (note spelling of gray), 2 pixels thick -- sets a zero margin around the section -- inserts some spacing below the top border line as 6 pixels of top padding -- and inserts 4 pixels of spacing below the bottom TOC item in the section.

If you are not familiar with CSS, simply copy and paste the above line and change the settings without changing any punctuation. A full list of the pre-defined colour names is at: https://htmlcolorcodes.com/color-names/

To terminate a section simply start another one, or if that's not wanted end with a 3rd field of a single "/" slash character on the subsequent TOC item.

4. The 4th field html for a heading is the full HTML to be inserted above the TOC item. Typically to create a section heading. It would normally be a an HTML list item, i.e. an <li> element. The HTML can contain a visible | character if needed.

For example:

  <li>Methods</li>

would insert a heading in the same font as the TOC items above the TOC item.

Or:  

  <li style="font-style:italic; font-weight:bold; font-size:21px; color:blue; padding-bottom:3px;">METHODS</li>

would insert a bold italic heading, with an extra space of 3 pixels below it.


So for example this mods string:

    about this app

would simply add a mouse-over tooltip of "about this app" to the TOC item.

or this mods string:

    full details of first method||background-color:green; border-top:1px solid black; margin:0px; padding-top:5px; padding-bottom:5px;|<li>Methods</li>

would add a mouse-over tooltip "full details of first method" to the TOC item, not add any icon, start a background green section behind the TOC item, having a thin 1 pixel black top separator line with 5 pixels of spacing below it, and insert a heading "Methods" above the TOC item.

Note the double "||" characters where the icon is omitted. Remember that it must be all on one line, even if not showing that way here.

Martin.