Google

"http://www.w3.org/TR/REC-html40/loose.dtd"> Cutting your document into pieces with HACHA Previous Up Next
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. 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.

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

7.2.1 Principle
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.

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

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

7.3 More Advanced Usage
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
  1. What is black?
  2. What is white?
  3. 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.

Previous Up Next