Html editing for ID Lab users


1. Introduction


Hypertext markup language was developed by a high energy physicist Tim Berners-Lee at CERN in the early 1990's. Here is an excerpt of a description of this history

                          Berners-Lee had been motivated to design the WWW  because
                          he and his colleagues in the high-energy physics                         
                          community were frustrated by computing incompatibilities.
                          Their vast stores of data were difficult to access and
                          exchange due to differing encoding formats and networking
                          schemes....During 1990 and 1991 Berners-Lee develops the components
                          of the WWW system. He works from several criteria: the
                          system must be flexible and designed with minimal constraint
                          so that it is compatible with numerous languages and
                          operating systems; the system must be capable of recording
                          random links between objects; and the system must be
                          constructed so that entering and correcting information is
                          easily performed. The first version of the WWW includes three
                          basic architectural principles that aim to accommodate these
                          criteria. The first is called Universal Document Identifier
                          (UDI), an address scheme for pointing the system to a
                          particular location within the WWW information space. UDIs
                          are later renamed Universal Resource Locators (URLs). The
                          second element is Hypertext Transfer Protocol (HTTP); it
                          serves as the protocol for accessing data and traversing
                          hypertext links. Hypertext Markup Language (HTML), a
                          documentation code designed to resemble the existing and
                          widely used Standard Generalized Markup Language
                          (SGML), is the third principle.

Here is a comprehensive description of the nitty-gritty of the language itself, if you are a masochist:
A Beginner's Guide to html


The bottom line is:  html and the worldwide web were created for physics, and the fundamental features of it are still a very effective environment for computational physics, so it is a part of our course.

2. A simple html editor: SeaMonkey, and some exercises

SeaMonkey is a freeware html editor and is available for your home PC, and I recommend that you get it. It works under both unix/linux and Windows.

\
The command above should bring up the browser window. There are icons on the base, or a file menu that will allow you to start the "composer" window (the pen and pad icon at lower left will also do it). Start up a composer window. You may want to use the browser now to look at this file. You can use the select and paste function of your mouse to copy the text of the link from the other browser if you wish.

Once composer opens you will see a blank page, with tabs at the bottom. Click on the html source tab. You should see about a dozen lines of stuff like "<html>" and <head>" etc., which is the actual html formatting of your document. Hopefully you will never need to look at this stuff again. Go back to the tab marked "normal" and type in a title for your document, lets use an example from my PHYS305 (computational physics) class:

A study on Series Summation Approximations for pi

