Help Builder HTML formatting

Help Builder focuses on separating content from the presentation to make it as easy as possible for you to create your help content. The majority of formatting is handled by the HTML Help templates while you can for the most part just type plain text with the occasional HTML markup.

Help Builder uses a unique way to handle HTML formatting. There are two ways that HTML is formatted when editing text:

Formatted HTML Text is converted into HTML using standard editing conventions. Line breaks are respected and any extended HTML tags such as quotes and angle brackets, ampersands etc. are automatically converted into the proper HTML markup for display. Any HTML tags should be entered using the the appropriate HTML tag format ( <>). This is the default for all editing fields.

Example:
```
This is some plain text.
  This is some plain text with **marked up bold text**.
  
```
The <RAWHTML> tag
You can also force text to be treated as totally unformatted or raw HTML. This means line breaks in the text are not converted and all text is treated only by HTML rules. The <RAWHTML> tag is used to wrap any HTML you would like to remain unformatted. If you want the whole topic to the be unformatted you should wrap the entire topic in the < RAWHTML > block.

Example:
```
This is formatted HTML and line breaks are automatically inserted into the text and displayed.

  <RAWHTML>
  This text is not marked up in any way.

  More text here all left alone by the HTML formatting engine.
  This line break will not break because no 
 was inserted.
  
  
    test
    asdasd
  
  
  </RAWHTML>
```

More formatted HTML text may be placed below. Again Help Builder marks up this text with linebreks and HTML invalid characters are expanded to entity entries

The reasoning behind this scheme is fairly simple: Most text in a help topic does not need special formatting so Help Builder simply lets you type plain text in a fast edit box. HTML formatting is difficult to type in a text editor and hard to read. So, to simplify matters the formatted mode allows you to work the way you normally type with the ability to insert markup using the HTML formatting toolbar.

To make formatting easier you can take advantage of the HTML formatting toolbar which is active whenever you type into an editing field. It's a good way to see how the formatting is accomplished when HTML markup is inserted into formatted HTML text. Note: don't use the formatting options when you're typing raw HTML - the markup currently does not take into account pure HTML tags and only works on formatted text.

Style Sheets and Templates

To handle topic presentation and display Help Builder relies on HTML based templates and a Cascading Style Sheet. If you're familiar with HTML you'll be right at home customizing your help projects.

Every topic type in Help Builder is mapped to a matching HTML template that handles the display of the topic. Since topics are basically made up of a number of fields you enter data into these HTML templates are used to expand these fields into the resulting topic's HTML output. Templates are ASP like pages that use the Help Builder COM object to generate the individual output for each field. The final page is turned into a plain HTML document which is then compiled into the Help file. This dynamic display occurs everytime you preview a topic and when the help file is built into a CHM file.

The Templates are basically plain HTML documents and include markup similar to the following:

<body topmargin="0">
<TABLE WIDTH=99% BORDER=0 BGCOLOR=#EEEEEE><TR><TD ALIGN=CENTER>
<h2><%= TRIM(oHelp.oTopic.Topic) %></h2></TD></TR></Table>
<br><p>
<div class="body"><%= oHelp.FormatHTML(oHelp.oTopic.Body) %></div>
<p>
<hr>
(c) West Wind Technologies, 2000 - <small>Last Updated: <i><%= TTOD(oHelp.oTopic.Updated) %></i></small>

You may notice that several styles are used with various standard HTML tags. For example, by default the PRE tag is using a style that shows code as Red Text on a grey background. The H1 and H2 tags have also been set up with style tags that automatically format the text into a standard style. All of these options can be overridden by changing the WCS templates and the wwHelp.css stylesheet file that controls the overall look of your Help Project. You can do this using the Topic Type and Template Editor.

in the template directories. You can override the master template (wwHelp.wcs) in the install directory or your own copies of these tempates that you can create in your project directory's TEMPLATES path. Note that each topic type (HEADER, TOPIC, CLASSHEADER, CLASSMETHOD, CLASSPROPERTY etc. plus any that you add on your own) can have a matching template. So if you create CLASSMETHOD.WCS this template will be used on all ClassMethod topics. See the templates topic for more detail of how the hierarchy of template overriding works.

To apply style sheets to text you can use the Styles option on the HTML formatting toolbar. The styles drop down includes all of the styles available for the current template and allows you to apply them to the current selection using SPAN tags.

Help Builder HTML formatting

HTML Formatting toolbar

Style Sheets and Templates

See also