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}\\ (section~\ref{callcc})}.
produces
More complicated forms of program control are possible using callcc (section 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 ... ... 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}}
.
TeX2page allows several related online documents
to refer to labels in one another, much as each would
refer to labels within itself. Each document needs to
identify the location of the other documents that it
wishes to refer to. The commands
\includeexternallabels
and \inputexternallabels
accomplish two flavors of such mutual
cross-referencing.
\includeexternallabels
\includeexternallabels external-jobname
allows the current document to incorporate
labels from external-jobname
, and refer
to them as it would to its own labels, ie, using
\ref
. It is therefore
important that the label names used by the documents
should not clash.
The argument external-jobname
is the
appropriate pathname to the external document.
Use the name of the main HTML file, without the
extension.
If using a relative pathname, take care to
calculate the pathname from the location of the current
document's main HTML (not source) file to the location
of the external document's main HTML (again, not
source) file.
For example, if you have two documents docA.tex
and docB.tex
in the current directory, and you
have used the .hdir
mechanism to direct the HTML
files to go into subdirectories docA
and
docB
8, then docA.tex
should
contain
\includeexternallabels ../docB/docB
and docB.tex
should contain
\includeexternallabels ../docA/docA
\inputexternallabels
\inputexternallabels external-jobname
also allows the current document to refer to labels
from external-jobname
. However, unlike
\includeexternallabels
, the labels are not
incorporated into the current documents pool of labels.
The call merely identifies that the labels from
external-jobname
are available for use in
the current document, but with appropriate
qualification. Instead of \ref
, the command
\htmlrefexternal
is used to refer these labels.
The call
\htmlrefexternal{text}{external-jobname}{external-label}
typesets text
as a hyperlink to the label
external-label
in the HTML document of
basename external-jobname
.
Note that the external document is named explicitly.
While the situation is more verbose than that with
\includeexternallabels
, it makes no requirement
that the names of the labels in the two documents
should not clash.
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.9
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
[25, 32] 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}.
\cite
and the other bibliography-related
commands described below are included in LaTeX. For
plain TeX, you will need to explicitly load the
macro file btxmac.tex
, present in all TeX
distributions.
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 the document
jobname.ext
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.10 Use the
thebibliography
environment to enclose your
bibliographic entries, and introduce each entry with
\bibitem
. For more details, see the LaTeX manual
[25, section 4.3.2, p 71], or see a sample
.bbl
file generated by BibTeX and imitate.
TeX2page can use the external program MakeIndex [2, 24] to generate indices. TeX2page's index-generation feature follows the same conventions as traditionally used with TeX and its derived packages [25, section 4.5, appendix 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 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).
By default, TeX2page prints a two-line colophon at the
bottom of the first page, the first line giving
the time of last change of the source document, and the
second line identifying TeX2page. You can control both
the placement and the detail of the colophon using
the \htmlcolophon
command.
\htmlcolophon{last-page}
puts the colophon on
the last, instead of the first, page.
\htmlcolophon{no-timestamp}
prevents
mention of the last modification time of the
document.11
\htmlcolophon{dont-link-to-tex2page-website}
will
mention TeX2page, but without hyperlinking
to the TeX2page website. To avoid mentioning
TeX2page at all, use
\htmlcolophon{dont-credit-tex2page}
, which also has
the convenient shorter form
\htmlcolophon{ingrate}
.
These arguments to \htmlcolophon
can be grouped
together, with whitespace separating them. Thus,
\htmlcolophon{last-page dont-credit-tex2page}
produces on the last page a colophon containing
only the timestamp.
To produce no colophon at all, do
\htmlcolophon{no-timestamp dont-credit-tex2page}
.
A call to \htmlcolophon
requesting
last-page
is best placed in the document before
text for the second page starts, so as to avoid the
default of the colophon appearing at the end of the
first page.
7
If you are using the
Eplain format, use the name
\tagref
instead of \ref
to get the behavior
described here. Or do \let\ref\tagref
after
\input
ting tex2page.tex
. Eplain uses the name
\ref
for a somewhat different operation, and
tex2page.tex
will not by itself overwrite it.
8 This could be done, for instance,
by having both docA.hdir
and docB.hdir
contain \jobname
.
9 Footnotes are separated from the body of the page by a horizontal rule.
10 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.
11 If the underlying Scheme is incapable
of determining a file's write date, no-timestamp
is automatically assumed.