Part VI
Appendices

Appendix A Adding Additional Automatic Picture Converters

First, of course, you will need to obtain the necessary software. The next step is usually to write a batch file which calls the new converter, with any necessary switches. This batch file will be called from within TeX4ht/SWP with either three or four arguments:

1. Optional: The path to your picture, as it appears in SWP. Note that this will appear with Unix syntax (see below) and may be empty. Example: H:/mydir1/mydir2/
2. The filename of your picture as it appears in SWP, eg: mygraf
3. The picture’s extension, including the leading period (.), eg .abc
4. The desired extension of the Web image including the leading period (.) as supplied by TeX4ht; unless you explicitly change this, the extension will be .gif

You cannot know in advance whether your batch file will be called with three or with four parameters (this depends on the way your Save Options are set up in SWP, and may change from document to document). You will need to check this in the batch file itself: this amounts to checking whether parameter 4 is empty: see tex4ht-im.bat for the basic idea. Thus in terms of the batch file, you will be converting either #1#2#3 to #2#4 (if you are called with 4 parameters) or #1#2 to #1#3 (if you are called with 3). You should test your batch file outside the TeX4ht context before going any further; be sure to test it with both 3 and with 4 parameters.

Next, you need to tell TeX4ht to run your batch file when it encounters your picture type. You will do this for both standard SWP and for Portable LaTeX documents.

It is important to understand how this will work. Your graphic’s path (if one is provided) will appear in Unix form, with separators / instead of the normal DOS \ characters. This is not usually acceptable to DOS. We use the TeX4ht filter htcmd -slash to change the separators around. But this means that you will not be able to use any program which uses the / character for its own purposes, because htcmd will change it, too. (That was a problem with the .wmf support via IrfanView, which needed /convert as a switch: that’s why I wrote xiview.exe to get round it).

Now to work. For purposes of illustration, suppose you are providing automatic conversion for a picture type abc which will use the batch file tex4ht-abc.bat to do the work. We begin with the standard SWP support. Open swpht\tcitex\tex\latex\tex4ht\swpframe.sty (where swpht is your top-level SWP directory) in a text editor.

