HEAD PREVIOUS

B  Appendix: Frequently Asked Questions

B.1  Building and Running TTH

Why does my compiler crash when compiling TTH?  
TTH comes in the form of a single C source file because it is mostly one very large function which is produced by flex. It is completely standard C code but the size challenges compilers' capabilities, especially if you try to optimize using the -O switch. With gcc under linux it is possible to compile an optimized version, but optimization hardly affects the speed and reduces the disk size of the already modest executable only by about 20%. Therefore it is no significant loss to compile without optimization. Under DOS, even unoptimized compilation can cause DJGPP to crash if its stack size is less than about 1024k. The fix (using stubedit on cc1.exe) for this DJGPP bug is described in its FAQ.
Why does my TTH executable, which I compiled myself, crash?  
Assuming that this is not a problem caused by invalid TEX, or by you poking around inside the C code, it is probably a compiler shortcoming. Some default settings of some compilers give TTH too little stack space and cause it to crash. Most self-respecting compilers have switches or settings to increase that space. Try increasing it, or get one of the binary distributions.
Why won't TTH run from Program Manager in Wind*ws?  
You need a command line. Call up the DOS prompt. If you feel the need for a drag and drop facility, get TTHgold.

B.2  [La]TeX constructs TTH does not seem to recognize

TTH does not recognize tableofcontents, backward references, listoffigures, ...  
Yes it does, see section 6.1, and use the -L switch.
TTH does not insert my picture environments.  
If picture environment pictures are to be included, conversion to a gif file is needed. See 6.5.
TTH messes up my tabbing environment.  
Tabbing is not currently supported. It is alien to the HTML document mark-up approach. See section 7.
Why doesn't \frac work in equations?  
It does, but only in LATEX documents because \frac is not a plain TEX command. The document you are presenting to TTH doubtless has no \documentclass command and other LATEX blurb at the top. If you insist on having LATEX commands available in such a document, you can use the -L switch. But note that other changes in interpretation (e.g. in footnotes) are implied by using this switch to tell TTH that this is a LATEX file.
Why does TTH not recognize ... command from ... style package?  
Let's be perfectly clear here. TTH does not currently recognize \usepackage and, with the exception of commands explicitly mentioned in this manual, does not support any of the zillions of extensions to LATEX that exist, even if they are part of the "standard distribution". TTH does support macro definitions, see section 9.2, and you might find that if you explicitly \input the style file that you need it will recognize the macro. However, many LATEX extension packages are written in a complicated manner such that they depend on changes in catcodes, which TTH does not support. Therefore no guarantee can be given. This is one reason why TTH deliberately does not recognize \usepackage.
Why does TTH not recognize my ends of lines properly?  
If you transfer a file from one operating system to another as a binary file, the line-end codes are likely to be messed up. They use different codes on Un*x, DOS, and Mac. Usually TEX is not bothered by this. TTH is somewhat more sensitive. Use ASCII transfer.
Why does TTH complain about my skip, space, ... command?  
Dimensions are often inappropriate for HTML. TTH tries do something sensible with dimension, space, and glue commands. Usually it is successful. If so, you need do nothing. In some rare cases, you might see some irrelevant left-over characters from the dimension command that have to be removed by hand.
Can TTH be made to support BibTEX bibliographies?  
It already does; see 6.2. If TTH is not finding the .bbl file even though you used the -L switch, then you probably forgot to generate it using LATEX and BibTEX, or perhaps it is in the wrong place. Try using the TTH switch -a.
Does TTH support ...?  
Probably yes if it is part of LATEX. But if you want a specific additional capability, and find that it is not supported, why not write a TeX macro to support it and translate it into suitable HTML using the functions described in this manual. Then you will have your support and if you send it to tth(at)hutchinson.belmont.ma.us (with the usual character substituted in the email address), it may be possible to include it into the standard TTH executable and you'll have helped all the other users of TTH.

B.3  HTML output that does not satisfy

