htmltotex tutorial

htmltotex is a utility for converting html pages to TeX documents. This is a program written in Perl5. htmltotex accepts only local files written according to html2 specifications and outputs a TeX file which you should compile using your TeX compiler. You need the following programs/packages to run it.

Perl 5. You may get the latest version of Perl from http://www.perl.com/perl/CPAN/src/5.0/.
The library files: fonts.mac, misc.mac, spl-chars and htmltotex.rc.
The image converter program imgtops (if you like to put inline images in your TeX document)
The file epsf.sty for incorporating inline images in TeX files. This is provided in TeX or LaTeX distributions. See the ftp sites ftp://ftp.dante.de/tex-archive/macros/latex209/contrib/revtex/epsf.sty or ftp://ftp.tex.ac.uk/tex-archive/macros/latex209/contrib/revtex/epsf.sty.

htmltotex accepts all html 2 tags. In addition it is html 3.2 compatible. That is, it recognizes all html3.2 tags and when it encounters one such tag it either does as expected or copes up with it in a clever and suitable manner.

Command-line options

Usage: htmltotex [Options] input_file

Table: Command-line options for htmltops
option	meaning	default
`-a`	Show details (code, parameter names and values) of APPLET tags.	Ignore APPLET tags.
`-b BASEURL`	Set base URL to BASEURL. If not set, overwritten by the BASE tag in the header of the input file.	file:<input file>
`-c`	Retain html comments in input file as comments in output TeX file.	Remove all html comments.
`-d`	Convert images in black-and-white dithered mode.	Retain original colors.
`-f`	Show details (buttons, checkboxes, textareas, textfields etc.) of the form components.	Don't show the details.
`-F`	Tell TeX not to load computer modern fonts at smaller sizes. Use scaled versions of the 10pt fonts instead. For more details look at the troubleshooting file.	If the size of normal text is n points, tell TeX to load computer modern fonts at point sizes n, n-3 and n-5.
`-g`	Convert images in gray scale.	Retain original colors.
`-h`	Print help message
`-i`	Do not put in-line images, show alternate text (ALT) only.	Put images.
`-I`	Do not put in-line images, do not show alternate text (ALT).	Put images.
`-ip FILE`	Input user-defined TeX macro/preamble file FILE. Only one file can be included. You may, for example, change text dimensions, paragraph skips etc. in the preamble file. You are, however, requested not to change \parindent to a non-zero value.	No user-defined files are included. Plain TeX macros and some other pre-defined macros are used only. These macros are read and processed from the library files `fonts.mac` and `misc.mac`. You may not directly use these macro files in your TeX documents.
`-L LIBDIR`	Append `LIBDIR` to the default list of directories for searching the library files. `LIBDIR` should be a colon-separated list of directories.	The default search path is /usr/local/lib/htmltotex: /usr/local/htmltotex: ~/.htmltotex: .
`-lf LFTR`	Set left-footer to LFTR.	Null
`-lh LHDR`	Set left-header to LHDR.	Null
`-m IMGDIR`	Put postscript files for in-line images in IMGDIR.	Directory of the input file.
`-o OUTFILE`	Output TeX file to OUTFILE	`stdout`
`-p NUM`	Set starting page number to NUM.	1
`-P`	Suppress page numbering.	Show page numbers.
`-pt NUM`	Set size of default font to NUM points.	10
`-r NUM`	Set TeX running mode to NUM for the output file. Admissible values for NUM are: 0 - stop-for-errors mode 1 - batch mode 2 - scroll mode 3 - nonstop mode	0
`-rf RFTR`	Set right footer to RFTR	Null
`-rh RHDR`	Set right header to RHDR	`TEXT` if input contains `<TITLE>TEXT</TITLE>` in the header; null otherwise. If you do not want a header even when the input contains the TITLE tag, give the option `-rh ""`.
`-t TMPDIR`	Set temp directory for intermediate files to TMPDIR. Intermediate files are used for image conversion. You must have permission to write in this directory.	`/tmp`
`-u`	Underline anchors.	Don't underline.
`-v`	Set up verbose mode.	Non-verbose mode
`-V`	Print version info and quit.
`-w NUM`	Set cell width in tables to NUM centimeters. Each cell in the tables of the output file is set in a \vtop box of width NUM cms.	3

