File: cutname.html

package info (click to toggle)
hevea-doc 2.36-1
links: PTS, VCS
area: non-free
in suites: bookworm, forky, sid, trixie
size: 1,764 kB
sloc: makefile: 9
file content (543 lines) | stat: -rw-r--r-- 36,155 bytes
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<meta name="generator" content="hevea 2.36">
<meta name="Author" content="Luc Maranget">
<script type="text/javascript" async src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-MML-AM_CHTML"></script><link rel="stylesheet" type="text/css" href="manual.css">
<title>Cutting your document into pieces with HACHA</title>
</head>
<body>
<a href="manual008.html"><img src="previous_motif.svg" alt="Previous"></a>
<a href="manual002.html"><img src="contents_motif.svg" alt="Up"></a>
<a href="manual018.html"><img src="next_motif.svg" alt="Next"></a>
<hr>
<h2 class="section" id="hacha">7&#X2003;Cutting your document into pieces with H<span class="c020"><sup>A</sup></span>C<span class="c020"><sup>H</sup></span>A</h2>
<ul>
<li><a href="cutname.html#sec42">Simple usage</a>
</li><li><a href="cutname.html#sec43">Advanced usage</a>
</li><li><a href="cutname.html#sec49">More Advanced Usage</a>
</li></ul>
<p>
H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A outputs a single <span class="c017">.html</span> file. This file can be
cut into pieces at various sectional units by H<span class="c020"><sup>A</sup></span>C<span class="c020"><sup>H</sup></span>A</p>
<h3 class="subsection" id="sec42">7.1&#X2003;Simple usage</h3>
<p>
First generate your html document by applying H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A:
</p><div class="flushleft">
<span class="c017"># hevea </span><em>doc</em><span class="c017">.tex</span>
</div><p>
Then cut <em>doc</em><span class="c017">.html</span> into pieces by the command:
</p><div class="flushleft">
<span class="c017"># hacha </span><em>doc</em><span class="c017">.html</span>
</div><p>
This will generate a simple root file
<span class="c017">index.html</span>.
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 &#X201C;cutting&#X201D; sectional unit.
By default, the cutting sectional unit is <em>section</em> in the
<em>article</em> style and <em>chapter</em> in the <em>book</em>
style.
The name of those files are <em>doc</em>001<span class="c017">.html</span>,
<em>doc</em>002<span class="c017">.html</span>, etc.</p><p>Additionally, one level of sectioning below the cutting unit
(<em>i.e.</em> subsections in the <em>article</em> style and sections in the
<em>book</em> style) is shown
as an entry in the table of contents.
Sectional units above the cutting section (<em>i.e.</em> parts in both
<em>article</em> and <em>book</em> styles) close the current table
of contents and open a new one.
Cross-references are properly handled, that is, the local links generated by
H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A are changed into remote links.</p><p>The name of the root file can be changed using the
<code class="verb">-o</code> option:
</p><div class="flushleft">
<span class="c017"># hacha -o root.html </span><em>doc</em><span class="c017">.html</span>
</div><p>Some of H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A output get replicated in all the files generated by
H<span class="c020"><sup>A</sup></span>C<span class="c020"><sup>H</sup></span>A.
<a id="html:footer"></a>Users can supply a header and a footer, which will appear at the
begining and end of every page generated by H<span class="c020"><sup>A</sup></span>C<span class="c020"><sup>H</sup></span>A. It suffices to
include the following commands in the document preamble:
</p><div class="flushleft">
&#X2003;<code class="verb">\htmlhead{</code><span class="c023">header</span><code class="verb">}</code><br>
&#X2003;<code class="verb">\htmlfoot{</code><span class="c023">footer</span><code class="verb">}</code>
</div><p>H<span class="c020"><sup>A</sup></span>C<span class="c020"><sup>H</sup></span>A also makes every page it generates a clone of its input as
regards attributes to the <code class="verb">&lt;body ...&gt;</code> opening tag and
meta-information from the <code class="verb">&lt;head&gt;</code>&#X2026; <code class="verb">&lt;\head&gt;</code>
block. See section&#XA0;<a href="manual024.html#metadef">B.2</a> for examples of this replication
feature.</p><p><a id="hacha:style"></a><a id="hevea_default30"></a>By contrast, style information specified in the <code class="verb">style</code> elements
from rom the <code class="verb">&lt;head&gt;</code>&#X2026; <code class="verb">&lt;\head&gt;</code>
block is not replicated. Instead, all style definitions are collected into an
external style sheet file whose name is <em>doc</em><span class="c017">.css</span>,
and all generated html files adopt <em>doc</em><span class="c017">.css</span> as
an external style sheet.
It is important to notice that, since version 1.08, H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A produces
a <code class="verb">style</code> element by itself, even if users do not explicitely
use styles. As a consequence,
H<span class="c020"><sup>A</sup></span>C<span class="c020"><sup>H</sup></span>A normally produces a
file <em>doc</em><span class="c017">.css</span>, which should not be forgotten while
copying files to their final destination after a run of&#XA0;H<span class="c020"><sup>A</sup></span>C<span class="c020"><sup>H</sup></span>A.</p>
<h3 class="subsection" id="sec43">7.2&#X2003;Advanced usage</h3>
<p>H<span class="c020"><sup>A</sup></span>C<span class="c020"><sup>H</sup></span>A behaviour can be altered from the document source, by using
a counter and a few macros.</p><p>A document that explicitly includes cutting macros still can be typeset by
L<sup>A</sup>T<sub>E</sub>X, provided it loads the
<span class="c017">hevea.sty</span> style file from the H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A distribution.
(See section&#XA0;<a href="manual007.html#both">5</a> for details on this style file).
An alternative to loading the <span class="c017">hevea</span> package is to put
all cutting instructions in comments starting with <code class="verb">%HEVEA</code>.</p>
<h4 class="subsubsection" id="sec44">7.2.1&#X2003;Principle</h4>
<p>
H<span class="c020"><sup>A</sup></span>C<span class="c020"><sup>H</sup></span>A recognizes all sectional units, ordered as follows, from
top to bottom: <em>part</em>, <em>chapter</em>,
<em>section</em>, <em>subsection</em>, <em>subsubsection</em>,
<em>paragraph</em> and <em>subparagraph</em>.</p><p>At any point between <code class="verb">\begin{document}</code> and
<code class="verb">\end{document}</code>,
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.</p><p>At document start, the root file and the output file are H<span class="c020"><sup>A</sup></span>C<span class="c020"><sup>H</sup></span>A
output file (<em>i.e.</em> <span class="c017">index.html</span>).
The cutting unit and the cutting depth are set to default values that
depend on the document style.</p>
<h4 class="subsubsection" id="sec45">7.2.2&#X2003;Cutting macros</h4>
<p>
The following cutting instructions are for use in the document
preamble. They command the cutting scheme of the whole document:
<a id="hevea_default31"></a><a id="hevea_default32"></a><a id="hevea_default33"></a><a id="hevea_default34"></a></p><dl class="description"><dt class="dt-description"><span class="c018">\cuttingunit</span></dt><dd class="dd-description">
This is a macro that holds the document cutting unit. You can change
the default (which is <em>section</em> in the <em>article</em> style
and <em>chapter</em> in the <em>book</em> style) by doing:
<div class="flushleft">
<code class="verb">\renewcommand{\cuttingunit}{</code><span class="c023">secname</span><code class="verb">}</code>.
</div>
</dd><dt class="dt-description"><span class="c018">\tocnumber</span></dt><dd class="dd-description"> Instruct H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A to put section numbers
into table of content entries.
</dd><dt class="dt-description"><span class="c018">\notocnumber</span></dt><dd class="dd-description"> Instruct H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A <em>not</em> to put
section numbers
into table of content entries. This is the default.
</dd><dt class="dt-description"><span class="c018">cuttingdepth</span></dt><dd class="dd-description">
This is a counter that holds the document cutting depth.
You can change the default value of 1 by doing
<code class="verb">\setcounter{cuttingdepth}{</code><span class="c023">numvalue</span><code class="verb">}</code>.
A cutting depth of zero means no other entries than the cutting units
in the table of contents.
</dd></dl><p>Other cutting instructions are to be used after
<code class="verb">\begin{document}</code>. They all generate html comments in H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A
output.
These comments then act as instructions to H<span class="c020"><sup>A</sup></span>C<span class="c020"><sup>H</sup></span>A.
<a id="hevea_default35"></a>
<a id="hevea_default36"></a>
<a id="hevea_default37"></a>
</p><dl class="description"><dt class="dt-description"><span class="c027"><span class="c017">\cuthere{</span><span class="c023">secname</span><span class="c017">}{</span><span class="c023">itemtitle</span><span class="c017">}</span></span></dt><dd class="dd-description">
Attempt a cut.
<ul class="itemize"><li class="li-itemize">If <span class="c023">secname</span> is the current cutting unit or
the keyword <span class="c017">now</span>, then
a new output file is started and an entry in the current table of contents
is generated, with title <span class="c023">itemtitle</span>. This entry holds a link
to the new output file.
</li><li class="li-itemize">If <span class="c023">secname</span> is above the cutting unit, then the
current table of contents is closed. The output file is set to the
current root file.
</li><li class="li-itemize">If <span class="c023">secname</span> 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 <em>itemtitle</em> and a link to the point where
<code class="verb">\cuthere</code> appears.
</li><li class="li-itemize">Otherwise, no action is performed.
</li></ul></dd><dt class="dt-description"><span class="c027"><span class="c017">\cutdef[</span><span class="c023">depth</span><span class="c017">]{</span><span class="c023">secname</span><span class="c017">}</span></span></dt><dd class="dd-description">
Open a new table of contents, with cutting depth&#XA0;<em>depth</em> and
cutting unit <em>secname</em>. If the optional <em>depth</em> is absent,
the cutting depth does not change.
The output file becomes the root file.
Result is unspecified if whatever <em>secname</em> expands to is
a sectional unit name above
the current cutting unit, is not a valid sectional unit name or if
<em>depth</em> does not expand to a small positive number.
</dd><dt class="dt-description"><span class="c018">\cutend</span></dt><dd class="dd-description">
End the current table of contents. This closes the scope of the
previous <code class="verb">\cutdef</code>. The cutting unit and cutting depth are
restored.
Note that <code class="verb">\cutdef</code> and <code class="verb">\cutend</code> must be properly balanced.
</dd></dl><p>
Commands <code class="verb">\cuthere</code> and <code class="verb">\cutend</code> have starred variants,
which behave identically except for footnotes (see&#XA0;<a href="#hachafoot">7.3.7</a>).</p><p>Default settings work as follows:
<code class="verb">\begin{document}</code> performs
</p><pre class="verbatim">\cutdef*[\value{cuttingdepth}]{\cuttingunit}
</pre><p>
and <code class="verb">\end{document}</code> performs <code class="verb">\cutend*</code>.
All sectioning commands perform <code class="verb">\cuthere</code>,
with the sectional unit name as first argument and the (optional, if
present) sectioning
command argument (<em>i.e.</em> the section title) as second argument.
Note that starred versions of the sectioning commands also perform
cutting instructions.</p>
<h4 class="subsubsection" id="table:link:style">7.2.3&#X2003;Table of links organisation</h4>
<p>
A table of links generated by H<span class="c020"><sup>A</sup></span>C<span class="c020"><sup>H</sup></span>A is a list
of links to generated files.
Additionally, some sublists may be present, up to a certain depth.
The items in those sublists are
links inside generated files, they point to sectional unit titles
below the cutting unit, up to a certain depth.</p><p>More precisely, let <span class="c023">A</span> be a certain sectional unit (<em>e.g.</em>
&#X201C;part&#X201D;), let <span class="c023">B</span> be just below <span class="c023">A</span>
(<em>e.g.</em> &#X201C;section&#X201D;),
and let <span class="c023">C</span> be just below <span class="c023">C</span> (<em>e.g.</em> &#X201C;subsection&#X201D;).
Further assume that cutting is performed at level&#XA0;<span class="c023">B</span> with a depth of
more than one.
Then, every unit&#XA0;<span class="c023">A</span> holds a one or several tables of links
to generated files, and each generated file normally holds a <span class="c023">B</span>&#XA0;unit.
Sublists with links to <span class="c023">C</span>&#XA0;units inside <span class="c023">B</span>&#XA0;units normally appear in the
tables of links of level&#XA0;<span class="c023">A</span>.
The command-line options <a id="hevea_default38"></a><span class="c017">-tocbis</span>
and&#XA0;<a id="hevea_default39"></a><span class="c017">-tocter</span> instruct <span class="c017">hacha</span>
to put sublists at other places.
With <span class="c017">-tocbis</span> sublists are duplicated at the beginning
of the <span class="c023">B</span>&#XA0;level files; while with <span class="c017">-tocter</span> sublist only
appear at the beginning
of the <span class="c023">B</span>&#XA0;level files.</p><p>In my opinion,
default style is appropriate for documents with short <span class="c023">B</span>&#XA0;units;
while <span class="c017">-tocbis</span> style
is appropriate for documents with long <span class="c023">B</span>&#XA0;units with
a few sub-units; and <span class="c017">-tocter</span> style is appropriate
for documents with long <span class="c023">B</span>&#XA0;units with
a lot of sub-units.
As you may have noticed, this manual is cut by following the
<span class="c017">-tocbis</span>&#XA0;style.</p><p>Whatever the style is, if a <span class="c023">B</span>&#XA0;unit is cut
(<em>e.g.</em> because its text is enclosed in
<code class="verb">\cutdef{</code><span class="c023">C</span><code class="verb">}</code>&#X2026; <code class="verb">\cutend</code>),
then every <span class="c023">C</span> unit goes into its own file and there is no sublist
after the relevant <span class="c023">B</span>&#XA0;level entry in the <span class="c023">A</span>&#XA0;level table of links.</p>
<h4 class="subsubsection" id="sec47">7.2.4&#X2003;Examples</h4>
<p>Consider, for instance, a <em>book</em> document with a long chapter
that you want to cut at the section level, showing subsections:
</p><pre class="verbatim">\chapter{A long chapter}
.....

\chapter{The next chapter}
</pre><p>
<a id="hevea_default40"></a><a id="hevea_default41"></a>
Then, you should insert a <code class="verb">\cutdef</code> at chapter start and a
<code class="verb">\cutend</code> at chapter end:
</p><pre class="verbatim">\chapter{A long chapter}
%HEVEA\cutdef[1]{section}
.....
%HEVEA\cutend
\chapter{The next chapter}
</pre><p>
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 command <code class="verb">\section</code> already
performs the appropriate <code class="verb">\cuthere{section}{...}</code> commands,
which were ignored by default.
(Also note that cutting macros are placed inside <code class="verb">%HEVEA</code> comments,
for L<sup>A</sup>T<sub>E</sub>X not to be disturbed).</p><p><a id="hevea_default42"></a>
<a id="hevea_default43"></a>
The <code class="verb">\cuthere</code> 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:
</p><pre class="verbatim">\documentclass{article}

\begin{document}

\begin{abstract} A big abstract \end{abstract}
...
</pre><p>
Then, you make the abstract go to its own file as it was a cutting
unit by typing:
</p><pre class="verbatim">\documentclass{article}
\usepackage{hevea}

\begin{document}
\cuthere{\cuttingunit}{Abstract}
\begin{abstract} A big abstract \end{abstract}
...
</pre><p>
(Note that, this time, cutting macros appear unprotected in the
source. However, L<sup>A</sup>T<sub>E</sub>X still can process the document, since the
<span class="c017">hevea</span> package is loaded).</p>
<h4 class="subsubsection" id="sec48">7.2.5&#X2003;More and More Pages in Output</h4>
<p>
<a id="hevea_default44"></a><a id="hevea_default45"></a>In some situations it may be appropriate to produce many
pages from one source files.
More specifically, loading the <span class="c017">deepcut</span> package will put
all sectioning units of your document (from <code class="verb">\part</code> to
<code class="verb">\subsection</code> in their own file.</p><p>Similarly, loading the <span class="c017">figcut</span> package will make all figures
and tables go into their own file.
The <span class="c017">figcut</span> package accepts two options, <span class="c017">show</span> and
<span class="c017">noshow</span>. The former, which is the default, instructs H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A
to repeat the caption into the main flow of text, with a link to the figure.
The latter option disables the feature.</p>
<h3 class="subsection" id="sec49">7.3&#X2003;More Advanced Usage</h3>
<p>
In this section we show how to alter some details of H<span class="c020"><sup>A</sup></span>C<span class="c020"><sup>H</sup></span>A
behaviour.
This includes controlling output file names and the title of generated
web pages and introducing arbitrary cuts.</p>
<h4 class="subsubsection" id="cutname">7.3.1&#X2003;Controlling output file names</h4>
<p><a id="hevea_default46"></a>When invoked as <span class="c017">hacha <em>doc</em>.html</span>,
H<span class="c020"><sup>A</sup></span>C<span class="c020"><sup>H</sup></span>A produces a <span class="c017">index.html</span> table of links file that
points into <em>doc</em><span class="c017">001.html</span>,
<em>doc</em><span class="c017">002.html</span>, etc. content files.
This is not very convenient when one wishes to point inside the
document from outside.
However, the <code class="verb">\cutname{</code><span class="c023">name</span><code class="verb">}</code> command
sets the name of the current output file name as <span class="c023">name</span>.</p><p>Consider a document cut at the section level, which contains the
following important section:
</p><pre class="verbatim">\section{Important\label{important} section}
...
</pre><p>
To make the important section goes into file <span class="c017">important.html</span>,
one writes:
</p><pre class="verbatim">\section{Important\label{important} section}\cutname{important.html}
...
</pre><p>
Then, section &#X201C;Important section&#X201D; can be referenced from
an H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A unaware html page by:
</p><pre class="verbatim">In this document, there is a very
&lt;a href="important.html#important"&gt;important section&lt;/a&gt;.
</pre><p>
If you are reading the html version of this manual, you may check
that you are now reading file <span class="c017">cutname.html</span>.
This particular file name has been specified from the source
using <code class="verb">\cutname{cutname.html}</code>.
</p>
<h4 class="subsubsection" id="sec51">7.3.2&#X2003;Controlling page titles</h4>
<p>
<a id="hevea_default47"></a>
When H<span class="c020"><sup>A</sup></span>C<span class="c020"><sup>H</sup></span>A 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
&#X201C;Cutting your document into pieces with H<span class="c020"><sup>A</sup></span>C<span class="c020"><sup>H</sup></span>A&#X201D;.
It is possible to insert some text at the beginning of all page
titles, by using the <code class="verb">\htmlprefix</code> command.
Hence, by writing
<code class="verb">\htmlprefix{\hevea{} Manual: }</code> in the document,
the title of this page would become:
&#X201C;H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A Manual: Cutting your document into pieces with H<span class="c020"><sup>A</sup></span>C<span class="c020"><sup>H</sup></span>A&#X201D;
and the title of all other pages would show the same prefix.</p>
<h4 class="subsubsection" id="sec52">7.3.3&#X2003;Links for the root file</h4>
<p>
<a id="hevea_default48"></a>
The command <code class="verb">\toplinks{</code><span class="c023">prev</span><code class="verb">}{</code><span class="c023">up</span><code class="verb">}{</code><span class="c023">next</span><code class="verb">}</code> instructs H<span class="c020"><sup>A</sup></span>C<span class="c020"><sup>H</sup></span>A to put links to a
&#X201C;previous&#X201D;, &#X201C;up&#X201D; and &#X201C;next&#X201D; page in the root file.
The following points are worth noticing:
</p><ul class="itemize"><li class="li-itemize">The <code class="verb">\toplink</code> command must appear in the document preamble
(<em>i.e.</em> before <code class="verb">\begin{document}</code>).
</li><li class="li-itemize">The arguments
<span class="c023">prev</span>, <span class="c023">up</span> and <span class="c023">next</span> should expand to urls,
notice that these argument are processed (see section&#XA0;<a href="manual018.html#urlareprocessed">8.1.1</a>).
</li><li class="li-itemize">When one of the expected argument is left empty,
the corresponding link is not generated.
</li></ul><p>
This feature can prove useful to
relate documents that are generated independently by
H<span class="c020"><sup>E</sup></span>V<span class="c020"><sup>E</sup></span>A and H<span class="c020"><sup>A</sup></span>C<span class="c020"><sup>H</sup></span>A.</p>
<h4 class="subsubsection" id="sec53">7.3.4&#X2003;Controlling link contents from the document</h4>
<p>
<a id="hevea_default49"></a>By default the links to the previous, up and next pages show a small
icon (an appropriate arrow). This can be changed with the command
<code class="verb">\setlinkstext{</code><span class="c023">prev</span><code class="verb">}{</code><span class="c023">up</span><code class="verb">}{</code><span class="c023">next</span><code class="verb">}</code>,
where <span class="c023">prev</span>, <span class="c023">up</span> and <span class="c023">next</span> are some L<sup>A</sup>T<sub>E</sub>X
source.
<a id="hevea_default50"></a>
For instance the default behaviour is equivalent to:
</p><pre class="verbatim">\setlinkstext
  {\imgsrc[alt="Previous"]{previous_motif.svg}}
  {\imgsrc[alt="Up"]{contents_motif.svg}}
  {\imgsrc[alt="Next"]{next_motif.svg}}
</pre><p>
Command <code class="verb">\setlinkstext</code> behaves as <code class="verb">\toplinks</code> does.
That is, it must occur in document preamble, arguments are processed
and empty arguments yield no effect (<em>i.e.</em> defaults apply).</p>
<h4 class="subsubsection" id="sec54">7.3.5&#X2003;Complete control over navigation links</h4>
<p>
<a id="hevea_default51"></a>The previous commands only impact the contents of the navigation links.
It is possible, although reserved to avanced users, to achieve greater control
by using the <code class="verb">\formatlinks</code> command. The <code class="verb">\formatlinks</code> command
takes four arguments which are command themselves. The last three command
format the &#X201C;previous&#X201D;, &#X201C;up&#X201D; and &#X201C;next&#X201D; links respectively,
while the first argument formats the resulting group of links.
For instance, one can avoid images and for arrows and typeset the full set of navivation links in a purple border
(see Section&#XA0;<a href="manual019.html#style%3Asheets">9</a> for styling techniques) as follows:
</p><pre class="verbatim">\newstyle{a.navarrow}{font-family:monospace;font-size:x-large;color:purple}
\newstyle{div.navarrows}{border:solid purple;display:inline-block;padding:1ex;}
\newcommand{\myprev}[1]{\ahref[class="navarrow" title="Previous" ]{#1}{$\rightarrow$}\quad}
\newcommand{\myup}[1]{\quad\ahref[class="navarrow" title="Up" ]{#1}{$\uparrow$}\quad}
\newcommand{\mynext}[1]{\quad\ahref[class="navarrow" title="Next" ]{#1}{$\writearrow$}}

\newcommand{\mylinks}[1]{\@open{div}{class="navarrows"}#1\@close{div}\end{center}}
\formatlinks{\mylinks}{\myprev}{\myup}{\mynext}
</pre>
<h4 class="subsubsection" id="sec55">7.3.6&#X2003;Cutting a document anywhere</h4>
<p>
<a id="hevea_default52"></a>
Part of a document goes to a separate file when enclosed in a
<code class="verb">cutflow</code> environment:
</p><div class="flushleft">
<code class="verb">\begin{cutflow}{</code><span class="c023">title</span><code class="verb">}</code>&#X2026;<code class="verb">\end{cutflow}</code>
</div><p>The content &#X201C;&#X2026;&#X201D; will go into a file of its
own, while
the argument <span class="c023">title</span> is used as the title of the introduced
html page.</p><p>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 <code class="verb">cutflow</code> environment.
This will occur naturally when the content of the <code class="verb">cutflow</code> environment.
contains a <code class="verb">\label</code> construct.
This look natural in the following quiz example:
</p><pre class="verbatim">\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}
</pre><p>
The example yields:
</p>
<h4 class="paragraph" id="sec56">A small quiz</h4>
<ol class="enumerate" type=1><li class="li-enumerate">What is black?
</li><li class="li-enumerate">What is white?
</li><li class="li-enumerate">What is Dylan?
</li></ol><p>
Answers in section&#XA0;<a href="manual010.html#answers">7.3.6</a>.
</p><p>
<a id="hevea_default53"></a><a id="hevea_default54"></a>
However,introducing html hyperlink targets and
references with the <code class="verb">\aname</code> and <code class="verb">\ahrefloc</code> commands
(see section&#XA0;<a href="manual018.html#hyperlink">8.1.1</a>)
will be more practical most of the time.</p><p><a id="hevea_default55"></a>The starred variant environment
<code class="verb">cutflow*</code> is the same
as <code class="verb">cutflow</code>, save for the html header and footer (see
Section&#XA0;<a href="#html%3Afooter">7.1</a>) which are not replicated in the introduced
page.</p>
<h4 class="subsubsection" id="hachafoot">7.3.7&#X2003;Footnotes</h4>
<p>
<a id="hevea_default56"></a><a id="hevea_default57"></a>Footnote texts (given as arguments either to <code class="verb">\footnote</code> or
<code class="verb">\footnotetext</code>) do not go directly to output.
Instead, footnote texts accumulate internally in a <em>buffer</em>,
awaiting to be flushed.
The flushing of notes is controlled by the means of a current
<em>flushing unit</em>, which is a sectional unit name or
<span class="c023">document</span> &#X2014; a fictional unit above all units.
At any point, the current flushing unit is the value of the
command&#XA0;<code class="verb">\@footnotelevel</code><a id="hevea_default58"></a>.
In practice, the flushing of footnote texts is performed by two commands:
</p><ul class="itemize"><li class="li-itemize"><code class="verb">\flushdef{</code><span class="c023">secname</span><code class="verb">}</code> simply sets
the flushing unit to <span class="c023">secname</span>.
</li><li class="li-itemize"><code class="verb">\footnoteflush{</code><span class="c023">secname</span><code class="verb">}</code> acts
as follows:
<ul class="itemize"><li class="li-itemize">If argument <span class="c023">secname</span> is equal to or above the
current flushing unit, then footnote texts are flushed (if any).
In the output, the texts themselves are surrounded by special comments
that tag them as footnote texts and record <span class="c023">secname</span>.
</li><li class="li-itemize">Otherwise, no action is performed.
</li></ul>
</li></ul><p>
The <em>article</em> style file performs <code class="verb">\flushdef{document}</code>,
while the <em>book</em> style file performs <code class="verb">\flushdef{chapter}</code>.
At the end of processing, <code class="verb">\end{document}</code> performs
<code class="verb">\footnoteflush{\@footnotelevel}</code>, so as to flush any pending notes.</p><p>Cutting commands interact with footnote flushing as follows:
</p><ul class="itemize"><li class="li-itemize"><code class="verb">\cuthere{</code><span class="c023">secname</span><code class="verb">}</code>
executes <code class="verb">\footnoteflush{</code><span class="c023">secname</span><code class="verb">}</code>.
Remember that all sectioning commands perform
<code class="verb">\cuthere</code> with their sectional unit name as argument.
</li><li class="li-itemize"><code class="verb">\cutdef{</code><span class="c023">secname</span><code class="verb">}</code>
saves the current flushing unit and buffer on some internal stack,
starts a new buffer for footnote texts, and
sets the current flushing unit to <span class="c023">secname</span>
(by performing <code class="verb">\flushdef{</code><span class="c023">secname</span><code class="verb">}</code>).
</li><li class="li-itemize"><code class="verb">\cutend</code> first flushes any pending texts
(by performing <code class="verb">\footnoteflush</code> with the current flushing unit
as argument), and restores the flushing unit and footnote text buffer saved
by the matching <code class="verb">\cutdef</code>.
</li><li class="li-itemize">The starred variants <code class="verb">\cutdef*</code> and&#XA0;<code class="verb">\cutend*</code> perform
no operation that is related to footnotes.
</li></ul><p>Later, when running across footnote texts in its input file, H<span class="c020"><sup>A</sup></span>C<span class="c020"><sup>H</sup></span>A
sometimes put notes in a separate file.
More precisely, H<span class="c020"><sup>A</sup></span>C<span class="c020"><sup>H</sup></span>A has knowledge of the
current <em>cutting level</em>, the current sectional unit where
cuts occur &#X2014; as given by the relevant <code class="verb">\cutdef</code>.
Moreover, H<span class="c020"><sup>A</sup></span>C<span class="c020"><sup>H</sup></span>A knows the current <em>section level</em> &#X2014;
that is, the last sectional command processed.
Besides, H<span class="c020"><sup>A</sup></span>C<span class="c020"><sup>H</sup></span>A extracts the <em>note level</em> from the comments
that surround the notes (as given by the command
<code class="verb">\footnoteflush</code> that produced the notes).
Then, H<span class="c020"><sup>A</sup></span>C<span class="c020"><sup>H</sup></span>A creates a separate file for notes
when the cutting level and the note level differ,
or when the current level is above the cutting level
(<em>e.g.</em> the current level is <span class="c017">document</span> while the cutting
level is <span class="c017">chapter</span>).
As a result, notes should stay where they are when they occur at the end of
H<span class="c020"><sup>A</sup></span>C<span class="c020"><sup>H</sup></span>A output file and otherwise go to a separate file.</p><p>To make a complicated story even more complicated,
footnotes in&#XA0;<span class="c017">minipage</span> environments or in the arguments
to <code class="verb">\title</code> or <code class="verb">\author</code> have a different, I guess satisfactory,
behaviour.</p><p>Given the above description, footnotes are managed by default as follows.
</p><ul class="itemize"><li class="li-itemize">In style&#XA0;<em>article</em>, <span class="c017">hevea</span> puts all footnotes
go at the end of the html file.
A later run of&#XA0;<span class="c017">hacha</span> creates a separate footnote file.
</li><li class="li-itemize">In style&#XA0;<em>book</em>, footnotes are collected at the end of
chapters. A later run of &#XA0;<span class="c017">hacha</span> leaves them where they
are. Footnotes in the title or author names are managed specially,
they will normally appear at the end of the root file.
</li></ul><p>
<a id="hevea_default59"></a>In case you wish to adopt a <em>book</em>-like behaviour for
an <em>article</em> (footnotes at the end of sections),
it suffices to insert <code class="verb">\flushdef{section}</code> in the document
preamble.</p><p>We now give a few example of interaction between notes and cutting.
We first consider normal behaviour.
The page you are reading is a section page, since the current
cutting unit is &#X201C;section&#X201D;. The current unit is &#X201C;subsection&#X201D;.
The following two subsubsections are sent to their own files by
the means of a <code class="verb">\cutdef{subsubsection}</code>/<code class="verb">\cutend</code> pair.
As a result the text of footnotes appear at the end of the
subsubsection pages.
</p><ul>
<li><a href="manual011.html">A cut subsubsection</a>
</li><li><a href="manual012.html">Another cut subsubsection</a>
</li></ul>
<p>The following two subsubsections are sent to their own files by
the means of a <code class="verb">\cutdef*{subsubsection}</code>/<code class="verb">\cutend*</code> pair.
As a result, the text of footnotes in the subsections appear
at the end of the current section page.<sup><a id="text5" href="#note5">4</a></sup>
</p><ul>
<li><a href="manual013.html">A cut subsubsection</a>
</li><li><a href="manual014.html">Another cut subsubsection</a>
</li></ul>
<p>Finally, to send the footnotes in subsubsections
to a separate web page, one should use
a&#XA0;<code class="verb">\cutdef{subsubsection}</code>/<code class="verb">\cutend</code> pair
(to create a proper buffer for subsubsection notes),
redefine the flushing unit, and flush notes explicitly.
</p><pre class="verbatim">\cutdef{subsubsection}\flushdef{document}%
\subsubsection{...}
  ...
\footnoteflush{document}\cutend
</pre><ul>
<li><a href="manual015.html">A cut subsubsection</a>
</li><li><a href="manual016.html">Another cut subsubsection</a>
</li></ul>

<hr class="ffootnoterule"><dl class="thefootnotes"><dt class="dt-thefootnotes"><a id="note5" href="#text5">4</a></dt><dd class="dd-thefootnotes"><div class="footnotetext">Standard section footnote.</div></dd><dt class="dt-thefootnotes"><a id="note6" href="manual013.html#text6">5</a></dt><dd class="dd-thefootnotes"><div class="footnotetext">Sent at
the end of <span class="c017">cutname.html</span></div></dd><dt class="dt-thefootnotes"><a id="note7" href="manual014.html#text7">6</a></dt><dd class="dd-thefootnotes"><div class="footnotetext">Sent at
the end of <span class="c017">cutname.html</span></div></dd></dl>
<hr>
<a href="manual008.html"><img src="previous_motif.svg" alt="Previous"></a>
<a href="manual002.html"><img src="contents_motif.svg" alt="Up"></a>
<a href="manual018.html"><img src="next_motif.svg" alt="Next"></a>
</body>
</html>