![]() | ![]() | ![]() | Controlling Hyperlatex | Contents | Index |
Practically everything about Hyperlatex can be modified and adapted to your taste. In many cases, it suffices to redefine some of the macros defined in the siteinit.hlx package.
When Hyperlatex processes the \documentclass{class}
command, it
tries to read the Hyperlatex package files siteinit.hlx,
init.hlx, and class.hlx in this order. These package
files implement most of Hyperlatex's functionality using LaTeX-style
macros. Hyperlatex looks for these files in the directory
.hyperlatex in the user's home directory, and in the
system-wide Hyperlatex directory selected by the system administrator
(or whoever installed Hyperlatex). siteinit.hlx contains the
standard definitions for the system-wide installation of Hyperlatex,
the package class.hlx (where class is one of
article, report, book etc) define the commands
that are different between different LaTeX classes.
System administrators can modify the default behavior of Hyperlatex by modifying siteinit.hlx. Users can modify their personal version of Hyperlatex by creating a file ~/.hyperlatex/init.hlx with definitions that override the ones in siteinit.hlx. Finally, all these definitions can be overridden by redefining macros in the preamble of a document to be converted.
To change the default depth at which a document is split into nodes,
the system administrator could change the setting of htmldepth
in siteinit.hlx. A user could define this command in her
personal init.hlx file. Finally, we can simply use this command
directly in the preamble.
Normally, the HTML output for your document document.tex are
created in files document_?.html in the same directory. You can
change both the name of these files as well as the directory using the
two commands \htmlname
and \htmldirectory
in the
preamble of your source file:
\htmldirectory{directory} \htmlname{basename}
The actual files created by Hyperlatex are called
and so on. The filename can be changed for individual nodes using the
\xname
command.
Hyperlatex automatically
partitions the document into several nodes. This is done
based on the LaTeX sectioning. The section commands
\chapter
, \section
,
\subsection
, \subsubsection
,
\paragraph
, and \subparagraph
are assigned
levels 0 to 5.
The counter htmldepth
determines at what depth separate nodes
are created. The default setting is 4, which means that sections,
subsections, and subsubsections are given their own nodes, while
paragraphs and subparagraphs are put into the node of their parent
subsection. You can change this by putting
\setcounter{htmldepth}{depth}
in the preamble. A value of 0 means that the full document will be stored in a single file.
The individual nodes of an HTML document are linked together using hyperlinks. Hyperlatex automatically places buttons on every node that link it to the previous and next node of the same depth, if they exist, and a button to go to the parent node.
Furthermore, Hyperlatex automatically adds a menu to every node, containing pointers to all subsections of this section. (Here, "section" is used as the generic term for chapters, sections, subsections, ....) This may not always be what you want. You might want to add nicer menus, with a short description of the subsections. In that case you can turn off the automatic menus by putting
\setcounter{htmlautomenu}{0}
in the preamble. On the other hand, you might also want to have more detailed menus, containing not only pointers to the direct subsections, but also to all subsubsections and so on. This can be achieved by using
\setcounter{htmlautomenu}{depth}
where depth is the desired depth of recursion. The default behavior corresponds to a depth of 1.
Normally, Hyperlatex adds a "navigation panel" at the beginning of every HTML node. This panel has links to the next and previous node on the same level, as well as to the parent node.
The easiest way to customize the navigation panel is to turn it off
for selected nodes. This is done using the commands \htmlpanel{0}
and \htmlpanel{1}
. All nodes started while \htmlpanel
is set
to 0 are created without a navigation panel.
If you wish to add additional fields (such as an index or table of
contents entry) to the navigation panel, you can use
\htmlpanelfield
in the preamble. It takes two arguments, the text
to show in the field, and a label in the document where clicking the
link should take you. For instance, the navigation panels for this
manual were created by adding the following two lines in the preamble:
\htmlpanelfield{Contents}{hlxcontents} \htmlpanelfield{Index}{hlxindex}
Furthermore, the navigation panels (and in fact the complete outline
of the created HTML files) can be customized to your own taste by
redefining some Hyperlatex macros. When it formats an HTML node,
Hyperlatex inserts the macro \toppanel
at the beginning, and the
two macros \bottommatter
and bottompanel
at the end. When
\htmlpanel{0}
has been set, then only \bottommatter
is inserted.
The macros \toppanel
and \bottompanel
are responsible for
typesetting the navigation panels at the top and the bottom of every
node. You can change the appearance of these panels by redefining
those macros. See bluepanels.hlx for their default definition.
You can use \htmltopname
to change the name of the top node.
If you have included language packages from the babel package, you can
change the language of the navigation panel using, for instance,
\htmlpanelgerman
.
The following commands are useful for defining these macros:
\HlxPrevUrl
, \HlxUpUrl
, and \HlxNextUrl
return the URL
of the next node in the backwards, upwards, and forwards direction.
(If there is no node in that direction, the macro evaluates to the
empty string.)
\HlxPrevTitle
, \HlxUpTitle
, and \HlxNextTitle
return
the title of these nodes.
\HlxBackUrl
and \HlxForwUrl
return the URL of the previous
and following node (without looking at their depth)
\HlxBackTitle
and \HlxForwTitle
return the title of these
nodes.
\HlxThisTitle
and \HlxThisUrl
return title and URL of the
current node.
\EmptyP{expr}{A}{B}
evaluates to A
if expr
is not the empty string, to B
otherwise.
The appearance of footnotes in the HTML output can be customized by redefining several macros:
The macro \htmlfootnotemark{n}
typesets the mark that
is placed in the text as a hyperlink to the footnote text. See the
file siteinit.hlx for the default definition.
The environment thefootnotes
generates the HTML node with the
footnote text. Every footnote is formatted with the macro
\htmlfootnoteitem{n}{text}
. The default
definitions are
\newenvironment{thefootnotes}% {\chapter{Footnotes} \begin{description}}% {\end{description}} \newcommand{\htmlfootnoteitem}[2]% {\label{footnote-#1}\item[(#1)]#2}
If you are familiar with HTML, then you will sometimes want to be
able to add certain HTML attributes to the HTML tags generated by
Hyperlatex. This is possible using the command \xmlattributes
. Its
first argument is the name of an HTML tag (in lower case!), the second
argument can be used to specify attributes for that tag. The
declaration can be used in the preamble as well as in the document. A
new declaration for the same tag cancels any previous declaration,
unless you use the starred version of the command: It has effect only on
the next occurrence of the named tag, after which Hyperlatex reverts
to the previous state.
All the HTML-tags created using the \xml
-command can be
influenced by this declaration. There are, however, also some
HTML-tags that are created directly in the Hyperlatex kernel and that
do not look up any attributes here. You can only try and see (and
complain to me if you need to set attribute for a certain tag where
Hyperlatex doesn't allow it).
Some common applications:
HTML 3.2 allows you to specify the background color of an HTML node using an attribute that you can set as follows. (If you do this in init.hlx or the preamble of your file, all nodes of your document will be colored this way.) Note that this usage is deprecated, you should be using a style sheet instead.
\xmlattributes{body}{bgcolor="#ffffe6"}
The following declaration makes the tables in your document have borders.
\xmlattributes{table}{border="1"}
A more compact representation of the list environments can be enforced
using (this is for the itemize
environment):
\xmlattributes{ul}{compact}
The following attributes make section and subsection headings be centered.
\xmlattributes{h1}{align="center"} \xmlattributes{h2}{align="center"}
Sometimes it is useful to turn off the special meaning of some of the
ten special characters of LaTeX. For instance, when writing
documentation about programs in C, it might be useful to be able to
write some_variable
instead of always having to type
some\_variable
, especially if you never use any formula and
hence do not need the subscript function. This can be achieved with
the \NotSpecial
command.
The characters that you can make non-special are
~ ^ _ # $ &
For instance, to make characters $ and ^ non-special, you need to use the command
\NotSpecial{\do\$\do\^}
Yes, this syntax is weird, but it makes the implementation much easier.
Note that whereever you put this declaration in the preamble, it will
only be turned on by \
begin{document}
. This means that you can
still use the regular LaTeX special characters in the
preamble.
Even within the iftex
environment the characters
you specified will remain non-special. Sometimes you will want to
return them their full power. This can be done in a tex
environment. It is equivalent to iftex
, but also turns on all
ten special LaTeX characters.
An HTML-file can carry a number of tags in the HTML-header, which is created automatically by Hyperlatex. There are two commands to create such header tags:
\htmlcss
creates a link to a cascaded style sheet. The single
argument is the URL of the style sheet. The tag will be added to
every node created after the command has been processed. Use an
empty argument to turn of the CSS link.
\htmlcharset
tags the HTML-file as being encoded in a particular
character set. Use an empty argument to turn off creation of the tag.
Here is an example:
\htmlcss{http://www.w3.org/StyleSheets/Core/Modernist} \htmlcharset{EUC-KR}
![]() | ![]() | ![]() | Controlling Hyperlatex | Contents | Index |