Examples:
htmltotex myfile.html # Use all defaults
htmltotex -o myfile.tex myfile.html # Output to myfile.tex
htmltotex myfile.html > myfile.tex # Same as the last example
htmltotex -t . myfile.html # Use . as temp directory
htmltotex -a -c -f myfile.html # Show applets and forms, retain comments
htmltotex -g myfile.html # Convert all in-line images to grey-scale
htmltotex -rh "My sweet home page" myfile.html # Set right header to "My sweet home page"
htmltotex -b "http://local.machine/~user/fun/index.html" myfile.html # Set base location
htmltotex -L /opt/htmltotex:~/lib myfile.html # Add directories /opt/htmltotex and ~/lib to the library search path
htmltotex -F -o myfile.tex myfile.html # Use this option if tex complains that it cannot find certain fonts when it tries to compile myfile.tex.

Tags supported

Anchors

<A> </A>

Blocks

<ADDRESS> </ADDRESS> <BLOCKQUOTE> </BLOCKQUOTE>
<BODY> </BODY> <HEAD> </HEAD> <HTML> </HTML> <TITLE> </TITLE>
<H1> ... <H6> </H1> ... </H6>
<BR> <HR> <P> </P> <CENTER> </CENTER> <DIV> </DIV>
<PRE> </PRE> <XMP> </XMP> <LISTING> </LISTING>
<SUB> </SUB> <SUP> </SUP>
<!-- ... >

Lists

<DL> </DL> <DT> <DD> <DIR> </DIR> <MENU> </MENU> <OL> </OL> <UL> </UL> <LI>

Tables

<TABLE> </TABLE> <TR> <TD> </TD> <TH> </TH>

Highlighting

<BLINK> </BLINK> <B> </B> <CITE> </CITE> <CODE> </CODE> <DFN> </DFN> <EM> </EM> <I> </I> <KBD> </KBD> <SAMP> </SAMP> <STRONG> </STRONG> <TT> </TT> <U> </U> <VAR> </VAR>

Font changes

<FONT SIZE=...> <FONT SIZE=+...> <FONT SIZE=-...> </FONT> <BIG> <SMALL>

Images

<IMG>

Forms

<FORM> </FORM> <INPUT> </INPUT> Input types: CHECKBOX, HIDDEN, IMAGE, RADIO, RESET, SUBMIT, TEXT. <OPTION> </OPTION> <SELECT> </SELECT> <TEXTAREA> </TEXTAREA>

Special characters

HTML control characters: < > " & ISO Latin characters: © Á À Â Ã Å Ä Æ Ç É È Ê Ë Í Ì Î Ï Ñ Ó Ò Ô Õ Ö Ø Ú Ù Û Ü Ý ß á à â ã å ä æ ç é è ê ë í ì î ï ñ ó ò ô õ ö ø ú ù û ü ý ÿ Numerical Character References: 
   ! " # $ % & ' ( ) * + , - . / 0 1 2 3 4 5 6 7 8 9 : ; < = > ? @ A B C D E F G H I J K L M N O P Q R S T U V W X Y Z [ \ ] ^ _ ` a b c d e f g h i j k l m n o p q r s t u v w x y z { | } ~ ¡ ¦ § ¨ © ª « ¬  ¯ ° ± ² ³ ´ µ ¶ · ¸ ¹ º » ¼ ½ ¾ ¿ À Á Â Ã Ä Å Æ Ç È É Ê Ë Ì Í Î Ï Ñ Ò Ó Ô Õ Ö × Ø Ù Ú Û Ü Ý ß à á â ã ä å æ ç è é ê ë ì í î ï ñ ò ó ô õ ö ÷ ø ù ú û ü ý ÿ Direct inclusion of characters:

¡ ¦ § ¨ © ª « ¬  ¯ ° ± ² ³ ´ µ ¶ · ¸ ¹ º » ¼
½ ¾ ¿ À Á Â Ã Ä Å Æ Ç È É Ê Ë Ì Í Î Ï Ñ Ò Ó Ô Õ Ö × Ø Ù Ú Û Ü Ý
ß à á â ã ä å æ ç è é ê ë ì í î ï ñ ò ó ô õ ö ÷ ø ù ú û ü ý ÿ

Applets

<APPLET> </APPLET> <PARAM>

HTML 3.2 tags