• Find the group of statements beginning \if\SubStringConditional{\PAVLcExt}{zzz}
• Copy the group of statements (up to but not including the comment %%% end template) to the clipboard.
• Paste the clipboard contents to just above the line % *********** end auto-graphics generation. You can add some space around the new group for appearance’s sake.
• In the new group:
  • in the line \if\SubStringConditional{\PAVLcEext}{zzz} change zzz to abc
  • in the line beginning \Needs{\string" change tex4ht-im.bat to tex4ht-abc.bat
• Save swpframe.sty

Now we do the same for Portable LaTeX support. Open swpht\tcitex\tex\latex\tex4ht\portgraf.tex in a text editor. Note that each block of graphics-control statements contains two \Configure{graphics*} statements, one for uppercase and one for lowercase extension.

• Find the group of statements beginning \Configure{graphics*}{zzz}
• Copy the group of statements (up to but not including the comment %%% end template) to the clipboard.
• Paste the clipboard contents below the group you just copied. You can add blank lines above and below for visual appeal.
• In the new group:
  • in the first \Configure{graphics*}{zzz} change zzz to abc
  • in the line beginning \Needs{\string" change tex4ht-im.bat to tex4ht-abc.bat
  • in the second \Configure{graphics*}{zzz} change zzz to ABC (the \Needs line is case-insensitive).
• Save portgraf.tex

Now when TeX4ht/SWP finds a picture with extension .abc (or .ABC), it will use tex4ht-abc.bat to convert it to a web image.

A.1 Using Irfan-View instead of ImageMagick

As mentioned in the main text, TeX4ht/SWP is pre-configured to use ImageMagick to convert the following image types to gif: .pcx .bmp .png .jpg .wpg .tif . But Irfan-View can also do these, and may be faster, so you may want to consider switching converters. Irfan-View also claims to handle .eps graphics, but in my limited experience it has problems here, so I recommend handling these with GhostScript/ImageMagick.

For the graphics types above, here’s how you switch converters. We begin with standard-SWP support.

• Open swpht\tcitex\tex\latex\tex4ht\swpframe.sty (where swpht is your top-level SWP directory) in a text editor.
• For each of the picture types you will see a block of code beginning \if\SubStringConditional{\PAVLcExt}{xxx} where xxx is the extension you are changing.
• On the line … htcmd -slash tex4ht-im2.bat … replace tex4ht-im2.bat by tex4ht-iv.bat
• Save and close swpframe.sty

Now we do the same thing for Portable LaTeX. Note that each block contains two \Configure{graphics*} statements — one for uppercase and one for lowercase extensions — and you need to make two changes.

• Open swpht\tcitex\tex\latex\tex4ht\portgraf.tex in a text editor.
• For each of the picture types referred to above, you will see a block of code beginning \Configure{graphics*}{xxx} where xxx is the extension you are changing.
• About three lines below this is a line beginning  \Needs{\string"htcmd -slash tex4ht-im2.bat. Change tex4ht-im2.bat to tex4ht.iv.bat
• Do the same with the second \Needs{\string"htcmd -slash tex4ht-im2.bat.
• Save and close portgraf.tex.

TeX4ht/SWP should now use Irfan-View instead of ImageMagick to do these conversions.

Note that you cannot completely replace ImageMagick by Irfan-View, since Irfan-View cannot do the crop-as-much-as-possible operation needed to produce equation- and glyph-gifs. ImageMagick is still needed here.

A.2 Removing an automatic conversion

If you should need to disable a particular type of automatic conversion, the simplest way is to “comment it out”. This is easy, since each set of conversion instructions forms a group of statements, as noted above. Just put the LaTeX comment character % in front of every line. Remember that you need to do this in both swpframe.sty and portgraf.tex.

Appendix B Changing the HyperLink layout

This Appendix deals with two points concerning the SWP-specific HyperLink dialog: how to customize the way these links are rendered in your HTML, and how to obtain a link to an arbitrary Marker in your document.

B.1 Changing the appearance

The default behavior of the HTML generated by SWP’s HyperLink dialog is to make the “Screen Text” a live link, and when the user clicks on it, the action described by the “Target” is taken. Here’s how to alter this behavior, if you need to.

• Open swpht.sty. Locate the definition of the macro \hpref: this extends from the line beginning \def\hpref#1#2#3#4 to the line }% end of \hpref definition
• Copy this text to the Clipboard
• Paste it into a document-specific .cfg file.

We will be changing the following lines of the definition (only the lines containing \Link will be changed):

Case 1: : You want the text of the “Target” to be the live text in your document. Change the lines to (replace #1 by #4):

Case 2: You want the text of the “Target” to be live, but you want it surrounded by the “Left” and “Right” Printed text. Change the lines to (this adds #2 before \Link and #3 after \EndLink):

Case 3: You want the “Screen Text” to be live, but you want it surrounded by the “Left” and “Right”” Printed Text (why, I don’t know). Change the lines to:

B.2 Arbitrary markers

As mentioned in section 15, SWP’s Marker mechanism is more general than LaTeX’s: you can put a Marker anywhere in your document, and jump to that location via the HyperLink dialog. In LaTeX this works only if the Marker marks something which is referenced by a LaTeX counter, like a section, subsection, or number in a numbered list.

It is possible get links to arbitrary Markers in your HTML, but the mechanism is a bit clumsy (not to mention visually unattractive). Essentially, we define a new LaTeX macro (\MARKER, in caps), and give it different definitions for typesetting and HTML generation. Here are the details.

• At a point where you have a SWP Marker which is not associated with sectioning or a numbered list, create, right next to the SWP Marker field, an encapsulated TeX field, whose name is MARKER and whose contents is \MARKER{xxx}. Note the capital letters, which should be observed.
• If you’ll use this often, save the TeX field as a SWP Fragment, say as marker.frg.
• Now re-open the field, and replace xxx by the name of your SWP Marker, so that they refer to the same thing. You should now see two fields in your document: one saying marker: xxx and the other saying MARKER, where in the first, xxx is a label, and in the second, the contents of the field refers to the same xxx.
• Place the following in your document Preamble:

  \def\MARKER#1{\label{#1}}

  This makes the \MARKER macro behave just like the SWP Marker when you typeset.

• Place the following in a document-specific configuration file, or in myconfig.cfg if you want it to be always available:

  \def\MARKER#1{\HCode{<A NAME="}#1\HCode{"></A>}}

  This makes \MARKER generate an HTML target.

Then whenever you need one of these free-standing markers, just insert Fragment and revise the field. The downside of this is a certain visual clutter: you have two fields with these references. You can avoid this by turning off the display of SWP’s Markers, but I personally find that I like to see them in my document.

Appendix C The Explicit-Package Approach to TeX4ht

This appendix discusses the details of the explicit-package approach to using TeX4ht. This was the only approach available in Version 1 of the support, and may still be useful for legacy documents. However, for most new users, the no-package approach described in section 12.1 is preferable.

C.1 Using the explicit package approach

To include an explicit reference to the TeX4ht/SWP package in your source, you include either of the following statements in the Preamble of your document:

\usepackage[no,other options]{swpht}

or

\RequirePackage[no,other options]{swpht}

Either will work: however, I find it somewhat easier to make changes with the \RequirePackage form, since this statement is accessible from SWP from the Typeset -> Preamble dialog. This sets up your document for standard typesetting: with this statement in your source, you should not notice any difference in typeset output.

To produce HTML output all you need to do is change the no to yes, and run the changed document through the TeX4ht batch file htswps.bat (or let htrun do it for you). You can make the change either in SWP itself, or you can use a text editor outside SWP. So to convert myfile.tex to HTML, assuming that the source contains the package reference:

• Change the no to yes
• Start a DOS session and switch to the directory containing myfile.tex.
• Issue the command

  htrun myfile n  or   htswps myfile n 

  where you must specify the name of your source file without an extension, and n (0 <n < 3) is the number of LaTeX passes needed to compile your file. If you omit n, the TrueTeX compiler runs three times, which is usually safe. In general, n is the number of compilations you need to typeset your document successfully within SWP.

• If the TrueTeX compiler finds an error in your document, it will pause and ask you what to do. If you respond x (for Exit), then the entire translation process will stop, and no HTML will be produced. This is to prevent the compiler running again, which would be a waste of time since you know you’ll have to fix something.
• When you are satisfied with your HTML, remember to change yes in the package options back to no: if you do not do this, you will not be able to obtain properly typeset output.

C.2 Testing the explicit-package approach

Here is how to test that the explicit package approach is working correctly. We do two tests: one in which we call the batch file directly, and a second where we use the cover-program htrun.exe.

• Issue the command

  htswps swphttest 1

to start generating HTML. The TrueTeX window should pop up once, and then you should see some screen messages from the TeX4ht system.

• When it’s finished, you should have swphttest.html, swphttest.css, and swphttest0x.gif, for the equation in your directory. Use a browser to view the file and check that it’s correct.
• Issue the command

  cleanup swphttest

— this cleans up most of the files produced by the system, so you can be sure that the next test runs correctly.

Next we test htrun.exe, which generates HTML without your having to tell the system whether or not your source (.tex) file contains the TeX4ht package.

• Issue the command

  htrun swphttest 1

  You should see a notification that the your file is found to be a LaTeX/SWP file with the package; the system will pause, then call htswps swphttest 1; the output should be the same as in the first test. The (new) swphttest.html should still be correct.

• Issue the command

  cleanup swphttest

C.3 Providing options

When your source document includes an explicit reference to the swpht package, you specify package options by including options in the brackets ([]) before the name of the package. You can include as many options as you like, and in any order, with two exceptions.

• The first option must be either yes or no, to turn the TeX4ht support on and off.
• The second option must be either the name of a configuration file name or the one of the keywords html (which requests output with extension .html), or htm (which requests files with extension .htm). The configuration file name may be provided without extension, in which case the system will search for a file with the given name, and extension .cfg. See section 13.2 for more on configuration files.

Here are some examples of providing package options (we show the form with \usepackage: the \RequirePackage form is the same).

• Request HTML-4 output, but with extension .htm

  \usepackage[yes,htm]{swpht}

• HTML-4 output with extension .htm, and additional configuration information in myfile.cfg:

  \usepackage[yes,myfile,htm]{swpht}

• HTML 3.2 output, extension .html (the default), additional configuration information in myconfig.txt:

  \usepackage[yes,myfile.txt,3.2]{swpht}

C.4 Configuration files

When you use the explicit-package approach, you must explicitly request a configuration file as a package option. It is never automatic. Note that the same configuration file can be used for both standard SWP documents and for Portable-LaTeX and non-SWP-LaTeX documents, because of conditional code in the file.

Standard SWP LaTeX

Use of configuration files is optional. However, if you wish to use document-specific configuration files, you must explicitly refer to myconfig.cfg as the second option (after yes or no) in the list of package options for the swpht package. See section 13.2

Portable LaTeX

A configuration file is required in order to correctly process pictures in Portable LaTeX documents. This means that you must explicitly refer to myconfig.cfg as the second option (after yes or no) in the list of package options for the swpht package.See section 13.2

Non-SWP LaTeX

A configuration file is needed only if you wish to make use of automatic picture handling, as described in section 14.3, or document-specific configuration files. If you wish to make use of these facilities, you must explicitly refer to myconfig.cfg as the first option in the list of package options for the tex4ht package. See section 13.2

Plain-TeX, TeXinfo

Default configuration files are not supported. If needed, they may be included as command-line package options.

Appendix D The TeXConverter

Steve Mayer’s TeXConverter provides a point-and-select interface for TeX4ht/SWP, which some users will prefer to the command-line usage described in the main text. The TeXConverter supports all conversion options discussed here. This Appendix describes how to obtain, set up and use the TeXConverter.

D.1 Obtaining the TeXConverter

• Browse to Steve Mayer’s website . The section Download contains a link to the current version in texconv.zip
• Unzip the distribution to the directory of your choice.

D.2 Setting up the TeX Converter

If you have not previously used the TeXConverter: the TeX4ht/SWP distribution provides a version of the Converter’s TeX Converter.ini file configured to match your installation choices in the rest of the system. This was left in c:\tex4ht\temp: you should move it to your TeXConverter directory, where it will over-write the one provided by Steve Mayer’s distribution. As of May 2004, the same thing applies to the configuration files tcconfig*.cfg: Carmen Fierro has supplied replacements for these, and if you want to use them you must move them to the TeXCoverter folder by yourseslf.

If you have already used the TeXConverter: you probably do not want to use the new version of TeX Converter.ini because it will not save any choices you have already made. You will need to tell the TeXConverter where you have installed TeX4ht, and possibly the locations of ImageMagick and GhostScript. To do this:

• Start the TeXConverter.
• Click on the Help tab.
• Under Settings click on Program Locations. The resulting dialog allows you to browse to the locations of the various files.

All users: with the TeXConverter running, and the Help tab displayed:

• You will probably want to check Save Preferences, and possibly also Allow multiple conversions. 
• If you plan on using TeX4ht for most of your conversions, you can ensure that its tab is uppermost when the TeXConverter starts by selecting TeX4ht from the Startup Preferences drop-down box.

D.3 Converting a document to HTML

In this section, we’ll repeat one of the TeX4ht/SWP tests using the TeXConverter, and convert swphttestA.tex to HTML.

D.3.1 Basic setup

Start the TeXConverter, select the TeX4ht tab. Begin in the left-hand panel:

• Click on Browse to locate the test document, swphttestA.tex, typically in c:\tex4ht\test. (You can also type in the information directly.)
• You can have the Converter automatically display your output by checking Run HTML file
• The TeXConverter includes its own browser: on slower computers, you may get a faster display by checking Use Own Web Browser, rather than starting your normal browser.

Now switch attention to the right-hand panel:

• Make sure that Use Scientific WorkPlace is checked.
• Make sure that Use htrun is checked.
• If you leave the Number of LaTeX passes set to Default you get three passes of the TrueTeX compiler, which is unnecessary (but harmless) for this document. You may as well change this to 1. 

D.3.2 Locating the output

By default, the TeXConverter’s output is placed in a subdirectory of the main document directory; and any images are placed in a subdirectory \images of that directory. You can change this behavior by clicking on Change Directory (bottom-right panel) for the location of the HTML. If you uncheck Put Image in subdirectory immediately to the right of that, the document and its images will be stored in the same place. Alternatively, you can choose a different subdirectory (of the HTML directory) for images by entering something in the text box.

D.3.3 Configuring the HTML

Immediately below the choice-of-passes selector is a grayed out box which shows which command will be run. Package options are shown following the number of LaTeX passes, in quotes. If nothing is shown, you will be producing HTML-4 output, and your files will have extension .html. To change this, or to configure the HTML, click the Advanced button. In the new screen, choose your options. However, note that if your document explicitly refers to the swpht package, then any options you specify here will be ignored. (That is, the options you explicitly specify in the document are assumed to take precedence, which is usually what you want.)

• The output type (HTML version) is selected under Output Formats. Your options are
  • HTML-4, with formatting instructions contained in a .css file. This is usually the preferred format.
  • HTML-3.2, with all formatting instructions internal to the HTML file.
  • You can also obtain output with no hypertext tags, a sort of “detex” translation, by checking Text-based output.
• To produce HTML files with extension .htm check the box next to Use DOS 8.3 Format in the Further Options section
• If you wish to include a configuration file, you can select it under Further Options. Note that You must use a configuration file if you are converting a Portable LaTeX document containing pictures, but generally TeX4ht/SWP will include the correct file automatically. See 13 for more on this. Thus you usually do not need to re-specify it here.
• When you have selected your options, click OK: this returns you to the main TeXConverter/TeX4ht tab.

D.3.4 Running the TeXConverter

When you have made all your selections, click Convert.

TrueTeX will run, and if you asked the TeXConverter to display the output you should see the same file you obtained when you originally tested TeX4ht/SWP.

Appendix E Adding a Directory to Your Path

If you needed to create a new directory for the TeX4ht/SWP batch files, here’s how to add this to your path. We’ll assume, for purposes of illustration, that you want to add c:\utility to your path.

E.1 Windows NT

• From the Control Panel, click on the System application, and then on the Environment tab
• In the System Variables display, scroll down until you find Path. At this point the input box labelled Variable should contain Path.
• The last input box contains the current value for your path.
• Scroll forward to the last entry, then add a semicolon (;) followed by the name of the new directory; so in the example you’d add ;c:\utility
• Click Set
• Click Apply
• Click OK and close the Control Panel.

You can now start a DOS session and type path : the response should show that the new element is indeed part of your path.

E.2 Windows 95/ 98

• Open c:\autoexec.bat in a text editor like NotePad.
• Find the line beginning path=
• At the end of the line, add a semi-colon (;) followed by the name of the directory you are adding (so in the example, you’d add ;c:\utility)
• Save the file
• Re-boot.

When your system re-starts, you can start a DOS session and type path. The response should show that the new element is indeed part of your path.

Appendix F Older versions of ImageMagick

Some time after ImageMagick 5.2.3, the convert switch to obtain a transparent background was changed from -transparency to -transparent. (Don’t ask me why). The distribution assumes that you have the latest version of ImageMagick, and consequently uses -tranparent. If you have an older version, you need to see which switch is applicable. To do this:

• Open convert.html (in the ImageMagick www subdirectory in a browser).
• Find the switch (they’re listed in alphabetical order).
• If your version of convert uses -transparency you will need to edit the following files, all of which are in c:\tex4ht, and change -tranparent to -transparency:
  • tex4htx.env (note: if you are also using MiKTeX, you may want to make the same change in tex4ht.env)
  • tex4ht-im.bat and tex4ht-im2.bat (2 instances each).
  • gifglyph.bat

Appendix G Advanced Configuration of htrun

htrun opens your document and looks for one of a set of strings which identify the document type. It then calls the appropriate batch file. Both the strings and the batch files are user-configurable, though in most cases there will be no need to do this. All data used by the program is contained in htrun.ini, located (with htrun.exe) somewhere in your path. You can remind yourself where by starting a DOS session and running htrun with no arguments. The program then displays a screen of information.

The htrun logic is shown in the following table:

There is one important thing to bear in mind when attempting to set up your own batch files. htrun does not actually run the batch file named in the .ini file: instead it appends a Translation Prefix to the name, and runs that batch file. The default Translation Prefix is ht. Thus, if a batch file entry says swps.bat then htrun will actually try to run the batch file htswps.bat. The reason for this is to facilitate alternative output format like XML: see section 18 for more on this. Before running the selected batch file, htrun looks for it in your path, and will refuse to run if the file isn’t found.

The following options are supported in the [integers] section (any omitted statement in this series is taken to be “off”, equivalent to =0):

• DEBFLAG=1 : additional information is sent to your DOS session console.
• RDEBFLAG=1 : the system will not actually run the selected batch file, so you can see what would be done with your source file.
• PAUSE=1 : htrun will pause and wait for you to press a key before executing the batch file, and you’ll see what’s about to happen.
• LATEX209=1 : this allows you to use separate batch files for processing LaTeX2e and LaTeX 2.09 files. This is required for the TrueTeX compiler under Windows 98 (and probably Win 95 too). It is the default setting for TeX4ht/SWP.
• PACKQUOTE=1 : The TeX compiler may balk if you try to pass it an empty (ie  " "   ) argument for the TeX4ht package. The solution is to pass a blank instead (ie  "  "   ). If PACKQUOTE=1, then htrun will expand  " "   in the TeX4ht package position only and insert the needed blank space. This appears necessary under Win NT4 — but not under Win 98. However, it is the default in the TeX4ht/SWP distribution.

Finally, note that the document-recognition strategy isn’t foolproof. Consider a plain-TeX file containing \input texinfo in a verbatim-like environment. (You’re illustrating the use of this command). This will be — mistakenly — recognized as a TeX4ht-processable TeXInfo file, instead of a plain-TeX file requiring some additional code (the string in CSNAME) before being processed by TeX4ht. Short of building a mini TeX parser, I don’t see how I can cope with this. Of course, LaTeX, with its well-defined notion of a preamble, is much less susceptible to this sort of thing.

Appendix H Advanced Configuration of swpinstall.exe

Almost everything in swpinstall.exe is user configurable, via an entry in swpinstall.ini.

• For every path variable of the form xxxDir there is a corresponding file variable xxxCheck, which you can set. The effect is that we look for xxxDir\xxxCheck as a way of validating your data.
• The name of the top-level batch file (default, top.bat) can be changed by specifying a topname entry in the [strings] section.
• Similarly, the name of the batch file executed by the top-level file (default, tinstall.bat) can be specified by the batname entry. Note that the program expects to find batname.bt1 and batname.bt2, from which to construct this batch file.
• In the [integers] section, you can turn off all file-checking by setting CHECKFLAG=0
• In the [integers] section, the environment size provided by the top-level batch file can be set by specifying envsize=nnnn. Default = 2048. On the other hand, if that’s all you need to change, it’s obviously simpler to edit top.bat directly.

Appendix I SWP Version 4+

With version 4.0 or later, the SWP family of products — including Scientific Notebook — allows you to create HTML directly from your on-screen files. As with TeX4ht, graphic images are used for mathematics, but because the internal Copy-As-Picture procedure is used to create them, the process is not only transparent to you, it is much faster than TeX4ht’s DVIPS+GhostScript+ImageMagick solution. For SN users who have previously used Hevea to create HTML, the new facility gives you a the ability to create HTML showing all your math without relying on glyphs being present in the Symbol font; and this is a major improvement. However, for SW and SWP users, who have access to LaTeX, there are a few limitations of the new facility that you need to be aware of.

I.1 Some Version 4 issues

No LaTeX The easiest way to understand the new HTML feature in SWP is to realize that it is creating hypertext from what is available on your SWP screen. In particular LaTeX is never used. This has a number of consequences, including:

• You cannot create a Table-of-Contents, linked or not. Or List of Figures, List of Tables, etc.
• BibTeX citations are handled by spelling out the contents of the \cite field, and the .bbl file itself is never used. For example, if your screen says “as demonstrated in [cite: Viton:2001]” the HTML will say exactly that; and no reference list is generated. TeX4ht, on the other hand, will use the contents of the bbl file to generate references exactly as they’d appear in typeset output; and the References section will also be produced.
• Subdocuments and other documents incorporated by \include are silently ignored.
• User-supplied TeX fields are “expanded” but have no effect, beyond printing out their contents. For example, I generally include the date via a \today fragment. The HTML export feature just produces \today() (the contents of the fragment) in the hypertext file.

Browser sensitivity The HTML produced by Version 4’s Export feature appears to be unusually sensitive to the browser. This applies particularly to inline math viewed in Netscape 4.7 (or presumably any of the 4.x series), which has severe alignment problems. However, alignment as viewed in Internet Explorer 5.0+ or Netscape 6.2 (possibly also 6.0+) is excellent. See below for a test.

Some appearance issues As noted above, the layout of the HTML is based on the screen appearance of your document (with several modifications, such as not using red for mathematics). If you’ve become used to not worrying much about the screen appearance on the grounds that LaTeX will take care of all the formatting for you, you may need to reconsider. TeX4ht, on the other hand, is independent of the screen appearance. (Conversely, if you want control over the appearance of your HTML, SWP 4’s .cst files provide a particularly easy way to get it, without worrying about LaTeX packages or TeX4ht configuration files). There are a couple of other issues you need to be aware of, some of which are fixable.

• HTML Export doesn’t treat the front-matter well: it is translated as ordinary paragraph text. Fortunately, this is easily corrected: open htmlout.cfg (in your top-level SWP directory) and add the following lines to the end of the [STYLEHEADER] section, and before the closing </SCRIPT>:

  P.Author {font-size: large ; text-align: center}

  P.Title {font-size: large ; text-align: center}

  You can use these as a model of other elements in the front-matter; if you want the text to be displayed in bold, you can add ; font-weight: bold to the descriptors. Note that once you’ve done this, it will be used in all your conversions, which is presumably what you want; however, there is no provision for document-specific configuration.

• Cross-references are silently ignored. There is a partial fix for this, too (at least as long as your cross-references are to material in the same document): open htmlout.dat (in your top-level SWP directory) and replace the definitions of \QTSN{label}#2 and \QTSN#1#2 given there (at about line 515) as follows:

  \QTSN{label}#2 modeless textarg "<A NAME=""#2""></A>"

  \QTSN#1#2 modeless "<A HREF=""##2"">#2</A>"

• Equation labels are also silently ignored, and the previous fix doesn’t work correctly here. It will generate a link where you have your cross-reference, but because the label attached to the equation itself is ignored, that link won’t work correctly: in Netscape 4 it takes you to the top of the document. I know of no way to get equation labels to work.
• There can be a problem with a free-standing “f” in math mode (“free standing” as opposed to, say, an “f” followed by an open-parenthesis or other math). The graphic created by the HTML-Export feature may be missing both the ascender and descender and can look nothing like an italic “f”. The reason is that the TrueType bounding box for this character does not include parts of the character, as you can verify by highlighting it on your SWP screen; and SWP uses that information in deciding on the size of the graphic. One possible work-around is to surround the “f” with a thinspace in math mode; this helps, but may have undesirable implications for your typeset output, if you also need to produce that.

If these features are important to you, then you may wish to stick with a converter like TeX4ht, which handles them all correctly, albeit with a time cost.

I.2 A comparative test of HTML production

I have created a small test to show how the various HTML translation systems compare on the same source document. You can view it starting from here , and my advice is to do so in as many different browsers as you can, before you decide on your HTML strategy.

Appendix J Legal Matters

TeX4ht/SWP (‘The SWP Support for TeX4ht’) described here provides a means of integrating a number of free, shareware and commercial products: among these are TeX4ht, Aladdin GhostScript, ImageMagick, Irfan-View, TrueTeX, Microsoft Windows, the TeXConverter and the Mackichan Software family of products: Scientific Word, Scientific WorkPlace and, to a limited extent, Scientific Notebook. I am not the author of any of these products, nor am I employed by the developers of any of them.

J.1 Disclaimer of liability

(The following text is taken from LaTeX Project Public License, modified to refer specifically to the SWP support).

There is no warranty for The SWP Support for TeX4ht. Except when otherwise stated in writing, I provide The SWP Support for TeX4ht ‘as is’, without warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. The entire risk as to the quality and performance of The SWP Support for TeX4ht with you. Should The SWP Support for TeX4ht prove defective, you assume the cost of all necessary servicing, repair, or correction.

In no event unless agreed to in writing will I, or any author named in the files of The SWP Support for TeX4ht, or any other party who may distribute and/or modify The SWP Support for TeX4ht as permitted below, be liable to you for damages, including any general, special, incidental or consequential damages arising out of any use of The SWP Support for TeX4ht or out of inability to use The SWP Support for TeX4ht (including, but not limited to, loss of data, data being rendered inaccurate, or losses sustained by anyone as a result of any failure of The SWP Support for TeX4ht to operate with any other programs), even if I or said other party has been advised of the possibility of such damages.

J.2 Redistribution

(The following text is taken from LaTeX Project Public License, modified to refer specifically to the SWP support, to remove conditions specific to LaTeX).

You may distribute a complete, unmodified copy of The SWP Support for TeX4ht. Distribution of only part of The SWP Support for TeX4ht is not allowed. You may not modify in any way a file of The SWP Support for TeX4ht that bears a legal notice forbidding modification of that file. You may distribute a modified file of The SWP Support for TeX4ht if, and only if, the following six conditions are met:

1. You must not distribute the modified file with the filename of the original file.
2. In the modified file, you must acknowledge the authorship and name of the original file, and the name (if any) of the program which contains it.
3. You must change any identification string in the file to indicate clearly that the modified file is not part of The SWP Support for TeX4ht.
4. You must change any addresses in the modified file for the reporting of errors in the file or in The SWP Support for TeX4ht generally to ensure that reports for files no longer maintained by the original maintainers will be directed to the maintainers of the modified files.
5. You must distribute the modified file under a license that forbids distribution both of the modified file and of any files derived from the modified file with the filename of the original file.
6. You must do either (a) or (b):
   1. distribute a copy of TheSWP Support for TeX4ht (that is, a complete, unmodified copy of The SWP Support for TeX4ht) together with the modified file; if your distribution of the modified file is made by offering access to copy the modified file from a designated place, then offering equivalent access to copy The SWP Support for TeX4ht from the same place meets this condition, even though third parties are not compelled to copy The SWP Support for TeX4ht along with the modified file;
   2. provide to those who receive the modified file information that is sufficient for them to obtain a copy of The SWP Support for TeX4ht; for example, you may provide a Uniform Resource Locator (URL) for a site that you expect will provide them with a copy of The SWP Support for TeX4ht free of charge (either the version from which your modification is derived, or perhaps a later version).

Note that in the above, ‘distribution’ of a file means making the file available to others by any means. This includes, for instance, installing the file on any machine in such a way that the file is accessible by users other than yourself. ‘Modification’ of a file means any procedure that produces a derivative file under any applicable law – that is, a file containing the original file or a significant portion of it, either verbatim or with modifications and/or translated into another language.

Changing the name of a file (other than as necessitated by the file conventions of the target file systems) is considered to be a modification of the file.

The distribution conditions in this license do not have to be applied to files that have been modified in accordance with the above conditions. Note, however, that Condition 5 does apply to any such modified file.

The conditions above are not intended to prohibit, and hence do not apply to, the updating, by any method, of a file so that it becomes identical to the latest version of that file of The SWP Support for TeX4ht.