Converting my dissertation to other formats

The following document lists what I had to do to convert my dissertation
from FrameMaker 5.5.6. to various other formats. For each format, I explain
the process, and the pros and cons with the process and with the format.

---------------------------------------------------------------------------

Frame to PS
	Open the book file. Either Save As PostScript or print to file.

	+ Very easy.
	- Naturally, all cross-references are lost.
	+ Browsers automatically uncompress a compressed version of a PS file.
	  Makes file transfer quicker.
	+ Portable.

---------------------------------------------------------------------------

Frame to PDF
	Open the book file. Save As PDF. You will get a window asking which
	paragraphs to include and which to exclude. Frame is trying to
	determine which paragraph types you want to keep in a bookmarks
	document. Your selection here does not affect the main PDF document
	itself; naturally, all paragraphs are included in the main document.
	The bookmark document is like a Table of Contents. Within a PDF reader
	such as acrobat, the bookmark document allows the reader to navigate by
	clicking on any of the entries in there. You have to decide which
	paragraph types make sense for navigating. Typically, the Title,
	1Heading, 2Heading, 3Heading, etc. are good choices. Additionally, I
	chose Figure, Table, Cite and some key paragraphs, such as Assumption,
	Guideline, Statement, Theorem, etc. Indent the included paragraphs
	relative to one another, hit Set and watch the PDF get generated.

	+ Very easy -- took about 3-4 tries to get it just right, with each try
	  taking about 3-4 minutes on an interactive server for Frame to
	  generate the file.
	+ Maintains cross-references in your document in your style. In other
	  words, the reader can navigate within the document itself by clicking
	  on the cross-references.
	- However, PDF does not visually distinguish between plain text and
	  hypertext. The reader has to know where to expect a cross-reference.
	+ Additionally, the reader can navigate from the bookmarks window on
	  the left.
	+ Designing your document well and including the right paragraphs in
	  the bookmarks will let you do some cool tricks. For example:
		In my reference pages, the citation code for the reference is a
		paragraph type called "Cite". Including this paragraph type in my
		bookmarks means that the reader can list all my references in the
		bookmarks window and click on the one he/she would like to see
		fully listed in the document window.
		Moreover, whenever I cited one of these references, I had an actual
		cross-reference to the appropriate "Cite" paragraph there. I chose
		this approach because when I was writing, it enabled me to change
		the code for a reference and have the cites changed automatically.
		(Incidentally, achieving this in Frame required a grand kludge
		involving making my references document a giant table...). The nice
		side-effect of this was that my cites became cross-referenced in
		the PDF as well. The reader can click on my cite and jump to the
		actual reference.
	- Browsers do not automatically uncompress a compressed PDF file.
	  Therefore, file transfers are slower.

---------------------------------------------------------------------------

Frame to HTML
	Open each file. Click File -> Utilities -> HTML Setup. For each
	paragraph tag, character tag and cross-reference tag, choose the tag in
	HTML. After this, Save As HTML.

	+ Conceptually easy.
	- Practically tedious, slow and frustrating. Ideally, you should be
	  able to open the book file and convert your documents in one shot.
	  However, Frame does not allow you to do HTML Setup from the book file
	  (which means you have to go with their defaults), and it makes one
	  giant HTML file instead of one file per chapter. Also, each Frame tag
	  has to be mapped to an HTML tag one-by-one. Each mapping takes up to
	  13 seconds on an interactive server, and 2-4 seconds on a compute
	  server.
	+ Most of the defaults are reasonable. The default background is white,
	  which is decent. The default font size is got from the document.
	- Some of the defaults are egregiously bad.
		For cross-reference, the default is to insert the text "See also
		...", instead of the original style.
		For numbered paragraphs, such as 1Heading, 2Heading, etc., the
		default is to not turn on autonumbering.
		For most character formats, the default HTML character class is
		Emphasis, when better formats are available. For example, I have a
		character class called "Code". There is a HTML character class
		called "Code". However, the default mapping from my "Code" is to
		"Emphasis", not "Code".
	+ Figures are changed to GIFs (default), JPGs or other formats.
	+ Mathematical formulæ are converted to GIFs if they are set aside as
	  equations. If they are inlined in text, they are replaced by an
	  extended set character, which usually appears as a "?", unless a
	  TrueType Symbol font is available.
	+ Cross-referencing is excellent. Once you specify the cross-reference
	  formats in the tedious and brain-dead way for each chapter, Frame
	  makes cross-references unerringly. Cross-references to other chapters
	  are inserted optmistically. Evidently, Frame has a deterministic way
	  of generating the cross-reference tags, because it can generate
	  references from Chapter 1 to Chapter 9 before the HTML for Chapter 9
	  is created!
	+ Justification, yes, even full-justification, is maintained.
	- Little oddities and annoyances that require hand-tweaking remain.
	  Frame retains page numbers in the Table of Contents, List of Figures,
	  etc. even though they don't make sense in an HTML document. You have
	  to remove those by hand. Also, if a cross-reference has special tags
	  (such as ... or ...), then the tags
	  are not nested as you would expect them to be. Images are given
	  borders, whether you like them or not. Text tagged as Subscript or
	  Superscript in the Frame document is not tagged as such in the HTML
	  document even though the CSS file has an entry for the mapping!
	  Formulæ have a horizontal line above them. During HTML Setup, if a
	  document has no cross-reference tags in it, and you try to see if
	  there are any that need to be mapped, Frame dies. Save often!
	- Creates different style files for different chapters. Understandable,
	  since we save each file separately. However, if there was a way to
	  work with the book as a whole, we would have had one style sheet.
	- Does not provide any means of navigating from chapter to chapter. You
	  would have to write that yourself.
	+ Pretty portable HTML, though it may appear differently on different
	  browsers.