Part III
Hevea and Hacha for SWP

10 The SWP user interface

The SWP interface consists of a set of batch files, and facilities for customizing the translation process, as described in the next sub-section.

The batch files all have the same syntax: for the basic plain-L^AT_EX-to-HTML translation file hhtml.bat this is:

: hhtml [other options] myfile or hhtml [other options] myfile.tex

where myfile is the name of your source file. Calling any of the batch files (except fhevea.bat, see below) without any arguments prints a brief summary of its purpose and syntax. This syntax isn't completely strict: while the names of all Hevea packages must precede the name of the source file (here, myfile or myfile.tex), command-line switches (eg -v) may follow the source name.

To translate a LaTeX source myfile.tex:

Close your document in SWP.

Start a DOS session, switch to the directory containing your source document and call the appropriate batch file with the name of your source (.tex) file as shown in the table below. Hevea will produce a file with the same name and with extension .html or .txt depending on whether you're translating to HTML or text.

Document Type Batch File Example

Standard L^AT_EX book hhtml.bat hhtml myfile

Standard L^AT_EX report hhtml.bat hhtml myfile

Standard L^AT_EX article hhtml.bat hhtml myfile

Style Editor book sebook.bat sebook myfile

Style Editor report sereport.bat sereport myfile

Style Editor article seart.bat seart myfile

Scientific Notebook hhtml.bat hhtml myfile

Non-SWP L^AT_EX hevea.bat hevea myfile

Run Hevea in filter mode fhevea.bat fhevea

Translate to plain text (w/SWP support) htext.bat htext myfile

Translate to Info (w/o SWP support) hinfo.bat hinfo myfile

Notes:

Translating standard-L^AT_EX-whatever-class documents use the same batch file, while Style Editor documents require different files according to the “type” (class) of document being processed. See section 10.2.
Scientific Notebook support is provided through the hhtml.bat file. See section 13.
hevea.bat does not include any SWP support.
fhevea.bat runs Hevea in filter mode, providing a quick way to see what output the system produces for a short L^AT_EX fragment. To start Hevea in filter mode, just call fhevea without the name of source (.tex)file. As supplied, the batch file runs without using any style (.hva) files; you can add them on the command line when you call the program.

When Hevea starts, you're presented with a blank line. You can then type in some L^AT_EX (multiple lines are OK). When you're finished, start a new line and enter Ctrl+Z. Hevea will respond with its translation of your input. See section 19.2 for an example.

10.1 Configuration files

Hevea's strength lies in its programmability: if your document contains non-standard macros, you can easily tell Hevea how to deal with them. Those instructions should be seen only by Hevea. Non SWP-users would insert specially commented text into the source file, but this won't work in SWP, because comments are moved to a special section of the document, where they'll probably not have the effect you're expecting. For this reason, the SWP implementation provides for three kinds of configuration files: a general file, a personal file, and a file specific to the current document. Any of these can add to or modify Hevea's built-in instructions for generating HTML.

The general file is swp.hva, located in the html and text subdirectories of your Hevea installation. It is commented, and describes a few decisions you may wish to change. A list of the macros defined in swp.hva appears in Appendix D.
The personal configuration file allows you to include your own “permanent” additions or changes to swp.hva, ones which you'd like to have automatically available every time you run Hevea. Because swp.hva may change as Hevea changes, you should not modify that file: your changes will be lost when you upgrade Hevea. Rather, you should start a personal configuration file, say dek.hva, place versions in the \html and \text subdirectories of the main Hevea directory, and edit the batch files to include it on the line calling Hevea, after swp.hva and before xhvbc.hva. Since these files are processed left-to-right, your personal file will over-write previous instructions.
The third configuration file is specific to the current document. It must be located in the same directory as the source (.tex) document, and must have the name of the source, plus the extension .hvb for HTML translation and .hvc for text translation. It it exists, it will be read in just before your document. Note that these files are an extension to Hevea: they are not automatically read by the program, and they are not supported by Luc Maranget. See Part V for an example of using configuration files.

Important: document-specific configuration files are supported by the Hevea file xhvbc.hva. This is a very recent addition to the Hevea-SWP system, and is not thoroughly tested. For this reason, I also provide an alternative set of older batch files. If Hevea seems not to be finding your .hvb files, you should try these alternative files: see Appendix F.

As supplied, the xhvbc.hva files print a message to the terminal if they find a document-specific configuration file. If you'd rather not see this, edit the file and remove the \typeout{... } macro. If you'd like to be told when Hevea hasn't found a configuration file, you can replace \relax by something like \typeout{HeVeA has not found your configuration file}.

10.2 Style Editor documents

