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
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.
Users can supply a header and a footer, which will appear at the
begining and end of every page generated by HACHA. It suffices to
include the following commands in the document preamble:
\htmlhead{
header}
\htmlfoot{
footer}
HACHAalso makes every page it generates a clone of its input as
regards attributes to the <BODY ...>
opening tag and
meta-information from the <HEAD>
... <\HEAD>
block. See section B.2 for examples of this replication
feature.
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.sty style file from the HEVEA distribution.
(See section 5 for details on this style file).
An alternative to loading the hevea package is to put
all cutting instructions in comments starting with %HEVEA
.
HACHA recognizes all sectional units, ordered as follows, from
top to bottom: part, chapter,
section, subsection, subsubection,
paragraph and subparagraph.
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.
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}
.
- \tocnumber
- Instruct HEVEA to put section numbers
into table of content entries.
- \notocnumber
- Instruct HEVEA not to put
section numbers
into table of content entries. This is the default.
- 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 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.
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}
Then, the file
that would otherwise contain the long chapter now contains the chapter
title and a table of sections.
No other change is needed, since the macro section
already
performs the appropriate \cuthere{section}{...}
commands,
which were ignored by default.
(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).
In this section we show how to alter some details of HACHA
behavior.
This includes controling output file names and the title of generated
web pages and introducing arbitrary cuts.
7.3.1 |
Controlling output file names |
|
When invoked as hacha doc.html,
HACHA produces a index.html table of links file that
points into doc001.html,
doc002.html, etc. content files.
This is not very convenient when one wishes to point inside the
document from outside.
However, the \cutname{
name}
command
sets the name of the current output file name as name.
Consider a document cut at the section level, which contains the
following important section :
\section{Important section}\label{important}
...
To make the important section goes into file important.html,
one writes :
\section{Important section}\label{important}\cutname{important.html}
...
Then, section ``Important section'' can be referenced from
an HEVEA unaware HTML page by :
In this document, there is a very
<A HREF="important#important.html">important section</A>.
If you are reading the HTML version of this manual, you may check
that wou are now reading file ``cutname.html''.
This particular file name has been specified from the source
using \cutname{cutname.html}
.
7.3.2 |
Controlling page titles |
|
When HACHA creates a web page from a given sectional unit,
the title of this page normally is the name of the sectional unit.
For instance, the title of this very page should be
``Cutting your document into pieces with HACHA''.
It is possible to insert some text at the beginning of all page
titles, by using the \htmlprefix
command.
Hence, by writing
\htmlprefix{\hevea{} Manual: }
in the document,
the title of this page would become :
``HEVEA Manual: Cutting your document into pieces with HACHA''
and the title of all other pages would show the same prefix.
7.3.3 |
Links for the root file |
|
The command \toplinks{
prev}{
up}{
next}
instructs HACHA to put links to a
``previous'', ``up'' and ``next'' page in the root file.
The following points are worth noticing:
-
The
\toplink
command must appear in the document preamble
(i.e., before \begin{document}
).
- The arguments
prev, up and next should expand to url's,
notice that these argument are processed (see section 8.1.1).
- When one of the expected argument is left empty,
the corresponding link is not generated.
This feature can prove useful to
relate documents that are generated independantly by
HEVEA and HACHA.
7.3.4 |
Cutting a document anywhere |
|
Part of a document goes to a separate file whem enclosed in a
cutflow
environment :
\begin{cutflow}{
title}
...\end{cutflow}
The content ``...'' will go into a file of its
own, while
the argument title is used as the title of the introduced
HTML page.
The HTML page introduced here does not belong to the normal flow of
text.
Consequently, one needs an explicit reference from the normal flow of text
into the content of the cutflow
environment.
This will occur naturally when the content of the cutflow
environment.
contains a \label
construct.
This look natural in the following quiz example:
\paragraph{A small quiz}
\begin{enumerate}
\item What is black?
\item What is white?
\item What is Dylan?
\end{enumerate}
Answers in section~\ref{answers}.
\begin{cutflow}{Answers}
\paragraph{Quiz answers}\label{answers}
\begin{enumerate}
\item Black is black.
\item White is white.
\item Dylan is Dylan.
\end{enumerate}
\end{cutflow}
The example yields:
A small quiz
-
What is black?
- What is white?
- What is Dylan?
Answers in section 7.3.4.
However,introducing HTML hyperlink targets and
references with the \aname
and \ahrefloc
commands
(see section 8.1.1)
will be more practical most of the time.