All HTML 3.2 tags are not supported. In fact, the last section describes which html3.2 tags are considered. For the sake of completeness, let us restate those HTML3.2 features that are taken care of by htmltotex. The closing tags are not listed. <H1 ALIGN=CENTER/LEFT/RIGHT> <OL START=number TYPE=1/a/A/i/I> <LI VALUE=number> <UL TYPE=DISC/SQUARE/CIRCLE> <LI TYPE=DISC/SQUARE/CIRCLE> <DIV ALIGN=CENTER/LEFT/RIGHT> <CENTER> <FONT SIZE=number> <FONT SIZE=+number> <FONT SIZE=-number> <BIG> <SMALL> <SUB> <SUP> <APPLET> <PARAM> © On the other hand, the following HTML features are not incorporated. (All of these are not part of HTML3.2 specifications, but supported by different browsers.) Again the closing tags are not listed. <STRIKE> <BASEFONT> <EMBED> <TAB> <LH> <FRAMESET> <FRAME> <SCRIPT> <FIG> <CAPTION> <CREDIT> <OVERLAY> ® text between <APPLET> and </APPLET>

What are ignored

Unknown tags (i.e. tags not listed in the section named Tags supported) are ignored. Examples: <FRAME>,<META> etc.
Any text between the <HEAD> and </HEAD> tags are ignored.
<TITLE> and <BASE> tags are processed only in the <HEAD> ... </HEAD> environment.
Non-local images are ignored.
Table arguments are ignored with one exception. The ALIGN arguments in the tags <TD> and <TH> are supported.
Nested highlighting commands do not have additive effects. The innermost highlighting command decides the font. For example, prints text in italics, not in bold italics.
Some higher ASCII characters are ignored, because there are no equivalent TeX symbols for them. These are ¢ £ ¤ ¥ ® Ð Þ ð and þ. Fonts supplied by AMS provide symbols for some of them. These are not incorporated. (You may not have the required AMS fonts.)

Assumptions

The input file is error-free according to HTML2 specifications. While attempts have been made to allow some types of errors in the input file, presence of other types of errors might result in errors (which may be fatal) during compilation of the output file. For example, if you miss a </B> tag corresponding to a <B> tag, TeX outputs a warning message
```
(\end occurred inside a group at level 1)
```
An html tag may span over more than one line. That is, tags like are supported. But unbalanced <'s might create troubles, whereas unbalanced >'s should not create problems.
A note on <: < is treated as a control character (namely a tag-starter) if and only if it is followed by an alphanumeric character, a slash (/) or a bang (!). In all other cases, it is treated as a literal <. This allows you to write the following code examples: or On the other hand, is NOT treated as a tag, whereas will treat <yourvar as the beginning of a tag. At any rate, when you mean by < a literal <, refer to it as <, whereas the use of < to mean a literal < as in the above examples is highly deprecated.
Certain special characters can be printed in html using the directive "&...;". I have noticed that many html page designers do not use the semicolon that completes the directive. They use a space instead. This is wrong in html culture and like bare <'s is highly deprecated. But many browsers pardon this offence. So also does htmltotex. This means that if you have to print an ampersand ("&"), you must use "&" (or "&amp ", if you want to exploit the merciful character of htmltotex).
HTML tags do not contain tags. This means that are not allowed. Normally, this should not pose any problem, beacause this tag is replaced by the action corresponding to TAG1, whereas TAG2 is ignored as a malformed argument to TAG1. However, comment tags might contain other tags (actually, almost anything under the sun).
Your TeX distribution provides at the minimum the following eight fonts: cmr10, cmbx10, cmti10, cmsl10, cmtt10, cmmi10, cmsy10, cmex10.

Troubleshooting

What should you do, if you have an error? Look at the file trouble.html that summarizes many possible errors and their remedies. If your error is not listed there, contact me.

Known bugs

Text between <A NAME="..."> and </A> is underlined (with the -u option).
The tags <XMP> and <LISTING> are treated interchangably in the sense that you can close the <XMP> environment by </LISTING> and vice versa.
Tags like <TITLE> and <BASE> are not processed unless they appear between <HEAD> and </HEAD>.
The tag <TR> to mark the first row of a table is absolutely mandatory.
You must end the environments <TITLE>, <SCRIPT>, <STYLE> and <CAPTION> by the corresponding end tags (</TITLE> etc). Otherwise whatever follows disappears.
Inclusion of paragraph-breaking materials between <A> and </A> (with the -u option) or between <U> and </U> creates problems. For example, consider This is perfectly acceptable in the html world, whereas in TeX every underlined text has to be in a single line.

Conclusion

Use htmltotex. With the exception of a few pathological cases, it should run okay for most of the files. For problems contact me at abhij@csa.iisc.ernet.in. Have fun !!

This page hosted by Get your own Free Home Page