As the Table shows, translating a Style Editor document is more complicated than translating a “regular” L^AT_EX document: you must use a batch file corresponding to the kind of document you're working with. This is because when Hevea starts, it looks at your document's “class”, and then inputs an .hva file corresponding to that class. (See section 10.3). For Style Editor documents this doesn't work. The base class for all Style Editor documents is sebase, and this gives no clue to what the document is actually about: that is, a Style Editor Book and a Style Editor Article will both use the same sebase class.

To cope with this, we provide a file sebase.hva, which Hevea will load when processing a Style Editor document; but this is essentially a do-nothing file — it just loads a couple of packages (theorem and ams, as in sebase.cls). The user needs to tell Hevea whether the document is an Article, a Book, or a Report⁴ and then arrange for the appropriate .hva file to be loaded. This is what the SE batch files do.

10.3 Other document classes

When Hevea sees the statement

: \documentclass{myclass}

at the beginning of your document, it attempts to open myclass.hva, and if this file is not found, will quit with an error message. You need to provide some guidance. In the simplest case, myclass will be a variant of one of the three standard L^AT_EX classes, perhaps providing a different appearance to the typeset document; and possibly defining some new macros. To get started:

Create myclass.hva in the \html directory of the Hevea installation.
Ask Hevea to consider this a variant of an existing class. If, say, the article class is the closest match, say
\input{article.hva}
If you anticipate doing text translation, copy this file to the \text subdirectory.

You will still need to provide for any specialized myclass macros used in your document. See Part V for the techniques. If you know that a macro is defined in myclass.cls you can enter it into myclass.hva; otherwise put it in a document-specific configuration file.

10.4 Text translation

Beginning with version 1.04, Hevea can translate your L^AT_EX into plain text. Obviously this can only work well when the document contains little or no mathematics. In text mode, Hevea looks for its .hva files in the \text subdirectory (rather than \html). Since this probably isn't something you'll do often, we provide only limited SWP support via the batch file htext.bat (and the associated Hevea style file swp.hva in the \text subdirectory).

Under text translation, a document-specific configuration file is assumed to have extension .hvc. (You can't use the same one as for HTML translation since you don't want to write HMTL code). Throughout this write-up I'll refer to the document-specific files as .hvb files, but you should remember that everything applies to .hvc files as well.
There are no separate text-translation files for Style Editor document types. Instead, sebase.hva loads the Book class, book.hva. This is more general than the Article class; the main difference is in how sections are “decorated” in the resulting text. If this is a problem, you can always imitate the batch files used for Style Editor translation to HTML.
The batch file htext.bat writes text 72 characters wide, Hevea's default. You can change this by editing the batch file itself, or by including the switch -w n on the command line, where n is the desired line width in characters.

11 Support for SWP graphics

SWP supports a wide variety of graphics through the \FRAME macro, or, if you select the Portable L^AT_EX option, via \includegraphics. As of Hevea version 1.05, \FRAME is supported internally; and, in a reversal of the usual strategy, we handle \includegraphics by translating it to \FRAME (!)⁵

Here's how it works. When Hevea sees a graphics macro, it reads the name of the graphics file, strips off all directory information, and writes an HTML IMG tag referring to your file, with the extension .gif. For example, if your .tex file contains a reference to the graphics file

 '../../../swwrk/airmalm.cgm'

Hevea will write the following tag into your HTML file:

<IMG SRC=''airmalm.gif'' ALT=''Graphic: airmalm.gif''> .

It is your responsibility to actually generate a .gif file from whatever graphics format you use in your source file.⁶ Note that all scaling, framing and float properties of your SWP graphic are ignored in the Hevea support.

Note that the SWP support over-rides the definition of \includegraphics loaded by the graphicx pacakge: this geenrates a warning, which should be ignored.

11.1 Maple graphics

(This section applies only to Scientific WorkPlace and Scientific NoteBook). Maple graphics are fully supported provided that you have generated the necessary snapshot files. Snapshots are free-standing pictures of your plots; since they are needed only when you typeset-print or typeset-preview your document, the snapshot-generation facility is normally turned off when you install SWP or SN. When no snapshot is found, two things happen:

Hevea prints a warning to your terminal:
.\test.tex:47: \FRAME: no filename (missing snapshot?) - using fallback name
It inserts a “dummy” IMG tag naming the fallback file FRAME-graphic-not-found. If you display the resulting HTML file in a browser, you will probably see some sort of icon indicating that the graphic is not available. This is a reminder that you need to generate a snapshot.

For Scientific WorkPlace documents, if you can typeset-print or typeset-preview your work, then the necessary snapshot files are present.

11.2 CustomNotes graphics

SWP uses CustomNote macros to handle Margin Hints, Solution Notes, Answer Notes, etc (and SN uses CustomNotes also for footnotes). On screen, these are typically represented by a graphic, which you'd click to view the contents. swp.hva (like tcilatex.tex) handles these fields by converting them to margin paragraphs; and then margin paragraphs are converted to footnotes. (This means that the CustomNotes will appear intermingled with your “real” footnotes, if you have them). The first argument of the \CustomNote macro, which typically contains a reference to the on-screen icon in a \FRAME, is ignored; thus you will not need to provide .gif versions of them.

