Making HTML help files

On the last section, we saw that help files can be presented in a number of different ways.  As a quick reminder…

1. A simple text document
2. Help window within the software (no separate documentation)
3. HTML help file read through the customers HTML browser
4. A help file which is read through a dedicated help file reader on the customers machine
5. A link to help file on the internet

The focus of this section will be options 3.  Once you understand how to do 3, the process of doing 4 and 5 will be a lot easier.  In fact, in order to do 4 and 5, you need to be able to do 3!  For this reason, this section is well worth a read.  Might as well get started!

Here are the basics you need to know first (please do not feel offended if you already know this)

• HTML stands for HyperText Markup Language and it can be thought of as a ‘programming language’ that allows you to format contents of Webpages using Tags.
• There are tools (HTML editors) that will automatically produce webpages for you, i.e. you do not need to know any of the HTML rules
• Even though HTML editors exist, it is important that you DO know some of the commonly used Tags
• Webpages that you create can also be opened using your own computer, i.e. you don’t need to ‘put it on the internet’

To get started with this tutorial, you need to have two things (both of which are free, yeh!)

1. A HTML editor will mean that you do not have to create pages from your non-existence HTML knowledge - if you do not already have HTML editor, download PageBreeze.  If you download PageBreeze, please install it now.
2. You will also need the example HTML pages I have prepared.  This is in the demo pack which you can download from the introduction section.  Unzip this file and browse to the ‘Help file’ folder.  Ignore Help.chm, TOC.hcc and Help project.hhp for now (we will deal with these files later)

My advice is this… have a look through all of the files within the ‘Help file’ folder (apart from the ones I have asked you to ignore).  To look at and edit the HTML code, open the htm files with PageBreeze.  To view the page, use your web browser, e.g. Internet Explorer or FireFox.  If you do this, you will quickly understand how to produce HTML files and work PageBreeze.

Below, I will give you some info/pointers/advice.

We will first open index.htm and inspect a few things from it.

• Firstly, a quick advice - You should use index.htm as the name for your homepage.  This is because all browers look to this file as the page to display first… e.g. when you type a web address on a browser (www.google.com), the browser will automatically take you to index.htm on the server.
• Look at the contents of this file! you will see a links to all the other help pages.  If you open the other help pages, you will see a link to index.htm.  This will mean that the user is always able to access any help file without exiting the browser and selecting a file to open (this is actually the main limitation that can be avoided by creating a single help file - considered in the next tutorial).
• HTML files are built up of Tags.  Tags that work on a block of text start with < ’something’ > and end with </ ’something’ >.  Each Tag does something different.  Note some examples as follows…
• <H1> Tag - defines Headding 1 (i.e. the biggest heading of the page)… as an example, you can use this Tag to format a page title.  Other heading Tags include <H2> and <H3>
• <blockquote> Tag - tabulates a chunk of text.
• <p> Tag defines a paragraph
• <a> tag makes a chuck of text into a link… notice how the text ‘Color Crazy overview’ is made into a link by using ‘<a href=”overview.htm”>Color Crazy overview</a>’ - i.e. clicking on that link will open the file ‘overview.htm’
• Towards the end of the HTML file, you will see the following code ‘<p>&nbsp;</p>’ what is this? - you may already know that all alphanumerical characters have their own decimal number… they also have their own HTML codes.  The above represents a space character.  Other character codes can be viewed at http://www.ascii.cl/htmlcodes.htm.
• Notice how we display an image by using ‘<img src=”images/logo.png” alt=”logo” width=”50″ height=”44″ />’ - we don’t actually have to define the width and the height unless we wanted to resize an image.  The ‘alt’ option is the text that is displayed whilst the image loads or if it is not found or for any reason, the image is not displayed on the browser.
• Notice <hr /> - this Tag basically draws a straight line on a webpage… useful for dividing sections on a page.
• Notice ‘<link href=”images/style.css” rel=”stylesheet” type=”text/css” />’ - what is this?!  We will come to this below.

As promised, we have come to it…

Look carefully at index.htm in your web browser and then to the HTML code on PageBreeze. Note that the page is actually black but there appears to be nothing in the HTML code to define the background color.  Also, look at the word ‘Contents’… its in italics, but the HTML code does not define this.  What is going on?!  - We are using something called a Stylesheet.

• What is a Stylesheet? -  It is simply a file with a collection of formatting attributes meant to be applied to a paragraph, a group of characters, or page elements.
• A file? - Indeed! the file has the extension .css (Cascading Style Sheets) and in our demo, it is found in the folder ‘\images’ within the ‘Help file’ folder and it is called style.css
• How does the file index.htm know to use the image\style.css file? - by using ‘<link href=”images/style.css” rel=”stylesheet” type=”text/css” />’ in the Head section of index.htm.

Now open style.css using any text editor (notepad is fine, so is PageBreeze).

• The first line starts with H1. what does this mean? - it means that the formatting options contained within  ’{’ and ‘}’ applies to H1 tags only (see above for what a H1 tag is).  Similarly, we have also formatted the paragraph Tag the ‘Li’ (list) Tag the ‘Body’ (i.e. the page) and the links (’a’ tags).  Note that the ‘a’ tags are different in the sense that their formatting changes based on, e.g. whether the mouse is hovered over them and whether the link has already been visited or not.
• You can also define formatting styles which are not assigned to recognized HTML tags.  To do this, simply add ‘#’ to the front of the style name.  An example is ‘#contents’.   I have used this in the index.htm file like this… ‘<p id=”contents”>Contents</p>’.  This is useful to do because you may sometimes want a certain section, e.g. in this case , a paragraph, to appear differently formatted from the other sections (in this case, other paragraphs!).  Notice how I have also done this with the back_to_contents links used in other pages.

Thats all there is to it!  Please feel free to play around with the downloaded files and if necessary, to use them as templates for creating your own help pages.  One question which may have is, how do you open the HTML file from your own application?  The solution is to use the ShellExecute command.  In Visual Basic, I use:

ShellExecute (me.hwnd, “open”, ‘path to the index.htm file’, vbNull, vbNull, 3)

If you plan to put up the help files you have created on the internet then it will need more work, i.e. you will need a server a web-address and a FTP software to upload the files onto the server. We will cover the issue of getting all these things later, but for now, just as a reference, you can also use ShellExecute to call a webpage using the following line (e.g. for Google.com):

ShellExecute (me.hwnd, “open”, “http://www.google.com”, vbNull, vbNull, 3)

If those fails, it’s because a browser isn’t set up to correctly open pages, the following should load internet explorer:

ShellExecute (me.hwnd, “open”, “iexplore”, “http://www.google.com”, vbNull, 3)

This article has no doubt thrown you whirling!  Webpages can be simple and as complex as you need it to be.  Use the above brief introduction as you reference guide.  Next, we will be looking at how put together all the separate HTML files into a single help file.