User Prepared HTML files to process
- In AUTO Mode, the toc file is built from the <Hm> statements in the HTML file
- In Non-AUTO mode, <!.toc> statements must be manually added to the
HTML files
- NOTE: It appears that the Helpviewer ONLY displays files ending in
.html or .htm
See the following files (possibly in the /html2toc directory)
- buildtoc
- Script to process html2toc.html for Helpviewer use
- html2toc.html
- The HTML "source" for the html2toc Helpviewer display
- html2toc.toc and TOC.html2toc.html
- Created after html2toc is run.
-
- These files are used by the Helpviewer.
-
Preparing HTML Files for html2toc
Three items are needed for each Table of Contents Entry
- A level number
In auto mode, this is the Heading Level + 1
In non-auto mode, this is based on the Section number
- A text entry to be displayed in the Helpviewer Contents Pane
- A URL (or anchor point), for the Helpviewer to display
These are generated from the headings in Auto mode.
In non-Auto mode, these are specified in <!.toc...>
statements, and may be generated from data found in the HTML file.
For AUTO MODE
You do not have to modify your HTML files to use this mode.
- Your headings become Helpviewer Table of Contents Items
- H1 is highest level Contents Item (Under "Book Name")
- H2 are items under the previous H1 item
- ...down to default (level 3), or specified by the -a level option
Headings below this level are not used to create table of contents entries.
- It does require some discipline to write in this style!
In this mode, NEW .htm or .html files will be created by html2toc with the name format:
TOC.filename.htm or TOC.filename.html
These TOC.* files are what the Helpviewer will display, not the input HTML files.
See Known Problems for some cautions.
Your source HTML files will NOT be modified.
(But always take precautions to back up your work.)
Example
- Assume that your current directory is /html2toc
- See Example Files (html2toc.html)
- Process html2toc.html with the command:
html2toc -o html2toc.toc -a4 "html2toc Users Guide|./copyright_h2t.html" html2toc.html
- Produces: html2toc.toc table of contents file
And HTML file(the file displayed by the Helpviewer): TOC.html2toc.html
- Requires: File copyright_h2t.html to be in the directory /html2toc
- To display in the helpviewer:
helpviewer -T /html2toc
The helpviewer will automatically access the .toc file you created,
in the directory specified by the -T option.
- The Helpviewer Contents Pane will show
html2toc Users Guide
as the name of the book
copyright_h2t.html will be displayed if that book is selected
For NON-AUTO MODE
- In this mode you will use <!.toc...> statements to identify items to add to the
table of contents file.
- (The <!.toc...> statements are ignored unless the -t option is used):
- These <!.toc...> statements cause entries to be made in the .toc file being generated.
The full <!.toc...> format is:
<!.toc[nn.mm.oo[|title]]>
- This specifies a section number which will be used to place this section in a proper hierarchical relation
with the other sections in this book.
And a title for the section.
- Any sections missing in the hierarchy (eg if section 2.1 is given, but there is no section 2)
will be displayed in the Table of Contents, with the title "Under Construction."
- Example:
- Suppose only these two <!.toc...> statements appeared in the HTML file:
- <!.toc3.4.5|Using the Software>
- <!.toc1.1|Introduction>
- These numbers (such as, 3.4.5) are only used to specify the ORDER and hierarchical relationship of the topics.
- The Helpviewer Contents Pane will display:
Book Name // comes from the "front" of the "book_name" operand
Under Construction // because item 1 is not defined
Introduction
Under Construction // because item 3 is not defined
Under Construction // because item 3.4 is not defined
Using the Software
- When the User requests a jump to a particular topic, it will jump to the
anchor defined ( with <a name=...> or <a id=....>) PREVIOUSLY listed in the HTML
file.
Shortcuts
There are shortcut forms of the statements. These get their information from
the previously encountered HEADING (<Hn>) statement:
- Form: <!.toc>
- The previous heading statement must be of the form:
nn.mm.ooA Title, as <Hn>5.3.4title</Hn>
The Section Number and the Title will come from this heading statement.
- Form: <!.toc1.2.3>
- The previous heading statement provides the title
The Section Number comes from the <!.toc> statement.
- Form: <!.toc2.3.4|Section A>
- Both the Title and Section Number come from the <!.toc> statement.
The previous heading statement is ignored.
In all cases the URL or anchor will be derived from the last encountered (as html2toc reads the current input
file) anchor statement defining a name= or id=.
Thus if we had:
<A name="running"></A>
<H1>1.2.3 Running the Software</H1>
<!.toc>
The entry in the .toc FILE would be:
level_number|Running the Software|./filename.html#running
Note the level number (based on the 1.2.3) is determined
when all of the HTML files are processed by html2toc.
My experiments show that the Helpviewer does not like the above anchor format;
you would probably have the following in your HTML file:
<H1><A name="running">1.2.3 Running the Software</A></H1>
<!.toc>
Note: In Non-Auto Mode html2toc will create a temporary file, html2toc.tmp, in the
current directory. It will not erase this file, but you may, if desired.
- Beware of anchors that you put in your document!
If they refer to any file that html2toc processes, the references may be wrong.
For example if an HTML anchor references
href="myfile.html#something", and myfile.html
was a converted file, the displayable file name will be TOC.myfile.html. However,
your HTML file will still reference them as myfile.html.
This will be corrected in the released version.
The current solution would be to manually
edit your HTML references to point to the converted files(TOC.myfile.html).
Local references (of the form href=#whatever") do not need to be changed.
References to files (image, HTML, or whatever) which have NOT been converted are also OK as is.
- Heading and Anchor References must exist on single physical lines.
You will get errors (see Errors) in html2toc if, say <H1> is on one line
and its corresponding </H1> is on another.