HTML 2.0 Draft Reconstruction

This page describes what I have done regarding the reconstruction of the IETF draft for HTML 2.0. Just in case you are wondering, here's why I am doing this.

I have done the following so far:

1. On Friday, I obtained the original draft 00 FrameMaker file from Eric Sink. Unfortunately, after comparison of the differences between the text versions of <draft-ietf-html-spec-00.txt> and <draft-ietf-html-spec-01.txt>, I decided that the only safe way to proceed was to just start from official text version of draft 01.

2. I then used FrameMaker 3.1 to read the text file, copied the template formats from my HTTP/1.0 spec, and began reformatting the document. It took about four hours to do this, mostly because of the need to delete extra spaces and assign appropriate paragraph types to each paragraph.

3. In parallel with the above, I began filling-in the bits of document information that the draft was missing (a standard heading, author's addresses, etc.) and cleaned up the acknowledgements. In the process, I also discovered that the draft contained the old version of Dan's SGML Public Text for HTML. So, I removed the existing SGML declaration, DTDs, and SGML Open catalog and replaced them with the newer versions. Note that I had to remove three spaces from every line so that they would fit in my format. Another four hours gone. At this point, I decide to stagger home and get some sleep.

4. But, what should be on my answering machine? A message from my Mum, reminding me that my little brother (well, not so little any more) would be having his graduation party all day Saturday. Ooops.

5. Saturday night (after my brother's graduation party), I began restructuring the document so that it matches the nature of HTML and the guidelines for an IETF specification. To that end, I moved the old overview, obsolete, and proposed sections to appendices; extracted the various introductory and terminology sections into a real Introduction, moved the SGML info stuff into its own section, moved the text/html media stuff into another section, and generally reorganized just about everything. Finally, I re-named the section headings appropriately and removed any material that was an exact duplicate of some other section.

6. Sunday had the nicest weather I've ever seen in Irvine (mind you, our average weather is better than most places ever see), and I spent the majority of it in front of a computer. Worse, everyone else is off on Spring Break, so the campus decided to shut off all the air conditioning systems. Mmmmmm, there's nothing like a hundred SPARCstations on a sunny day to make a small building feel mighty toasty!

   But if that's not enough, one of the professors in our department decided that I should co-author a paper with him. Great, right? Weeeeellll, this paper is due Monday. :(

   Okay, so I do that, and what should happen next? I get a message from my advisor (currently on sabbatical in France) that he would like to know my opinion about the faculty candidates we interviewed last week. *sigh* But wait, there's more. Another message comes in, this time reminding me that our grant's quarterly progress report is due this week, so I need to write down what I've done this past quarter and what is planned for the next. Plan for three months? Crikey, I can't even plan for three days! It is about this point that I begin to recognize the conspiracy.

7. At 2am Monday, I actually managed to get back to the draft. I have generated a new base draft 02a in PostScript or FrameMaker binary format. Note that this draft still contains the original body text of draft 01 (with the exception of some re-named section references and some deleted paragraphs that were exact duplicates of others). One thing you will immediately notice is how many errors occur in the original text -- they are much more visible with the new structure. If you are still skeptical, just do a search for the same text in the old draft.

8. I will now turn on the document change bars and begin making my changes to the content of the spec. This way, people will be able to identify my content changes (other than the DTD replacement) from the structural changes. I will not have time to fix all of the prose, though I do hope to fix all the technical errors.

9. Monday night (and Tuesday morning), I was able to get all of my known fixes into the draft. I have generated another base draft 02b in PostScript or FrameMaker binary format. However, there are still some clear errors, so I'll work on it again tonight before submitting it as a new Internet Draft. This would be a good time for others to check the document and tell me what needs fixing.

10. Okay, I'm done making changes. I have generated a new draft in
    • Postscript with Change Bars
    • Postscript (no Bars)
    • FrameMaker binary
    • FrameMaker MIF
    • Text (gzip'd)
    • Text

11. A problem was encountered when converting the draft to text. For some reason, MifMucker failed to translate things like ">" and "]]>" when they were on a line by themselves. The result was a mucked-up DTD, which I fixed by hand. Could someone please cut-n-paste it out of the text version (above) and run it through their favorite SGML parser?

How to convert from FrameMaker to Text

I recommend that you save the file after each step.

1. You will need to get and install a copy of MifMucker. I use the following ascii map file (I also have an old HTML map file which may be useful).
2. Copy (or Save As...) the FM version of the spec to a new file called "ugly.fm" -- you'll see why I call it that fairly soon.
3. Open ugly.fm and force all variables to be written to text (that is done in FM 3.1 through the Special/Variables -- !sv -- dialog).
4. Open the Format/Paragraph... dialog and choose "Default Font" from the Properties list. Type shift-F8 to clear the dialog, and then set the font to Courier, 11pt, Regular, Regular, Regular; turn off all of the style radio buttons (particularly kerning) and set Spread to 0.0. Apply this to All Paragraphs and the Para Catalog. Note that this should make all the paragraphs ugly.
5. Still in the Format/Paragraph... dialog, choose "Advanced" from the Properties list. Type shift-F8 to clear the dialog, and then set all of the Word spacing to 100% and turn off automatic spacing -- this prevents space kerning.
6. Find a "Note" paragraph, select it, and then use the Numbering Properties (in the Format/Paragraph... dialog) to change the autonumber character style to "Default P Font" (this gets rid of the italics on "Note:".
7. Select all in Flow (from the Edit menu) and apply the character format "Default P Font" -- this gets rid of any character based highlighting.
8. Change the IETF draft filename to *.txt from the *.ps original.
9. Remove the leading tabs and number from all the TOC entries -- this is done easiest by using the macro recorder for repetition.
10. Briefly page through the document looking for badly formatted lines -- this happens sometimes when a hard return was used to force a linebreak in the PS version.
11. Save ugly.fm, and then Save As... to "ugly.mif" in Maker Interchange Format (MIF).
12. Assuming that mifmucker is on your path and the ugly.mif and ascii.map files are in the current directory, run the command

             % mifmucker ascii ugly.mif
    

    It will take about 20 minutes to run on a fast machine (yes, it is amazingly slow). The result will be "ugly.txt".
13. Edit ugly.txt with your favorite text editor to fix up the bits that aren't quite right. Finally, change the name to "draft-ietf-whatever.txt" and you are done.
14. As I mentioned above, a problem was encountered when converting the HTML draft to text. For some reason, MifMucker failed to translate things like ">" and "]]>" when they were on a line by themselves. The result was a mucked-up DTD, which I fixed by hand.