![]() | ![]() | ![]() | Moving information around | Contents | Index |
In this section we deal with questions related to cross referencing between parts of your document, and between your document and the outside world. This is where Hyperlatex gives you the power to write natural HTML documents, unlike those produced by any LaTeX converter. A converter can turn a reference into a hyperlink, but it will have to keep the text more or less the same. If we wrote "More details can be found in the classical analysis by Harakiri [8]", then a converter may turn "[8]" into a hyperlink to the bibliography in the HTML document. In handwritten HTML, however, we would probably leave out the "[8]" altogether, and make the name "Harakiri" a hyperlink.
The same holds for references to sections and pages. The Ipe manual says "This parameter can be set in the configuration panel (Section 11.1)". A converted document would have the "11.1" as a hyperlink. Much nicer HTML is to write "This parameter can be set in the configuration panel", with "configuration panel" a hyperlink to the section that describes it. If the printed copy reads "We will study this more closely on page 42," then a converter must turn the "42" into a symbol that is a hyperlink to the text that appears on page 42. What we would really like to write is "We will later study this more closely," with "later" a hyperlink--after all, it makes no sense to even allude to page numbers in an HTML document.
The Ipe manual also says "Such a file is at the same time a legal Encapsulated Postscript file and a legal LaTeX file--see Section 13." In the HTML copy the "Such a file" is a hyperlink to Section 13, and there's no need for the "--see Section 13" anymore.
You can use the \label{}
command to attach a
label to a position in your document. This label can be used to
create a hyperlink to this position from any other point in the
document.
This is done using the \link
command:
\link{
anchor}{label}
This command typesets anchor, expanding any commands in there, and makes it an active hyperlink to the position marked with label:
This parameter can be set in the \link{configuration panel}{sect:con-panel} to influence ...
The \link
command does not do anything exciting in the printed
document. It simply typesets the text anchor. If you also want a
reference in the LaTeX output, you will have to add a reference using
\ref
or \pageref
. Sometimes you will want to place the
reference directly behind the anchor text. In that case you can
use the optional argument to \link
:
This parameter can be set in the \link{configuration panel}[~(Section~\ref{sect:con-panel})]{sect:con-panel} to influence ...
The optional argument is ignored in the HTML-output.
The starred version \link*
suppresses the anchor in the printed
version, so that we can write
We will see \link*{later}[in Section~\ref{sl}]{sl} how this is done.
It is very common to use \ref{
label}
or
\pageref{
label}
inside the optional
argument, where label is the label set by the link command.
In that case the reference can be abbreviated as \Ref
or
\Pageref
(with capitals). These definitions are already active
when the optional arguments are expanded, so we can write the example
above as
We will see \link*{later}[in Section~\Ref]{sl} how this is done.
Often this format is not useful, because you want to put it
differently in the printed manual. Still, as long as the reference
comes after the \link
command, you can use \Ref
and
\Pageref
.
\link{Such a file}{ipe-file} is at the same time ... a legal \LaTeX{} file\texonly{---see Section~\Ref}.
Note that when you use LaTeX's \ref
command,
the label does not mark a position in the document, but a
certain object, like a section, equation etc. It sometimes
requires some care to make sure that both the hyperlink and the
printed reference point to the right place, and sometimes you will
have to place the label twice. The HTML-label tends to be placed
before the interesting object--a figure, say--, while the
LaTeX-label tends to be put after the object (when the
\caption
command has set the counter for the label). In such
cases you can use the new Label
environment. It puts the
HTML-label at the beginning of the text, but the latex label at the
end. For instance, you can correctly refer to a figure using:
\begin{figure} \begin{Label}{fig:wonderful} %% here comes the figure itself \caption{Isn't it wonderful?} \end{Label} \end{figure}
A \link{fig:wonderful}
will now correctly lead to a position
immediatly above the figure, while a Figure~\ref{fig:wonderful}
will show the correct number of the figure.
A special case occurs for section headings. Always place labels after the heading. In that way, the LaTeX reference will be correct, and the Hyperlatex converter makes sure that the link will actually lead to a point directly before the heading--so you can see the heading when you follow the link.
After a while, you may notice that in certain situations Hyperlatex
has a hard time dealing with a label. The reason is that although it
seems that a label marks a position in your node, the HTML-tag
to set the label must surround some text. If there are other
HTML-tags in the neighborhood, Hyperlatex may not find an appropriate
contents for this container and has to add a space in that position
(which may sometimes mess up your formatting). In such cases you can
help Hyperlatex by using the Label
environment, showing Hyperlatex
how to make a label tag surrounding the text in the environment.
Note that Hyperlatex uses the argument of a \label
command to
produce a mnemonic HTML-label in the HTML file, but only if it is a
legal URL.
In certain situations--for instance when it is to be expected that
documents are going to be printed directly from web pages, or when you
are porting a LaTeX-document to Hyperlatex--it makes sense to mimic
the standard way of referencing in LaTeX, namely by simply using the
number of a section as the anchor of the hyperlink leading to that
section. Therefore, the \ref
command is implemented in
Hyperlatex. It's default definition is
\newcommand{\ref}[1]{\link{\htmlref{#1}}{#1}}
The \htmlref
command used here simply typesets the counter that was
saved by the \label
command. So I can simply write
see Section~\ref{sec:cross-references}
to refer to the current section: see Section *.
You can place a hyperlink to a given URL (Universal
Resource Locator) using
the \xlink
command. Like the \link
command, it takes an
optional argument, which is typeset in the printed output only:
\xlink{
anchor}{URL}\xlink{
anchor}[printed reference]{URL}
In the HTML-document, anchor will be an active hyperlink to the
object URL. In the printed document, anchor will simply be
typeset, followed by the optional argument, if present. A starred
version \xlink*
has the same function as for \link
.
If you need to use a ~
in the URL of an \xlink
command, you have
to escape it as \~{}
(the URL argument is an evaluated argument, so
that you can define macros for common URL's).
The Hyperlatex converter automatically partitions your document into
HTML-nodes. These nodes are simply numbered sequentially. Obviously,
the resulting URL's are not useful for external references into your
document--after all, the exact numbers are going to change whenever
you add or delete a section, or when you change the
htmldepth
.
If you want to allow links from the outside world into your new document, you will have to give that HTML node a mnemonic name that is not going to change when the document is revised.
This can be done using the \xname{
name}
command. It
assigns the mnemonic name name to the next node created
by Hyperlatex. This means that you ought to place it in front
of a sectioning command. The \xname
command has no function for
the LaTeX-document. No warning is created if no new node is started
in between two \xname
commands.
The argument of \xname
is not expanded, so you should not escape
any special characters (such as _
). On the other hand, if you
reference it using \xlink
, you will have to escape special
characters.
Here is an example: This section "Links into your document" in this document starts as follows.
\xname{hyperlatex_extlinks} \subsection{Links into your document} \label{sec:into-hyperlinks} The Hyperlatex converter automatically...
This HTML-node can be referenced inside this document with
\link{External links}{sec:into-hyperlinks}
and both inside and outside this document with
\xlink{External links}{hyperlatex\_extlinks.html}
If you want to refer to a location inside an HTML-node, you
need to make sure that the label you place with \label
is a
legal XML id
attribute. In other words, it must
start with a letter, and consist solely of characters from the set
a-z A-Z 0-9 - _ . :
All labels that contain other characters are replaced by an automatically created numbered label by Hyperlatex.
The previous paragraph starts with
\label{label_urls} \cindex[label]{\verb+\label+} If you want to refer to a location \emph{inside} an \Html-node,...
You can therefore refer to that position from any document using
\xlink{refer to that position}{hyperlatex\_extlinks.html\#label\_urls}
(Note that #
and _
have to be escaped in the \xlink
command.)
Hyperlatex understands the thebibliography
environment. Like
LaTeX, it creates a chapter or section (depending on the document
class) titled "References". The \bibitem
command sets a
label with the given cite key at the position of the reference.
This means that you can use the \link
command to define a
hyperlink to a bibliography entry.
The command \Cite
is defined analogously to \Ref
and
\Pageref
by \link
. If you define a bibliography like
this
\begin{thebibliography}{99} \bibitem{latex-book} Leslie Lamport, \cit{\LaTeX: A Document Preparation System,} Addison-Wesley, 1986. \end{thebibliography}
then you can add a reference to the LaTeX-book as follows:
... we take a stroll through the \link{\LaTeX-book}[~\Cite]{latex-book}, explaining ...
Furthermore,
the command \htmlcite
generates the printed citation itself (in our
case, \htmlcite{latex-book}
would generate
"[1]"). The command \cite
is approximately
implemented as \link{\htmlcite{#1}}{#1}
, so you can use it as usual
in LaTeX, and it will automatically become an active hyperlink, as in
"[1]". (The actual definition allows you to use
multiple cite keys in a single \cite
command.)
Hyperlatex also understands the \bibliographystyle
command
(which is ignored) and the \bibliography
command. It reads the
.bbl file, inserts its contents at the given position and
proceeds as usual. Using this feature, you can include bibliographies
created with BibTeX in your HTML-document!
It would be possible to design a WWW-server that takes queries
into a BibTeX database, runs BibTeX and Hyperlatex
to format the output, and sends back an HTML-document.
The formatting of the
bibliography can be customized by redefining the bibliography
environment thebibliography
and the Hyperlatex macro
\htmlbibitem
. The default definitions are
\newenvironment{thebibliography}[1]% {\chapter{References}\begin{description}}{\end{description}} \newcommand{\htmlbibitem}[2]{\label{#2}\item[{[#1]}]}
If you use BibTeX to generate your bibliographies, then you will
probably want to incorporate hyperlinks into your .bib
files. No problem, you can simply use \xlink
. But what if you also
want to use the same .bib file with other (vanilla) LaTeX files, which do not define the \xlink
command? What if you want to
share your .bib files with colleagues around the world who do
not know about Hyperlatex?
One way to solve this problem is by using the BibTeX @preamble
command. For instance, you put this in your BibTeX file:
@preamble(" \providecommand{\url}[1]{#1} ")
Then you can put a URL into the note field of a BibTeX entry as follows:
note = "\url{ftp://nowhere.com/paper.ps}"
Now your BibTeX file will work fine with any LaTeX documents, typesetting the URL as it is.
In your Hyperlatex source, however, you could define \url
any way
you like, such as:
\newcommand{\url}[1]{\xlink{#1}{#1}}
This will turn the note field into an active hyperlink to the document in question.
The \input
command is implemented in Hyperlatex. The subfile is
inserted into the main document, and typesetting proceeds as usual.
You have to include the argument to \input
in braces.
\include
is understood as a synonym for \input
(the command
\includeonly
is ignored by Hyperlatex).
The Hyperlatex converter understands the \index
command. It
collects the entries specified, and you can include a sorted index
using \htmlprintindex
. This index takes the form of a menu with
hyperlinks to the positions where the original \index
commands
where located.
You may want to specify a different sort key for an index
intry. If you use the index processor makeindex
, then this can
be achieved in LaTeX by specifying \index{sortkey@entry}
.
This syntax is also understood by Hyperlatex. The entry
\index{index@\verb+\index+}
will be sorted like "index
", but typeset in the index as
"\verb+\index+
".
However, not everybody can use makeindex
, and there are other
index processors around. To cater for those other index processors,
Hyperlatex defines a second index command \cindex
, which takes
an optional argument to specify the sort key. (You may also like this
syntax better than the \index
syntax, since it is more in line with
the general LaTeX-syntax.) The above example would look as follows:
\cindex[index]{\verb+\index+}
The hyperlatex.sty style defines \cindex
such that the
intended behavior is realized if you use the index processor
makeindex
. If you don't, you will have to consult your
Local Guide and redefine \cindex
appropriately. (That may
be a bit tricky--ask your local TeX guru for help.)
The index in this manual was created using \cindex
commands in
the source file, the index processor makeindex
and the following
code (more or less):
\W \section*{Index} \W \htmlprintindex \T \input{hyperlatex.ind}
You can generate a prettier index format more similar to the printed
copy by using the makeidx
package donated by Sebastian Erdmann.
Include it using
\W \usepackage{makeidx}
in the preamble.
You can use \typeout
to print a message while your file is being
processed.
![]() | ![]() | ![]() | Moving information around | Contents | Index |