There is usually no good "greek" symbol font in html (and many browsers couldn't handle it if there were) so for now we will just use the word "pi".

You can preset the heading to a "title" format with a pulldown at the left, or just select it after the fact with your mouse and change it. The editor should be pretty familiar to you if you use MS Word.


Select "heading 3" from the left pulldown, and make yourself a quick outline (these are just suggested headings):

1. Introduction

2. Series approximations for Pi

3. Computational approach for this study

4. Results of computation

5. Analysis of results

6. Conclusions

3. Adding links

You add links by selecting the text of your link and using the "link" button at the top. Here is a link to the top of this page (try it):
to the top...

Add a set of links just below your title that give the contents of your document. Just repeat the headings in normal text size, then select each one successively and link it using the "link" button. You will need to expand your link menu using the "more properties" button in order to see your heading as available links. To link to an outside file or document, you need to give the exact URL as the link text in the window provided.

Once you are done with this, create a new local directory in your home area, called html, and save your file as PiCalc.html in this new folder.  (The command to make a new directory is "mkdir "). Now use your mozilla browser (probably minimized from before) with the "open file" command on the file pulldown menu to view your new html document. Try the links.

4. Inserting images

To insert an image, first locate the image file you want to put in and verify that it has a type that is easily viewed by browsers--I suggest either Joint Photo Experts Group (.jpeg or .jpg), Portable Network graphics  (.png), or GIF (graphics interchange format, .gif) since these seem to be used by all browsers. 

If the file is not in this format (not a problem for .png of course), unix command "convert" (from the "Image Magick" package) can usually deal with it: just give it the input and output filenames with the output suffix one of the above (.jpg is nice since it is compressed already, also .png).

Just for fun, try converting your file:

$ convert myfile.png test.jpg

Check it by using the "display command:

$ display test.jpg

which will bring up an image of the file. You will note there is a lot of blank space that you won't want in your html. So you will crop it out. Click your mouse within the image window and a popup menu should appear. Click "transform>crop" and your mouse cursor will be enabled to drag a box around the portion of the image you want to save. Drag from one diagonal corner of the save box to the other, and then click the final corner when you think you have it set right. If correct, then click "crop" and your image will be cropped. You then have to save it through several dialog boxes (it will overwrite your old image if you use the defaults--so be careful).

If you don't like the quality of the jpg image, you can improve it somewhat  by using the "quality" flag on convert (good only for jpegs):

$ convert -quality 1000 mtfile.png test.jpg

It is difficult for any network imaging to reproduce the print quality of postscript. Later on we will be using primarily postscript for printed reports, so don't be surprised if your images do lose some resolution. You may want to use gnuplot to produce both types of output eventually.

Once you have an image you like, to insert it into your html, you just position (with a mouseclick) the cursor where you want the left edge of the image to land, and use the "image" button, which brings up a self-explanatory menu, and even allows you to browse for the file if you want. You can then center it as if it were text, and use a centered text entry at the bottom of it to create a figure caption.

Do this on your html test file that you have created above.

Images can be expanded or shrunk by using the "more properties" button on the composer "image" dialog box. This will give you options to change the size of the displayed image.  Shrink your image down by a factor of two using this method, and then save and view it with your browser.

4.1 A sidebar on Image Magick

The "Image Magick" commands encountered above are also available when you use the "xinit" command to enable the Xwindows environment on Cygwin on your home computer if you have installed it. Image Magick is a very power package of image manipulation tools. (You can even use it to create mpeg movies on your PC!). Take a look at the ImageMagick website for more information, or use "man   ImageMagick" (one word) for more information from a command line on your pclab or home pc cygwin shell terminal.

 

5. Equations 

There is no equation editor in Mozilla Composer. In fact there are really no easy-to-use equation editors for any html editors that I know of. If you are familiar with Word's equation editor and have access to it, I have heard that it can save to html format, but I have not had good luck with it, and (why am I not surprised?) it tends to not work well for any browser other than Internet Explorer.

There are some different text forms, fonts, text styles, etc, available in composer, including superscripts and subscripts, and these can help with many simple equations. Take a look at the "Format" pulldown menus at the very top of the composer toolbars.

To have nice equations that cannot be done with simple edits, you will need to first generate them in another program, then save them and convert them to JPEG or PNG for insertion as images. This is a bit painful but at the moment it is the only good solution for  equations that just cannot be expressed well with standard keyboard characters.

5.1 Equations with HtmlMath

Because of the lack of an equation editor, Professor Peter Gorham, who taught this course previously, wrote a shell script (a unix program) called HtmlMath which can be downloaded and used on your local computer for most html equations. It is based on LaTeX equation formatting, which will take some getting used to. Since we will be using it later on for report preparation, it is the preferred way of getting equations for now. Right-click on the link above and use "save link target as" to get a file of the same name in your "work" area. You will then need to change this file to have execute permission, by typing

chmod a+x HtmlMath

Then you run the program by typing a command such as this:

./HtmlMath 'R|E(\omega)|=\sqrt{2\pi}\mu\mu_0 Q L f \sin\theta e^{-(kL)^2(\cos\theta-1/n)^2/2}'


The prepended "./ "is needed to call the program from your local directory. The expression in single quotes is an equation. Once you enter this, some stuff will be printed out, and after 10 sec or so, you should see a window pop up with this:

Here is another one:

./HtmlMath '\frac{x^n-1}{x-1} = \sum_{k=0}^{n-1}x^k'

And the result:

If this is too large for what you want, you will probably have to mess with HtmlMath directly to change it, or alternatively, try using ImageMagick to edit the image file and change its size directly.

Latex has a lot of syntax requirements for math, a summary tutorial can be found here (see chapter 4). Try out some different equations of your own to get a feel for it, and don't forget the single quotes on either end.

5.2 Equations with Naturalmath

A very simple online equation editor, based on similar LaTeX processing to HtmlMath, is available from the math department at the University of Missouri, called Naturalmath. This site provides an interface that allows you to type in equations in a simple text format. The interpreter at the site then converts this to a  PNG or GIF format that you can save directly from the browser window, or download via a link. Note that the LaTeX commands for Naturalmath are slightly simplified compared to actual LaTeX and this does limit the usefulness somewhat.

Type the following commands into a NaturalMath window on your browser, using the link above:

Gamma (z) = integral from 0 to infinity t^(z-1) e^(-t) dt

z! = Gamma (z+1)

Now click submit, and when you get an image of the equation,  click with your LEFT mouse button on the "image" link in the NaturalMath window, or directly on the image itself, and select "save link target as" to get a popup dialog box which will prompt you on where to save your image. You will probably want to rename it something simple like "gamma.png" instead of the "afile-2004-01-27-003--8560-111.png" that it will give you as a default!

Now insert this image into one section of your html file from above, just to see how it will look. Save and view (hit reload) with your browser.

The format for naturalmath is a bit tricky sometimes--you will have to experiment. If you get no image of an equation then you probably have a format error. I suggest starting with a simple equation on the first line, then the equation of interest on the succeeding lines. If you have an error, this will ensure that you get an image of the first (correct) line, followed by an error message that will help you to correct your mistake.

Use the Naturalmath tutorial to get a better handle on the capabilities of naturalmath.


6. Tables, horizontal lines, anchors, etc.

These are done from buttons at the top, and are pretty self-explanatory. Anchors are named locations in your file that you can use as links--for example, you can set an anchor at "equation 1" and link to it later on when you refer to it in you text.
The bulleted list at the top of this page used anchors to form the links to each of these sections.

Try creating a simple table like the one here:

name
 Arnold Schwarzenegger
 Barack Obama
 June Jones
address
 Sacramento CA
 White House
 SMU
job
 Governator
 POTUS1
 football coach
table notes:
1. POTUS: President Of the United States -- as of moment that this page authored

Note that the table will default to a width of "100% of window"-- change this to make it a fixed width.


7. Archiving, Uploading and Publishing your web page

You can always view your html file locally with your browser, but if you want other people to see it from outside your own computer, your computer has to be set up as a web server. One option is to post on your HEPG/UH account.

The best way to create the archive is to create a directory in your work area that will contain nothing but the document and its associated files. For example:

$ cd work
$ pwd
/_someplace_/work
$ mkdir Report1
$ mv report1.html  ./Report1
$ mv report1a.jpg  ./Report1
$ mv report1b.png  ./Report1

and so on for all of the associated files in your report. Of course if you created the folder first and the images all within this folder then you would not need to do this. Note that all of your links must be "relative" links, NOT absolute links, since you are going to transfer all of these files to another location to publish them.
 You can always view the progress of your html document by using the "open file" option on whatever browser you are running, then pointing it to the local folder and the file "Report1.html" or whatever you called it.

Once the document is ready, move your current working directory to the folder above "Report1" (if you are in the folder "Report1", then use the command "cd  .. " which bumps you up one level in the directory structure) and execute the following command:

$tar -cvzf Report1.tar.gz ./Report

This command creates the archive "Report1.tar.gz" from the contents of the folder "Report1".

Check that you did create the archive and that it has non-zero size with the command:

$ ls -lrt

your new archive file should be the last one displayed and should have a size not equal to zero.

These archives are much more portable and compact for moving around to other computers. We will use the same technique for saving and archiving work in progress: programs, data, and reports.