Why doesn't TTH automatically generate   <head> and <body> HTML tags?
First, the <head> and <body> tags are optional in the HTML specification. There is no need for TTH to generate them to statisfy the standard. Second, TEX and LATEX files do not have a corresponding structural division into separate head and body sections. It might seem as if LATEX does, with \begin{document} being the divider, but there are many cases where this mapping is incorrect. For example title may not be defined until after \begin{document}, corresponding to the HTML body section, whereas it must be in the head section. Finally, if TTH automatically entered <head> and <body> tags, then the thoughtful author would not be able to enter them where they ought to be by using, for example:
%%tth: \begin{html} <head> \end{html}
Therefore, the choice not to produce these tags automatically is a deliberate one based on a careful consideration of the advantages and disadvantages. An author can always adjust their TEX code to include them, if they wish to be pedantic about the division. See also the section on HTML style [12.2].
Why don't TEX commands get expanded in the HTML title?  
In HTML, the stuff that goes in the <title>...</title> of a page is not permitted by the specification to contain HTML tags - things in angle brackets - and tags are not interpreted. If an equation or some other command that TTH translates into HTML formatting is in the title, then the title will break when expanded. Therefore TTH deals with commands differently in the title. By default it leaves them in the TEX form that they started as, since that is about as easy to read as any unformatted mathematics. Using the -n? switch enables control of the precise behaviour. See 3.
How do I make TTH border my tabular table?  
TTH looks in the format string argument of the begin{tabular} environment and if it begins with a | (vertical bar) then the HTML table is bordered.
TTH inserts the title and author even without the maketitle command  
True, TTH inserts them when you define them. This gives you a chance to fine-tune the presentation if you wish.
What is this strange result using \dot \hat \tilde \frac \vec ... in in-line equations?  
Neither over and under accents nor built-up constructs such as fractions can be rendered in-line (i.e. in a textstyle equation produced by $ ... $) in HTML. Therefore, TTH outputs something that is not elegant but reasonably indicates the original intention. Additional brackets are inserted to ensure that fractions are unambiguous. TTH will render all these built-up constructs correctly in a display equation. See also 5.2 and 5.3 for alternatives.
Why does the large square root sign look so ugly?  
There are some things that browser symbol fonts can't do well.
Why does a dagger sign come out strange?  
Browsers don't generally have a dagger sign in their fonts. TTH uses a kludge.
The file I "published" using Netscape Composer looks messed up when viewed on a Mac.  
Don't use Composer on TTH documents. See section 13.4.
Why does TTH mess up my \fbox, minipage, etc?  
The whole concept of a "box" is not really translatable into HTML. TTH tries to mimic the box using tables. But in some cases, especially in equations, it can't cope.
How do I get caligraphic fonts, {\cal E}, AMS fonts, etc?  
You can't because browsers don't have access to them. TTH can only support fonts that are available on the browsers that eventually visit the page. By default TTH tells the browser to render caligraphic as italic helvetica font. You may, if you wish, define \cal to be something different, such as %%tth:\def\cal{\it\color{red}}.
Why does TTH turn double-quotes into an accent instead of quotes?  
In basic TEX the double quotes character " is not defined, and hence may do anything that the local installation feels like. Double quotes must be inserted by using two quote " or back-quote " characters. In German TEX implementations, the double-quotes character is used to provide the umlaut over accent and for some other special needs. TTH supports these German uses in some appropriate contexts. English speakers should adopt proper TEX quote usage. There is essentially never a situation in LATEX where it is advisable to use a double quote to represent itself outside of a verbatim section (where it will naturally be treated literally). In Plain TEX you might need it. If so, \char`" is an absolutely fool-proof way to insert it. Here it is:". You can also just enclose it in braces thus:{"}.
Why doesn't TtH output use < p > for paragraphs?  
For the first years of its existence it did. However, standards of HTML interpretation have grown tighter to the point where <p> is a great liability. In XHTML (the latest HTML standard) <p> is a container element. It must have a closing </p>; so that every paragraph must be its own group. This compulsion is contrary to TEX usage. Therefore TtH changed to dispense completely with any use of <p>, using an empty <div> with an associated CSS style instead. This has the significant benefit of ensuring that for standards-compliant browsers, font changes propagate even into the cells of tables. (NS4 is not compliant, Mozilla, NS7 etc are, in this respect.)

B.4  How to write TEX designed for Web publishing

