Previous Next Contents

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.
\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).


Previous Next Contents