Notes on Writing for the Web

Note:
This document is intended as a good place for web-spinners to start looking for information. In particular, it is intended to point to all the manuals, specifications, and other technical documentation relating to the tools I'm currently using. If you have other suggestions, let me know.

Quick Reference

Here are some other resources for HTML authors:

WWW & HTML Developer's JumpStation
A very comprehensive set of pointers to developers' resources, hosted by OneWorld Information Services
A Tutorial on HTML
by Wm. Dennis Horn of Clarkson's Technical Communications Department

Ways to publicise your Website

WebPost at Sales and Marketing Exchangeg
Fill in one form and have it sent to all the most popular directories.
Postmaster
same sort of thing.

Markup Language

This file is written in HTML (HyperText Markup Language), the lingua franca of the World Wide Web.

The technical details for the Web itself can be found in Technical Aspects of the World-Wide Web -- this points in turn to About HTML, which points to the HTML Specification

Technical information on the NCSA server (which happens to be the one we're using) can be found here).

Technical information on and related to NCSA Mosaic (the most popular Web browser) can be found here. It also points to some beginner's guides and quick references.

Editing

Emacs

This file (and the other local files it links to) were created with GNU Emacs in html-mode. I found it rather clumsy, so I switched to html-helper-mode, which is a vast improvement. It particular, it uses a more natural typing style (inserting boilerplate and putting the cursor in the right place, rather than prompting you for stuff to insert) and displays tags in boldface, italics in italics, and so on. The local documentation is here

The way to preview stuff like this is to run Mosaic or some other web browser on the same file you're editing, using the r key (for ``reload'') whenever you change it. Alternatively you can use w3-mode (described here) and preview with w3-preview-this-buffer (which I bind to C-Cv), but it doesn't look as good or give you as good an idea of how people using more popular browsers are likely to see it. Lucid Emacs is said to handle inline images in w3-mode, so that's another possibility, especially for Lisp hackers.

I have something like the following in my .emacs file to load a Web browser and HTML editing modes.

(load "w3-load" t) ;;; w3-load.el defines the following autoloads: ;;; (autoload 'w3-preview-this-buffer "w3" "WWW Previewer" t) ;;; (autoload 'w3-follow-url-at-point "w3" "Find document at pt" t) ;;; (autoload 'w3 "w3" "WWW Browser" t) ;;; (autoload 'w3-open-local "w3" "Open local file for WWW browsing" t) ;;; (autoload 'w3-fetch "w3" "Open remote file for WWW browsing" t) ;;; (autoload 'w3-use-hotlist "w3" "Use shortcuts to view WWW docs" t) (autoload 'html-helper-mode "html-helper-mode" "An improved HTML editing mode" t) (setq html-helper-do-write-file-hooks t) (setq html-helper-build-new-buffer t) (setq auto-mode-alist (cons '("\\.html$" . html-helper-mode) auto-mode-alist)) (defun my-html-mode-hook () "Hook for HTML editing" (local-set-key "\C-Cv" 'w3-preview-this-buffer) ;; The preceeding doesn't seem to work unless you've already run M-Xw3. (auto-fill-mode 1) (setq fill-column 78) ) ;;; My actual html-mode hook has more stuff in it, but this will work for ;;; anyone (add-hook 'html-helper-mode-hook 'my-html-mode-hook) Marcus E. Hennecke) suggests adding the following setup code: (setq my-url "http://theStarport.org/people/" my-html-domain "theStarport.org" html-helper-address-string (concat "" (user-full-name) " " (user-real-login-name) "@" my-domain)) (setq html-helper-new-buffer-strings '("\n" "\n" "\n" "" "\n" "

\n\n" "
\n" "
" html-helper-address-string "
\n" html-helper-timestamp-delimiter "new file\n" ""))
which I will eventually add to default.el

Other Editors

The alternative Web browser tkWWW is the only one I know of that includes a full WYSIWYG hypertext editor. It's only available on Unix. There is a Mac HTML editor based on Hypercard.

Here is a recent pointer to tkHTML an editor (not including a browser) in Tk/tcl.

There are also a number of conversion programs for, e.g., FrameMaker, LaTeX, or Microsoft RTF. Some of them are listed here.

Protection

Now that we have two servers, protection is easy. I have a Public subdirectory inside ~/www and a firm policy of never making links from the public area to the private one. I made the following links:
	cd /usr/local/httpd_CRC/people
	ln -s ~/www steve
	cd /usr/local/httpd/people
	ln -s ~/www/Public steve
When I make a link from the private area to the public area, I use a full URL, i.e. I refer to my public home page as http://theStarport.org/people/steve/ instead of using a relative path like Public/steve.html. You can also protect everything in a directory by putting a file in the directory with the name .htaccess and contents: order deny,allow deny from all allow from theStarport.org Options All I do this just to make sure that my private stuff is really private.

You can also use such a file to modify the way a directory is listed; see for example .htaccess in this directory. By supplying a file called index.html you can replace the usual directory listing with anything you want; see for example http://theStarport.org/ and http://theStarport.org/people/. In particular, you can use an index.html file to make files in a directory accessible without revealing what else is there.

Directories

My directory tree looks like this: The ``index file'' is sort of an HTML hotlist, only not as dynamic. It lists the files and directories that I often need to look at. The personal icon directory is the same (via symbolic link) for public and private; the images and documents are not, because the contents are completely different.

File Formats

I like to keep files in a format that is is readable both in a browser and in an editor like Emacs. This reduces the need to preview things, although it's still a good idea to check links.

These formatting ideas are exemplified in ~/www/Public/pointers.html.

Lists of pointers

I use a description list format for lists of pointers, e.g.
Starport's home page
a paragraph of descriptive material, often including what it points to, for example my home page.
longer links
get a line break before the title, if feasible.

File Contents

One of these days I need to make some scripts for maintaining an HTML table of contents in a document. Until then, it's pretty easy to do it by hand. I use headers like:

Header

A Sub-Header

Which I turn into a hierarchical table of contents using unordered lists, i.e. It only takes two substitute commands to turn the `name="' into `href="#' and `h?' into `b'. The first time I do it I use grep to find all the headings.

Other Formatting Hints

Note:
You can make a note like this one with the following HTML:
Note:
You can make a note like this one with the following HTML:

Windows

In the X Window System it's easy to have an editor and a previewer (Web browser) on the screen. In fact, I like to have multiple copies of Emacs with fully-overlapped windows, using twm's tab-format title bars to select them quickly. I have the following in my .twmrc file to separate the tabs: SqueezeTitle { "Emacs" left 3 8 "e1" left 7 8 "www" left 2 8 "gnus" left 1 8 "vm" left 0 0 } AutoRaise { "Emacs" "Mosaic" "XTerm" }

I also set autoraise for Mosaic and Emacs so that moving the cursor into any part of an editor or browser window pops it to the front. Then when I want to stick a pointer to someplace interesting into one of my pointer files, I do the following:

  1. Follow the link in Mosaic, then select its URL by double-clicking in the ``Document URL'' box.
  2. Go to my Emacs window, find the appropriate file, and go to the right place in it.
  3. Insert a list item (^C^I) and a link (^C^L), and paste in the selected URL (^Y).
  4. Go back to Mosaic and select the title.
  5. Move past the "> at the end of the link and paste in the title (^F^F^Y).
Total operations after the link and destination have been found: one double-click, one drag-select, and 8 keystrokes.

Scripts

The following scripts ought to be written one of these days:

html-update-toc

Update a table of contents in an HTML file, using the format described above. It should surround the TOC with HTML comments that it can recognize.

html-update-dir

Update a directory listing by extracting the title from each HTML file and adding a line to the .htaccess file of the form AddDescription "Writing for the Web" authoring.html
$Id: authoring.html,v 1.5 1999/07/10 05:38:09 steve Exp $
Stephen Savitzky<steve@theStarport.org>