How do I insert code that is used only by TTH, not TEX?  
Use %%tth: followed by the material you wish to pass to TTH. TEX omits this line as a comment. Alternatively, insert \newif\iftth at the top of your document, then use a conditional: \iftth \TtH\ material \fi. TtH recognizes \iftth as a special `if' that is always true, whereas to TEX it is simply a new `if', which by default is false when defined.
How do I insert HTML tags into my file without TEX knowing?  
Use %%tth: then on this line put \begin{html} tags \end{html}. Do not try to continue this html onto a second line with a second %%tth: before the \end{html} because the html environment will output the %%tth:, which it probably not what you want. Another way to pass codes directly to the output is the \special{html: ... } command. Do not use \begin{verbatim} to pass HTML tags. It will convert the greater than and less than signs to make them appear in the display and not be interpreted as tags.
How do I insert code that is used only by TEX, not TTH?  
Insert \newif\iftth at the top of the file and then use the conditional constr uction: 
\iftth\beginsection{The \TtH\ Header}\par\else\beginsection{The \TeX\ Header}\fi
The `else' clause may also be used with a blank first clause, of course: \iftth\else ... \fi. Alternatively, insert the definition \def\tthdump#1{#1} at the top of the file and then use \tthdump{\TeX\ material} to pass stuff only to TEX. The command \tthdump is an internal command for TTH (which cannot be redefined) that simply discards its argument. Thus, for example, the following will output alternate versions from TEX and TTH. 
\def\tthdump#1{#1}
%%tth:\begin{html}<H1>The HTML Header</H1>\end{html}
\tthdump{\beginsection{The \TeX\ Header}\par}
How do I include the style file ...sty for the TEX paper I prepared for... journal?  
If you must, put it in the same directory as your .tex file and see if it works. If it crashes, you may have to write a simpler one. Remove the old style file. Look at your TEX file, or the TTH messages telling you which commands are unknown. Decide which of the journal's specific commands or environments you used or need. Write a little style file that defines them to do something simple and sensible, or translates them into standard LATEX commands. Or ask the journal to provide such a style file! If you are a journal publisher, distribute your simplified style file to your authors.
In bordered tables I want an empty cell to look empty. How do I make TTH do that?  
HTML tables by default "fill in" an empty cell, so that it gives the visual impression of being absent. This is sometimes useful, so TTH does not prevent it. If you want it to look like an empty cell, put a non-break space in it by &~& in the TEX.
How do I include into a macro I am defining a # sign for an HTML reference?  
When you do \special{html:<a href="#reference">} TTH just puts the html tag in the output verbatim. TEX does essentially the same for its dvi file and the dvi processor later may or may not complain about not understanding it; but generally it is ignored. However if you try to define a macro like \def\localhref{\special{html:<a href="#reference">}} then TEX will complain as follows: 
! Illegal parameter number in definition of \localref.
<to be read again> 
                   r
l.3 \def\localref{\special{html:<a href="#r
                                            eference">}}
?
This problem is caused by TEX's syntax analysis of the contents of the definition. One solution is to hide the definition from TEX using %%tth:. An alternative definition that avoids this problem must also be included for TEX's benefit, for example thus: 
\def\tthdump#1{#1}
\tthdump{\edef\localref{[a hyperreference]}}
%%tth:\def\localhref{\special{html:<a href="#reference">}}
Alternatively, use \# in place of # in the hypertex reference. TTH specifically recognizes this as a literal and does appropriate translation. For example 
\def\localhref#1#2{\special{html:<a href="\##1">}#2\special{html:</a>}}
will use its first parameter as a local anchor reference, preceded by #, and its second as the text of the anchor. The sequences \% and \\ are also treated as escaped literals, inserting their second character, inside a raw html section.
How do I construct a macro to take as a single argument a URL, which may contain special TEX characters like   _ ~ @ & etc, that makes TTH construct a hyperreference but TEX just enter it in the text?
Use the built-in command \url{...}. This behaves in essentially the same way as the command defined in LATEX's url.sty. The reference will appear verbatim in the text (in teletype font).

B.5  Formerly Frequently Asked Now Rarely Asked

Why does TTH only manage to input a limited number of files, perhaps 15 or so, then report "file not found" after that?  
This is a limitation of the operating system. It has only a limited number of file handles available. In MSDOS this number is set by a command FILES=... in the operating system configuration file config.sys. It needs to be set to a number large enough to accommodate all the input or include files that your TEX document uses, plus whatever other file overhead the operating system is using. Under OS/2 a similar limitation exists and is avoided by increasing the number of allowable file handles in the emx run-time system (e.g. SET EMXOPT=-c -h400 in config.sys).
TTH seems not to work on WinNT when converting included PostScript   files, even though my ps2gif program works fine from the command line. What is the problem?
The problem is not TTH. It appears to be an operating system problem. The batch program ps2gif is breaking for some strange reason when called from TTH. See footnote 5.
TTH does not recognize evironment ... even though it claims to.  
Probably you left a spurious space, e.g. \begin {enumerate} between the \begin and the following brace. TTH occasionally won't accept that, even though LATEX does. It is bad style.
HEAD NEXT