Writing hypertext at the MIT AI lab

Writing Hypertext

Topics

So you want to write hypertext? Just fire up the handy-dandy WYSIWYG hypertext authoring system and ... well, not quite.

That'll come eventually, of course, but a really usable, solid hypertext editor isn't freely available yet. This page is about what you can do in the meantime. Basically, you have two choices: use a translator to convert it from whatever form it's currently in (we have a LaTeX-to-hypertext converter installed right now), or write the stuff directly in emacs.

Writing Hypertext in Web format (html)

For simple tasks, you can probably get by just by using the Emacs html mode (see description below), in conjunction with a sample document to use as a model. To print a Web document with the html formatting commands visible use the Save As command under the File menu while you are browsing the Web document of your choice. A window will appear asking you were to save the file, and a pop-up menu will allow you to select HTML format. Once the file is saved you may print the file using lpr. The HTML formatting will be visible.

Fuller documentation on what HTML is (i.e., what format tags are available), is available through many on-line primers. If you're serious, you may want to consult an style guide as well --- NCSA has a list of them. (Ignore the reference to "style sheets" at the top --- that's a description of a potentially interesting technology which is, unfortunately, not supported by any browser in widespread use).

Once you've written some html, you can try it out simply by saving it out to a file with an ".html" extension, and using "Open Local" from the Mosaic file menu. When it is ready for prime-time it should go in the /com/doc/web directory.

Emacs HTML modes

In order to write Hypertext documents from scratch should know about the html modes in Emacs. These modes allow you to type simple key sequences to create html formatting. This saves you from typing millions of <'s and >'s which are common to all html formatting commands.

We have two supported HTML modes, Marc Andreessen's original html-mode, and the somewhat more sophisticated html-helper-mode from Nelson Minar. (The html-helper-mode command structure is more consistent and more complete that that of html-mode).

html-helper-mode

You can load html-helper-mode into your emacs by typing M-x load-library html-helper-mode. Documentation is available either in hypertext form or in Emacs itself, by means of the usual C-h m sequence within Emacs.

html-mode

You can get at the html mode in Emacs by doing 'M-x load-library html-mode' in emacs. Documentation is then available by means of the usual C-h m key sequence from any buffer which is in html mode.

Making HTML modes load automatically

If you will be writing more than one simple html document you will want to put some code in your .emacs file which will automatically load the html mode of your choice when opening files with .html suffixes.

Translating Text

If you have existing documentation you want to put up on the Web, you may be able to use a LaTeX-to-hypertext converter, latex2html. Hypertext documentation is here, and there is also a man page. This program is still quite new, but it is well past proof-of-concept.

For instance, Richard Gabriel's "worse-is-better" paper goes through without alteration or complaint. A paper of mine on some texture work I did also went through perfectly smoothly, without alteration. The latter is the more interesting case: it includes lots of math and several postscript figures, all of which are included in the hypertext form as bitmaps. (You don't even want to think about how this works. Just accept it).

(For contrast, here is a .dvi-file version of Gabriel's paper).

Note that the converter only handles LaTeX commands; documents which make use of plain-TeX macrology (outside of .sty files, which can easily be made to work properly) will have problems. Note also that here are dark corners of LaTeX (and even merely dim ones) which it doesn't handle properly yet. (The man page lists a few of these, such as cross-references in figure captions).

Even with all of that, it is still by far the best option if you have some preexisting LaTeX to convert, and may also be the easiest way going to write hypertext which includes any kind of serious mathematics.

There are also converters available for documents in TeXinfo and RTF (i.e., Microsoft Word) format --- they're coming as my time permits; let me know if you have pressing need.

Adding Yourself to 'People of The MIT AI lab'

To create an entry in the People of the MIT AI Lab section you need to create an html document with some information about yourself, your project, and (if you like) a picture of yourself. If you would like instructions on including your picture in your personal html file they can found in /com/doc/web/people/photo-info.html

Once you have created your own personal html document about yourself write the file to the /com/doc/web/people directory. You will also need to add a link to your personal html file in the /com/doc/web/people/people.html file. Looking at other people's entries should make this fairly obvious. Add yourself in alphabetical order. The name of your file should probably be your username. It must have a .html suffix to work correctly, as do all html documents.


Robert Thau --- rst@ai.mit.edu
Laurel Simmons ---laurel@ai.mit.edu