The command \label{tag} anchors a
location in the document that can be referred to
elsewhere in the document with a
\ref{tag}.7 The
location represented by a \label is the header of
the smallest sectioning environment enclosing the
\label. This sectioning environment can be a
chapter, (sub)section, or footnote.
A \label command is typically placed after the
sectioning command,
and the corresponding \ref will print as
that section's number. In HTML, the \ref text
will additionally be a link:
Clicking that
link will cause the browser to display the part of the web
page starting the labeled section.
Note that the \label merely names pre-selected
anchor points in the documents, viz, the openings of
chapters, (sub)sections, and footnotes. To insert your
own anchors at arbitrary locations in the document, use
\tag{ATAG}{TAGVALUE}. (You need to supply a
TAGVALUE, because there is no sectioning
environment whose number \tag can assume.)
This causes \ref{ATAG} to expand to TAGVALUE,
and furthermore, in the HTML, to be a hyperlink to the
location of the \tag. The main use for the \tag
command is to enrich the HTML version of your document
with hyperlinks -- unlike \label, \tag does
not add value to the print version.
You may need to rerun TeX2page in order to resolve the cross-references in a document. TeX2page will tell you if this is the case.
The command \urlhd{URL}{HTML text}{DVI text} lets you
link to arbitrary URLs, not just to labels within your
document. In the HTML output, a hyperlink to `URL' is
created, with the link text being `HTML text'. In the
DVI output, the part `DVI text' is output. Example:
For more details, consult
\urlhd{http://www.ithaka.org/odyssey.html}{the Odyssey}{the
{\it Odyssey\/} document in the Ithaka repository}.
In the DVI output, this becomes
For more details, consult the Odyssey document in the Ithaka repository.
In the HTML output, it would be
For more details, consult the Odyssey.
where
``the Odyssey'' is an HTML link to the site
http://www.ithaka.org/odyssey.html.
\urlhd is named to be a mnemonic for its
argument sequence, viz, the URL, followed by
the Html text, followed by the Dvi
text.
Note that you can use \urlhd for cross-referencing
within the document also. The URL in such cases will
be a label as specified by a \label or a
\tag command, but should add a `#' prefix. Eg,
See \urlhd{#hairy}{below}{section~\ref{hairy}}
for further details.
where the further details are described in a section
annotated with \label{hairy}. Assume this
section is numbered 21. Then, the reference typesets
as ``See section 21 ...'' in the DVI output and ``See
below ...'' in the HTML output (with below
being a link). In contrast, if we had written
See section~\ref{hairy} for further details.
we would have had ``See section 21 ...'' in both
DVI and HTML. \urlhd is thus more flexible
than \ref.
Because of page breaks in the HTML output (sec
3.1), it is possible that a label's definition
and the references to it do not ultimately sit on the
same physical HTML page. Nevertheless, your TeX
source can use #tag-style URLs to refer to anchors
anywhere within it. TeX2page will automatically
convert a #tag-style URL to its correct fully
qualified equivalent.
\urlhd takes three arguments. In some
cases the second and third arguments may be mere repetitions
of a preceding argument. For such cases, TeX2page
provides some convenient abbreviations.
\urlh takes two arguments. The first argument is the
URL, and the second is the descriptive text that is used in
both the HTML and the DVI outputs. For example:
TeX is available at
\urlh{http://www.tug.org}{the TUG website}.
produces
TeX is available at the TUG website.
In the HTML output, ``the TUG website'' is a hyperlink to
http://www.tug.org.
An optional \\ may be used inside \urlh's second argument. The
text before the \\ is used in both the HTML and the DVI
outputs. The text after the \\ is used only in
the DVI output. This helps you to specify extra information
for the DVI output, which may be necessary because the DVI
output lacks the information implicit in the hyperlink. For example:
TeX is available at
\urlh{http://www.tug.org}{TUG\\ (\path{tug.org})}.
produces, in the DVI output.
TeX is available at TUG (
tug.org).
The HTML output will not mention the parenthesized domain name, since the word ``TUG'' hyperlinks to it.
\\ is useful for internal cross-references too. For
example (assuming the label callcc refers to section 2.3):
More complicated forms of program control are possible
using \urlh{#callcc}{{\tt callcc}\\ (sec~\ref{callcc})}.
produces
More complicated forms of program control are possible using callcc (sec 2.3).
in the DVI output. In the HTML output, the parenthesized section reference will be dropped as redundant, as the word ``callcc'' hyperlinks to the relevant section.
An optional \1 may be used after \\ to refer to
\urlh's first argument, ie,
the URL.
Example:
TeX is available at
\urlh{http://www.tug.org}{TUG\\ (\1)}.
produces
TeX is available at TUG (
http://www.tug.org).
in the DVI output. In the HTML output, the parenthesized URL is dropped as redundant, as the word ``TUG'' hyperlinks to it.
Finally, the combination of \tag and
\urlh is useful for inserting
internal cross-references in the HTML document
without affecting the print document. For example,
the following text
\tag{ex1}{ignore}
\urlh{#ans1}{\bf Exercise 1.} Statement of a problem ...
\ldots\ lots of intervening stuff ...
\tag{ans1}{ignore}
\urlh{#ex1}{\bf Answer 1.} Answer to exercise 1 ...
prints as
Exercise 1. Statement of a problem ...
... lots of intervening stuff ...
Answer 1. Answer to exercise 1 ...
in both the DVI and the HTML. However, in the HTML, the proclamations ``Exercise 1.'' and ``Answer 1.'' are also helpful hyperlinks to each other.
\url takes just one argument, the URL. For the
descriptive text, both the HTML and the DVI outputs simply
use the URL itself. Example:
TeX is available at \url{http://www.tug.org}.
\urlp takes two arguments. In the HTML output,
the first argument is the link text and the second is
the URL. In the DVI output, the first argument is
typeset followed by a space followed by the URL in
parentheses. \urlp{text}{URL} abbreviates
\urlh{URL}{text\\ (\path{URL})}.
\mailto is a single-argument command for
specifying email addresses. \mailto{ADDRESS}
abbreviates \urlh{mailto:ADDRESS}{\path{ADDRESS}}.
The command \tableofcontents emits
a list of the section names in the
document, with their numbers. In HTML, these entries
are links to the corresponding sections.
Footnotes are a more print-oriented form of
cross-reference. TeX2page recognizes plain TeX's
\footnote as well as a new macro called
\numfootnote. The latter numbers footnotes
automatically and sequentially (ie, the user need not
think up footnote marks).
Both \footnote and \numfootnote produce the
expected output. The footnote mark occurs both
in the body of the text and at the bottom of the
relevant (DVI or HTML) page, with the latter
accompanied by the footnote text.
Additionally, in the HTML output, the footnote mark in the text body is a link to the footnote mark in the footnote text, and vice versa. This paragraph ends with a footnote. Click the footnote mark to see the footnote text at the bottom of the HTML page. You can either click the ``back'' button on your browser or the footnote mark itself to get back to the body of the text.8
The footnote above (below?) was generated by
... to get back to the body of the
text.\numfootnote{Footnotes are separated ...
by a horizontal rule.}
TeX2page can use the external program BibTeX [9, 15] to generate bibliographies from bibliographic database files. A bibliographic database file is a .bib file containing bibliographic entries of the form
@book(tex,
author = "D E Knuth",
title = "{The TeXbook}",
publisher = "Addison-Wesley",
year = 1993
)
TeX source can cite a bibliographic entry using
the command \cite. Eg,
Here's an example diagram from {\it The
TeXbook\/}~\cite[p~389]{tex}.
The command \bibliographstyle specifies the
style of the citations: plain numbers the
bibliography items, whereas alpha gives them
mnemonic alphanumeric keys. The command
\bibliography specifies one or more .bib files
to search for the citations, and generates a bibliography, ie, a sorted list of all the cited
entries. Eg,
...
\section*{Bibliography}
\bibliographystyle{plain}
\bibliography{tex,scheme,html}
Here tex.bib, scheme.bib, and html.bib are the .bib files used, presumably containing entries specific to TeX, Scheme, and HTML respectively.
\nocite{citation} will include in the
bibliography the entry for citation,
without needing to cite it in the text.
\nocite{*} will include all the entries
from all the supplied .bib files.
A first run of TeX2page on creates an auxiliary file jobname--h.aux. A subsequent run of TeX2page calls BibTeX on jobname--h.aux to produce the corresponding sorted bibliography in the file jobname--h.bbl, which is slurped into the output document. (You may call BibTeX yourself, as you would have to do when TeXing the document for the DVI output.)
If TeX2page cannot create or find jobname--h.bbl despite its best efforts, it will inform you that you need to generate it manually. Once created, the file is reused as is in future runs. Delete the file to have it regenerated (perhaps because your document has changed).
BibTeX is convenient for selecting, sorting, and
writing out in appropriate format the relevant
bibliographic entries for your document, but if for
some reason you want to do it all on your own, you
can.9 Use the
thebibliography environment to enclose your
bibliographic entries, and introduce each entry with
\bibitem. For more details, see the LaTeX manual
[9, sec 4.3.2, p 71], or see a sample
.bbl file generated by BibTeX and imitate.
TeX2page can use the external program MakeIndex [2] to generate indices. TeX2page's index-generation feature follows the same conventions as traditionally used with TeX and its derived packages [9, sec 4.5, appx A].
This means that an occurrence of
\index{item} in the TeX source causes
item to be entered into an unsorted index
file, jobname--h.idx. A subsequent
run of TeX2page calls MakeIndex on
jobname--h.idx to produce the sorted index
in jobname--h.ind, which is included in the
output using a command such as \printindex. (You
may call MakeIndex yourself, as you would have to do when
TeXing the document for the DVI output.)
The auxiliary files have the basename jobname--h rather than jobname as in TeX, because the HTML index is necessarily different in character from the DVI index: Whereas the DVI index item mentions one or more page numbers in the main text where the indexed item occurs, the HTML index item is a hyperlink into the main text.
If an indexed item needs to point to multiple occurrences in the main text, the hyperlink associated with the index entry points to the first occurrence. The hyperlinks for succeeding occurrences are notated by bracketed numbers starting from 2. (The number represents the number of the occurrence.)
TeX2page recognizes two macros for index
insertion. First, there is the more conventional
\printindex which emits the sorted index
inside a section called ``Index''. In addition,
there is also \inputindex, which emits just
the index without a section header. This is so
that you can set the index your own way. Eg,
you may want to have a different section header
or include some introductory prose.
If TeX2page cannot find the sorted index file (jobname--h.ind) despite its best efforts, it will inform you that you need to generate it manually. Once created, the file is reused as is in future runs. Delete the file to have it regenerated (perhaps because your document has changed).
7 If you are using the
Eplain [1] format, use the name
\tagref instead of \ref to get the behavior
described here. Or do \let\ref\tagref after
\inputting tex2page.tex. Eplain uses the name
\ref for a somewhat different operation, and
tex2page.tex will not by itself overwrite it.
8 Footnotes are separated from the body of the page by a horizontal rule.
9 This approach, while tedious and a maintenance millstone, can be rational sometimes: Eg, if your bibliographic entries are written in a raconteur's style and include opinions or digressions that are tailormade for the particular document at hand, they are likely inappropriate for inclusion in a quasi-central bibliographic database.