Designing it yourselfTopCarrying onMoving information aroundContentsIndex

Moving information around

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.

Cross-references

 

You can use the \label{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 *.

Links to external information

 

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).

Links into your document

 

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.)

Bibliography and citation

 

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.

Splitting your input

 

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).

Making an index or glossary

 

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.

Screen Output

You can use \typeout to print a message while your file is being processed.


Tom Sgouros, November 14, 2004

Designing it yourselfTopCarrying onMoving information aroundContentsIndex