How To...

(some notes on managing the website)

I do all the development and testing (HTML syntax checking, link testing, etc.) on my home computer — an Apple Macintosh "Mini" (1.42 GHz PowerPC G4) running OS X 10.3.9. (Of all the development platforms I've worked on, OS X is by far the best: you get all the benefits of the Mac's elegant user interface plus the stability and flexibility of Unix.) Here's an overview of what I do:

Step 1: Edit the HTML files

I rely on » BBEdit (v. 8.2.1), an extremely powerful and full-featured general-purpose Macintosh text editor that has almost all the HTML coding features you'll ever need. Its find-and-replace capability (based on grep, a tried-and-true Unix "regular expression" text search tool) makes it easy to do complex text edits across the entire website with just a few clicks and keystrokes. (If you're not familiar with grep regexp commands, be forewarned: it can take a little time to master its cryptic syntax. But the time invested will amply reward you in time saved.)

On rare occasions, when I want to test experimental chunks of HTML for browser compatibility, I use DreamWeaver.

Step 2: Prep the files for the web

Once I've edited the files on my Mac, I run a bunch of Unix shell scripts to take care of a number of pesky housekeeping details: applying time-stamps, assembling zip file archives, building master file lists, etc.

Step 3: Upload

When I'm satisfied that the site looks good on my Mac, I run another shell script to upload all the newly modified files to the live website.

That's the overview. Here are more details about how to...

• ...update the website
• ...work with Microsoft Word files

How to update the website

Update and check HTML.Using BBEdit:

1. Do "Update/Site..." This makes sure that all the include'd portions of the site are properly brought up to date as needed. The update process is the BBEdit analogy to Unix makefiles: BBEdit compares the mod date of the file against those of the files on which it depends (i.e., its include files). If any of the dependencies are newer than the file, then BBEdit re-inserts the includes into the file. The upshot is that only those files whose underlying dependencies have changed are modified.
2. Do "Check/Site Syntax..." and "Check/Site Links..."
3. If you made any changes based on Step 2, run "Update/Site..." once more (or just update the file(s) that you fixed).

Final global checks. Using Terminal:

1. Run cksite to validate (a) links to remote sites and (b) the CR/LF status of all html files. If any errors are found, correct the affected files and re-run BBEdit's "Check/Document Syntax" and "Check/Document Links." Re-run cksite until it's clean.

Final build and upload. Using Terminal:

• % buildsite ati # applies time stamps and execs all the makefiles
• % makebulk # prepares the off-line edition (bulk file)
• % upload_to_server ati all [password] # uploads the files

For the gory details, see all the shell scripts and related files.

How to work with MS Word files.

In this example, we're presented with a Microsoft Word file named "Book.doc", and we're going to convert it to an ATI webpage named "book.html".

Proofread & spellcheck. Using Microsoft Word:

1. Open "Book.doc"
2. Print & proofread
3. Apply corrections
4. Spell-check
5. Save As... Web page ("Book.htm")
6. Close "Book.htm" (or Quit from Word)

Unix-ify the line-breaks. Using BBEdit:

1. Open "Book.htm"
2. Change line-breaks from Mac to Unix
3. Save
4. Close "Book.htm"

Strip all the non-standard HTML grunge that Word introduced.

When you use Word's "Save As..." command to save a file in HTML format, Word throws in a ton of nonstandard and useless HTML code. That grunge must always be removed before publishing a file on ATI. One of the most popular tools for doing that is the shareware program HTMLTidy, but I found that it only partially fixes it, and sometimes does weird things — like unconverting perfectly good HTML entities (e.g., &) to their ASCII equivalents (&) — requiring a follow-up cleanup session by hand. So I threw together fixword, a small C++ program that does exactly what I want it to do, and no more. If you want to see the source code, let me know.

Using Terminal:

• % cd ~/Desktop
• % fixword Book.htm book.html # remove Microsoft grunge
• % mv book.html foo/bar/somedir/. #(move it to its destination folder in the website)

Standardize the HTML. (back in BBEdit:)

1. Open "book.html"
2. Select All
3. Hard Wrap to 10000 (cmd-\)
4. Run AppleScript "CSS prep" (details available on request)
5. Copy and paste header and footer "include" chunks from another document. Edit the header chunk accordingly.
6. Do "Update document"
7. Tidy, tweak, fiddle, and fudge the HTML 'til it's the way you want it.

Integrate it into the website. (still in BBEdit:)

1. Add relevant entries to the Indexes.
2. Cross-references: are there any other docs that should link to this one?
3. Write a summary blurb for the document and incorporate it in the associated index.html file.
4. Copy the blurb to the "What's New" page, editing as needed.
5. Add entry to the RSS feed. Edit (update) the revision date in the RSS file.
6. Check website syntax.
7. Check website links.