Advanced HTML TOC 2.0
www.zzee.com | Index | You are here: Contents > 5. How program creates TOC

5. How program creates TOC

Program scans header tags in HTML file and build according TOC tree according to specified template. Each TOC item is hyper-linked to an according <h> tag.

5.1. Where program inserts TOC

www.zzee.com | Index | You are here: Contents > 5. How program creates TOC > 5.1. Where program inserts TOC

The program inserts TOC into the destination file right after  tag, or if none found, after <body> tag, or if none found, before the first <Hx> tag, or if none found, in the beginning of the file.

If you have special place where to insert TOC, put there  tag. All header tags prior to  tag are not processed and excluded from TOC. Note that this tag is case insensitive. If you have more than one such tags in the file, just the first of them is significant.

5.2. How to undo changes made

www.zzee.com | Index | You are here: Contents > 5. How program creates TOC > 5.2. How to undo changes made

Use Menu > TOC > Clear TOC and all HTML code inserted. This clears the following:

TOC inserted
Named anchors generated (within <h> tags)
Numbering inserted (if Process numbering in decimal notation is checked)

Note that clearance of named anchors generated and inserted numbering are performed in accordance to Header tag range settings.

5.3. TOC tree and precedence of tags

www.zzee.com | Index | You are here: Contents > 5. How program creates TOC > 5.3. TOC tree and precedence of tags

The tree is created based on relative relationship between two neighbor header tags. Their precedence is straight: the more important tag has the precedence over less important one.

Example 1. If you had these headers:

<h1>Header1</h1>
<h3>Header2</h3>
<h2>Header3</h2>

Then TOC generated would look like follows:

Header1
- Header2
- Header3

Where Header2 and Header3 tags go to the same level, despite that Header2 is less important tag than Header3.

Example 2. If you had these headers:

<h1>Header1</h1>
<h2>Header2</h2>
<h3>Header3</h3>

Then TOC generated would look like follows:

Header1
- Header2
  - Header3

When you create TOC from multiple files and select to put page titles to TOC, then <title> tag takes precedence over any <h> tag.

5.4. Correct header tags layout

www.zzee.com | Index | You are here: Contents > 5. How program creates TOC > 5.4. Correct header tags layout

It is recommended that HTML file has header tags laid out correctly. It means that there should not be any header tag that takes precedence over the very first header tag. Examples:

```
<h3>Header1</h3>
<h1>Header2</h1>
```
This is laid out incorrectly as Header2 has a precedence over Header1.
```
<h2>Header1</h2>
<h3>Header2</h3>
<h2>Header3</h2>
```
This is laid out correctly as no tag takes precedence over Header1.

5.4.1. Side effects of incorrectly laid out header tags

www.zzee.com | Index | You are here: Contents > 5. How program creates TOC > 5.4. Correct header tags layout > 5.4.1. Side effects of incorrectly laid out header tags

When you created TOC from multiple files, and didn't put page titles to TOC, and inserted local TOC into each source file, and if you had incorrect header tag layout, then TOC generated, which was inserted into each source file, might have had wrong HTML code. Total TOC which was inserted into the destination file would be correct anyway.

To work around, select put page titles to TOC. And as title takes the precedence over any header tag, layout becomes correct. Another way is to use a template that is not based on container tags, such as Indent based tree. Or you can insert  tag after "hung" heading, to suppress its processing by the program.

In any other situation, for example, if you build TOC for a single file, incorrect header tags layout should not lead to any errors.

5.5. Named and hyperlink anchors

www.zzee.com | Index | You are here: Contents > 5. How program creates TOC > 5.5. Named and hyperlink anchors

To link TOC items to <Hx> tags named anchors are used. They are located inside <h> tags. There are two possible situations.

If you already have a named anchor inside <h> tag, then program uses it. Example:
```
<h1><a name="pet">Robot-pet interaction</a></h1>
```
Program leaves <H1> tag as is and creates this TOC entry:
```
<li><a href="#pet">Robot-pet interaction</a></li>
```
Note that the program uses the first named anchor it encounters inside <Hx> tag.

If you don't have a named anchor in <Hx> tag, program creates it. Example:

	<h1>Robot-pet interaction<h1>

Program modifies <H1> tag like follows:

	<h1><a name="zzee_link_6_1001933000">Robot-pet interaction</a></h1>

And creates this TOC entry:

	<li><a href="#zzee_link_6_1001933000">Robot-pet interaction</a></li>

If building TOC from multiple files, program always creates relative paths. That's why it is required that all source and destination files are located on the same drive (such as "c:\").

5.6. Generated named anchors format

www.zzee.com | Index | You are here: Contents > 5. How program creates TOC > 5.6. Generated named anchors format

To enable proper visual formatting, program can insert user-defined attributes into named anchors generated. You can use this possibility to provide font, color and other style attributes to these tags. You set this in Format Options tab > Named anchors' attributes edit box.

Note that existing named anchors are not modified.

5.7. Where numbering is inserted

www.zzee.com | Index | You are here: Contents > 5. How program creates TOC > 5.7. Where numbering is inserted

If you process numbering, then it is inserted into each header tag that falls into specified range. Numbering is inserted right after <Hx> tag.

Example. If you had the following header:

<h2>Old <a name="money">Moneys</a></h2>

then after processing it might look like:

<h2>3.4 Old <a name="money">Moneys</a></h2>

We can not insert numbering inside named anchor as there might be text or other tags before named anchor tag after opening <Hx> tag like in the above example in the other headers, and therefore it could lead to a style difference from heading to heading. Thus to insure consistency, the program inserts numbering right after <Hx> tag.

Note: if you processed TOC with wider header tags range and inserted numbering, and then re-built TOC using more narrow header tag range, then old numbering remained in those headers that fell outside the new range. In this case you need to clear result of the previous build first and then re-build TOC again with new range of headings.

5.8. HTML [input] compatibility details

www.zzee.com | Index | You are here: Contents > 5. How program creates TOC > 5.8. HTML [input] compatibility details

Internal parser is compatible with HTML 4.0 specification.
Each heading open tag <Hx> should contain according end tag </Hx>. This is the requirement of HTML 4.0 and earlier specifications.
Headings may not be nested. Situation like <h1><h2>Heading</h2></h1> is prohibited by HTML 4.0 specification, which specifies that headings may contain only inline contents.
JavaScript and other script code is ignored. The program doesn't process headings which are created with the help of script.
HTML comments should end in "-->", the program doesn't recognize single ">" as the end of comment and searches for the first "-->" to occur.
The program supports only single-byte character sets. Double-byte or other non single-byte sets are not supported. Note, UTF-8 is a single byte set and should be OK.

5.9. Browser compatibility [output]

www.zzee.com | Index | You are here: Contents > 5. How program creates TOC > 5.9. Browser compatibility [output]

TOC generated and modifications made to the headings are compatible with any browser, even old ones. Certain template styles, however, such as expanding/collapsing tree, require JavaScript and DOM support and therefore supported by modern browsers such as MS IE 5 and Netscape 6.