11.3 Customizing graphics handling

It is easy to customize graphics handling because when Hevea sees a \FRAME macro, it extracts the name of the graphic, and then calls another macro \swFRAME to handle the HTML writing. The \swFRAME macro is defined in swp.hva, and you can alter it to suit your needs. One thing you might want to do is to alter the default graphics extension: this is given by the macro \swEXT: if you want your IMG tags to refer to .jpg graphics instead of the default .gif , all you need to do is change

\def\swEXT{.gif}

\def\swEXT{.jpg}

You can get additional control over the HTML by re-writing \swFRAME itself. Either of these changes can be placed in a document-specific configuration file.

You might want to have Hevea show the names of the graphics as it encounters them, as a reminder that you need to convert them (obviously this works best if you use the error-recording technique described in Appendix C). To do this, change the line in swp.hva beginning

: \renewcommand{\swFRAME}[1]{\@print{<IMG SRC=”} ...

to something like

: \renewcommand{\swFRAME}[1]{\typeout{Graphic: #1\swEXT}\@print{<IMG SRC=”}...

12 Unicode

SWP's two Unicode macros are fully supported. For versions prior to SWP 3.5 we had a macro of the form \UNICODE{0xe5}, while, to save space, SWP 3.5 introduced a new macro, like \U{e5}. These macros are handled as follows:

The \UNICODE macro is handled internally. Because few browsers support Unicode entities in hex form, Hevea converts the argument to its decimal equivalent. It then calls a supplementary macro \swUNICODE to actually write the material into the HTML file.
\swUNICODE sees two arguments: the hex number without the leading 0 (so in the example, xe5) and the decimal equivalent. These arrive without any formatting; it is up to the macro to add the appropriate formatting to transform the desired representation into an HTML entity. As distributed, \swUNICODE uses the decimal form (argument 2); prefixes &# and appends ; to make the HTML entity of the form å. The \swUNICODE macro is defined in swp.hva; you can alter it to suit.
The \U macro prefixes 0x to its argument, and calls \UNICODE. \U is defined in swp.hva.

Note that whether your readers will be able to see Unicode characters depends on their having an appropriate font installed. In particular you probably need to tell your browser that you are using the UTF-8 character set. If your Unicode characters display as question marks, this is necessary: Netscape 4.08 requires it, but Internet Explorer 5 does not. I take it that this means, by virtue of the lowest-common-denominator approach, that if your source uses Unicode, you will always want to do this.

To enable the alternate character set, you must re-define the default META information provided by Hevea, which specifies the ISO-8859-1 character set. The following (taken directly from hevea.hva) will do this, if you put it in a document-specific configuration file:

\renewcommand{\@meta}{\@print{<META http-equiv=''Content-Type'' content=''text/html; charset= UTF-8''>
}%
\@print{<META name=''GENERATOR'' content=''hevea }\usebox{\@heveaversion}\@print{''>
}}

It's probably easiest to open \html\hevea.hva and cut-and-paste — remember to change \newcommand to \renewcommand — rather than copying this text.

13 Scientific Notebook

I don't use Scientific Notebook myself, and though I've tried to support it under Hevea, this support is largely untested. There are two things to bear in mind:

You will need to generate snapshot files for Maple graphics: since SN prints and previews in “native Windows mode”, you'd ordinarily have no occasion to do this.
As far as I can tell, SN files are a subset of the L^AT_EX in SWP's standard-L^AT_EX-article-class documents. Thus, we process them though the “standard” batch file hhtml.bat. If this changes, then the Scientific Notebook support will have to be re-worked, perhaps through a more specialized batch file.

14 Hacha, the file-chopper

Hacha takes a single HTML file produced by Hevea⁷ and chops it into smaller files. It generates a top-level file containing a table-of-contents, and each item in the TOC is a hyper-link to one of the smaller files. These files in turn contain icons which allow the reader to move to the next (or previous) file in the series, as well as an icon to return to the TOC. These icons will be automatically copied to your source-file directory: remember to move them to your web site.

Hacha.bat takes a single argument, the name+extension of the HTML file produced by Hevea. By default, the resulting top-level file is called index.html, and the names of the smaller sub-files are built from the name of the Hevea file. Thus

Hacha myfile.html

produces the base file index.html containing the TOC, and the series of hyper-linked sub-files myfile001.html, myfile002.html ... . If you would prefer another name for the base file, you can use the command-line option -o. The sub-files' names are unchanged.

The simplest way to control Hacha is via the document-specific configuration file. For example, I wanted the online version of this document to be split into its Parts, so I inserted \newcommand{\cuttingunit}{part} into a document-specific configuration file. This generates a warning that can be ignored; and produces the desired result.

Part III Hevea and Hacha for SWP