7 Cutting your document into pieces with HACHA
HEVEA outputs a single .html file. This file can be
cut into pieces at various sectional units by HACHA
7.1 Simple usage
First generate your HTML document by applying HEVEA:
# hevea mydoc.tex
Then cut mydoc.html into pieces by the command:
# hacha mydoc.html
This will generate a simple root file
index.html.
This root file holds document title, abstract and a simple table of
contents.
Every item in the table of contents contains a link to or into a file
that holds a ``cutting'' sectional unit.
By default, the cutting sectional unit is section in the
article style and chapter in the book
style.
Additionally, one level of sectioning below the cutting unit (i.e.,
subsections in the article style and sections in the
book style) is shown
as an entry in the table of contents.
Sectional units above the cutting section (i.e., parts in both
article and book styles) close the current table
of contents and open a new one.
Cross-references are properly handled, that is the local links generated by
HEVEA are changed into remote links.
The name of the root file can be changed using the
-o
option:
# hacha -o root.html mydoc.html
Some of HEVEA output get replicated in all the files generated by
HACHA.
This includes the content of the <HEAD>
... <\HEAD>
block (except the <TITLE>
... <\TITLE>
block),
and the argument to the \@bodyargs
, \@htmlargs
,
\htmlhead
and \htmlfoot
commands (see
section B.2).
7.2 Advanced usage
HACHA behavior can be altered from the document source, by using
a counter and a few macros.
A document that explicitly includes cutting macros still can be typeset by
LATEX, provided it loads the
hevea package from the HEVEA distribution.
(See section 5 for details on the hevea package).
An alternative to loading the hevea package is to put
all cutting instructions in comments starting with %HEVEA
.
7.2.1 Principle
HACHA recognizes five sectional units, ordered as follows, from
top to bottom: part, chapter,
section, subsection and subsubection.
At any point between \begin{document}
and
\end{document}
,
there exist a current cutting sectional unit (cutting unit for short),
a current cutting depth, a root file and an output file.
Table of contents output goes to the root file, normal output goes to
the output file.
Cutting units start a new output file, whereas units comprised between the
cutting unit and the cutting units plus the cutting depth add new
entries in the table of contents.
At document start, the root file and the output file are HACHA
output file (i.e., index.html).
The cutting unit and the cutting depth are set to default values that
depend on the document style.
7.2.2 Cutting macros
The following cutting instructions are for use in the document
preamble. They command the cutting scheme of the whole document:
- \cuttingunit
-
This is a macro that holds the document cutting unit. You can change
the default (which is section in the article style
and chapter in the book style) by doing:
\renewcommand{\cuttingunit}{
secname}
.
- cuttingdepth
-
This is a counter that holds the document cutting depth.
You can change the default value of 1 by doing
\setcounter{cuttingdepth}{
numvalue}
.
A cutting depth of zero means no other entries than the cutting units
in the table of contents.
Other cutting instructions are to be used after
\begin{document}
. They all generate HTML comments in HEVEA
output.
These comments then act as instructions to HACHA.
- \cuthere{secname}{itemtitle}
-
Attempt a cut.
- If secname is the current cutting unit or
the keyword ``now'', then
a new output file is started and an entry in the current table of contents
is generated, with title itemtitle. This entry holds a link
to the new output file.
- If secname is above the cutting unit, then the
current table of contents is closed. The output file is set to the
current root file.
- If secname is below the cutting unit and less than the
cutting depth away from it, then an entry is added in the table of
contents.
This entry contains itemtitle and a link to the point where
\cuthere
appears.
- Otherwise, no action is performed.
- \cutdef[depth]{secname}
-
Open a new table of contents, with cutting depth depth and
cutting unit secname. If the optional depth is absent,
the cutting depth does not change.
The output file becomes the root file.
Result is unspecified if whatever secname expands to is
a sectional unit name above
the current cutting unit, is not a valid sectional unit name or if
depth does not expand to a small positive number.
- \cutend
-
End the current table of contents. This closes the scope of the
previous
\cutdef
. The cutting unit and cutting depth are
restored.
Note that \cutdef
and \cutend
must be properly balanced.
Default settings work as follows:
\begin{document}
performs
\cutdef[\value{cuttingdepth}]{\cuttingunit}
and \end{document}
performs \cutend
.
All sectioning commands down to \subsubsection
perform \cuthere
,
with the sectional unit name as first argument and the (optional, if
present) sectioning
command argument (i.e., the section title) as second argument.
Note that started versions of the sectioning commands also perform
cutting instructions.
7.2.3 Examples
Consider, for instance, a book document with a long chapter
that you want to cut at the section level, showing subsections:
\chapter{A long chapter}
.....
\chapter{The next chapter}
Then, you should insert a \cutdef
at chapter start and a
\cutend
at chapter end:
\chapter{A long chapter}
%HEVEA\cutdef[1]{section}
.....
%HEVEA\cutend
\chapter{The next chapter}
The macro section
already performs the appropriate
\cuthere{section}{...}
commands. As a consequence, the file
that would otherwise contain the long chapter now contains the chapter
title and a table of sections.
(Also note that cutting macros are placed inside %HEVEA
comments,
for LATEX not to be disturbed).
The \cuthere
macro can be used to put some document parts into
their own file.
This may prove appropriate for long cover pages or abstracts that would
otherwise go into the root file.
Consider the following document:
\documentclass{article}
\begin{document}
\begin{abstract} A big abstract \end{abstract}
...
Then, you make the abstract go to its own file as it was a cutting
unit by typing:
\documentclass{article}
\usepackage{hevea}
\begin{document}
\cuthere{\cuttingunit}{Abstract}
\begin{abstract} A big abstract \end{abstract}
...
(Note that, this time, cutting macros appear unprotected in the
source. However, LATEX still can process the document, since the
hevea package is loaded).