Previous Up Next

Part III
Hevea and Hacha for SWP

9  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-LATEX-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:

Notes:

9.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.

9.2  Style Editor documents

As the Table shows, translating a Style Editor document is more complicated than translating a “regular” LATEX 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 9.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 Report4 and then arrange for the appropriate .hva file to be loaded. This is what the SE batch files do.

9.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 LATEX classes, perhaps providing a different appearance to the typeset document; and possibly defining some new macros. To get started:

  1. Create myclass.hva in the \html directory of the Hevea installation.
  2. Ask Hevea to consider this a variant of an existing class. If, say, the article class is the closest match, say
    \input{article.hva}
  3. 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.

9.4  Text translation

Beginning with version 1.04, Hevea can translate your LATEX 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).

10  Support for SWP graphics

SWP supports a wide variety of graphics through the \FRAME macro, or, if you select the Portable LATEX 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 (!)5

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.6 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.

10.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:

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

10.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.

10.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}

to

\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=’’}

11  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:

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.

12  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:

13  Hacha, the file-chopper

Hacha takes a single HTML file produced by Hevea7 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 — as you might, for consistency — you can use the command-line option -o. Thus if you say Hacha myfile.html -o myfile000.html you will generate a lead file myfile000.html that will refer to myfile001.html, myfile002.html etc. Note that there is no way to change the names of the sub-files (here, myfile001.html, myfile.002.html etc).

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.


Previous Up Next