This document is organised into the following sections:-

Remember: When viewing any HTML document, you can always use a menu option to view the source to see how it was done!

Introduction

 This is not a complete beginner's guide to HTML, for that you should look to the Help menu of your favourite HTML viewer. Instead, all that is present here is enough to allow you to update the .html files that make up the SNOMAN Companion.

HTML is a mark-up language, a bit like TeX in that you embed commands in a plain text file. The basic HTML command looks like this:-

<tag_name> ... </tag_name> where tag_name is some HTML tag. For example the tag 'title' is used to put a title in the Document Title box at the top of this window. For this document, the command was:- <title>HMTL: A Beginner's Guide</title> Note: tags are not case sensitive; 'TITLE' or even 'TiTlE' work just as well.

The entire document is enclosed within the tag 'html' and is then subdivided into the two tags 'head', which contains the 'title' tag, and 'body' which contains the rest. To add comments use:-

<!-- ... --> and this can be used to include the EXTRACT *file and *endfile lines. The *file line must include the leading_source keyword so that EXTRACT will allow it to be preceeded by a little HTML. So, to summarise, the overal framework of any .html file in this companion looks like this:- <html><head><!-- *file member=... language=html leading_source library=snoman *file date=... --> <title>...</title> </head> <body> .... </body> </html> <!-- *endfile member=... -->

Headings and Ruled Lines

 Headings, of decreasing levels of prominence, have the tags 'h1', 'h2', ...'h6'. For example:- <h1> This is an H1 Heading </h1> <h2> This is an H2 Heading </h2> <h3> This is an H3 Heading </h3> <h4> This is an H4 Heading </h4> produces:-

This is an H1 Heading

This is an H2 Heading

This is an H3 Heading

This is an H4 Heading

To get a horizontal rule like the one below, use:- <hr>

Fonts

 To make something boldface use the tag 'b' e.g. <b> This is in boldface </b> produces:-

This is in boldface

An in a similar way, use 'i' - italic, 'u' - underline and 'tt' - typewriter

Line and Paragraph Breaks

 To force a line break use:-

<br>

Normally the viewer will disregard line breaks and puts as much on each line as the window will allow - trying resizing the window to see this. To force a paragraph break, use:-

<p>

Note that there is no

</br> or </p> If you want to keep some text exactly as it stands use the 'pre' tag. Its particularly useful as a simple way of making tables:- <pre> Heading 1 Heading 2 data data </pre> produces:- 
  Heading 1    Heading 2
 
   data          data

Lists

 The tag 'ul' produces an unnumbered list where each item has 'li' as it tag. For example:- <ul> <li> This is item one <li> This is item two </ul> produces:-

In a similar way 'ol' produces an ordered list:-
  1. This is item one
  2. This is item two

Links and Anchors

 The most powerful feature in HTML is its ability to connect documents together. In HTML jargon, a LINK is the connection point that points to an ANCHOR . If you click on the link above you will jump to the anchor (the jump is so small that you may not see it unless this text is near the bottom of the window). To define a link, you use the 'a' tag (a is for anchor), invent a name for a link, say my_link, and decide what text will be highlighted. For example, to create a link and anchor within a single document as shown above, the following was used:- <a href="#my_link"> LINK </a> this will highlight the word LINK, which if clicked, will jump to the anchor called my_link. To define the anchor use:- <a name="my_link"> ANCHOR </a> Note that you have to put a # for the link but not for the anchor. The reason for this becomes clear when considering links between documents. If you want to link to another document, say my_other_doc.html, in the same directory, then the link becomes:- <a href="my_other_doc.html#my_link"> LINK </a> So the # acts as a delimiter after the file name. Often, you just want to link to the start of the file and then, as you might suspect, you just omit the # part:- <a href="my_other_doc.html"> LINK </a> in this case there is no need for an anchor at all, every document has an implicit anchor to its start. It is possible to link to documents in other directories by giving the directory as well as the file name or even to link to a document on another machine. This is done by using a URL (Uniform Resource Locator) and is beyond the scope of this beginner's guide (all the companion .html files are stored in a single directory).

Links in SNOMAN documentation

Links from Companion to User/Programmer Manuals

The User Manual and Programmer Manual are available in HTML form:- These are created from the latex source files with the latex2html utility, and are located in separate directories, user_manual and programmer_manual, below the html directory.

It is clearly a useful thing to have hypertext links from the Companion to the manuals but this is not straightforward as latex2html creates a large number of files with nondescript names, eg node32.html. They are also likely to change each time the manuals are compiled into html. However, the natural thing to refer to in a link is a latex label rather than a particular file and this can be done as follows:-

  1. Make sure there is a latex label defined in the section of the manual you want to link to (most sections already have labels) eg, \label{prog_event_loop}
  2. Create a special link in the companion file of the form <a latexref="prog_event_loop" href="user_manual/node167.html"> The Programmable Event Loop </a> The latexref should be the latex label you want to link to. The href will be set later automatically so it can be left blank for now.
  3. Set these links at any time with the SET_COMPANION_LINKS tool set_companion_links.perl -manuals *.html This command should be run in the html directory. The tool works by using the labels.pl files which are generated by latex2html and map latex labels to URLs. They can be found in the user_manual and programmer_manual directories.
Note that:-

Links in Manuals

The latex2html package, used to generate the on-line versions of the SNOMAN manuals, provides some special latex commands which can be used to create hypertext references in the html version of the document. The most useful command is \htmladdnormallink{<text>}{<URL>} which makes <text> a hyperlink to <URL>. For example Note that the `../' was necessary in the URL because the companion files are in the directory above that of the manuals.

Links to Data Files

It is simple enough to add links to titles files (.dat) and SNOMAN command files (.cmd) with the use of relative directory paths <a href="../../prod/run_e_minus.cmd"> RUN_E_MINUS.CMD </a> However, some users may prefer not to use the `prod' directory, but instead, keep everything in `code'. The SET_COMPANION_LINKS tool can be used to switch over such links from prod to code or vice versa. set_companion_links.perl -use_code *.html set_companion_links.perl -use_prod *.html

Go Back to the Snoman Companion Top Page

Highest link so far: 7:- HMTL: A Beginner's Guide Introduction Headings and Ruled Lines Fonts Line and Paragraph Breaks Lists Links and Anchors Links from Companion to User/Programmer Manuals Links in Manuals Links to Data Files