7  Cross-references

The command \label{tag} anchors a location in the document that can be referred to elsewhere in the document with a \ref{tag}.⁶ 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.

7.1  Referring to external documents

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. E.g.,

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.

7.1.1  Abbreviations for specifying links

\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, i.e., 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}}.

7.2  Referring to labels in related documents

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.

7.2.1  \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, i.e., 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⁷, then docA.tex should contain

\includeexternallabels ../docB/docB 

and docB.tex should contain

\includeexternallabels ../docA/docA 

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

7.3  Table of contents

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.

7.4  Footnotes

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 (i.e., 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.⁸

The footnote above (below?) was generated by

... to get back to the body of the 
text.\numfootnote{Footnotes are separated ... 
by a horizontal rule.} 

7.5  Bibliographies

TeX2page can use the external program BibTeX [13, 18] 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. E.g.,

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, i.e., a sorted list of all the cited entries. E.g.,

\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-Z-B.aux. A subsequent run of TeX2page calls BibTeX on jobname-Z-B.aux to produce the corresponding sorted bibliography in the file jobname-Z-B.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-Z-B.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.⁹ Use the thebibliography environment to enclose your bibliographic entries, and introduce each entry with \bibitem. For more details, see the LaTeX manual [13, section 4.3.2, p. 71], or see a sample .bbl file generated by BibTeX and imitate.

7.6  Index generation

TeX2page can use the external program MakeIndex [2, 12] to generate indices. TeX2page’s index-generation feature follows the same conventions as traditionally used with TeX and its derived packages [13, 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-Z-I.idx. A subsequent run of TeX2page calls MakeIndex on jobname-Z-I.idx to produce the sorted index in jobname-Z-I.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-Z-I 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. E.g., you may want to have a different section header or include some introductory prose.

If TeX2page cannot find the sorted index file (jobname-Z-I.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.7  Colophon

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.¹⁰ \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.