Conditional Text

         

   
\begin{latexonly} and \begin{htmlonly}

Conditional text can be specified using the environments latexonly and htmlonly. These allow writing parts of a document which are intended only for electronic delivery or only for paper-based delivery.

This would be useful for example in adding a long description of a multi-media resource in the paper version of a document. Such a description would be redundant in the electronic version, as the user can have direct access to this resource.

Here is an example of the use of the latexonly environment, used earlier in this manual: \begin{latexonly}

\begin{figure}
    \begin{center}
    \fbox{\includegraphics[width=4in]{psfiles/eform.ps}}
    \end{center}
    \caption{An electronic form. Of course in the online version of this
     document the form above would be active.}
\end{figure}

\end{latexonly}

Note the warning concerning how the environment delimiters should be used in the L^ATEX source code.

 

  
\htmlonly...\endhtmlonly

^97.1
This is an alternative way to specify a chunk of material intended for the HTML version only, using the old A_MS-style of delimiting environments. Use of this style is discouraged; the htmlonly environment is preferred.
^97.1

 

  
\latexonly...\endlatexonly

^97.1
This is an alternative way to specify a chunk of material intended for the L^ATEX typeset version only, using the old A_MS-style of delimiting environments. Use of this style is discouraged; the latexonly environment or the unscoped %begin{latexonly} construction are preferred.
^97.1

Note the warning concerning how the environment delimiters should be used in the L^ATEX source code.

       

  
\latex, \html and \latexhtml

^96.1
There are also shorthand notations to accomplish the same thing as in the latexonly environment and htmlonly environment, but with less typing.

• The \latex{...} command causes everything within the braces to be processed by L^ATEX, but ignored by L^ATEX2HTML.
• Conversely, the \html{...} command causes everything within the braces to be ignored by L^ATEX and processed by L^ATEX2HTML.
• Finally the command \latexhtml{...}{...} causes everything within the first set of braces to be processed exclusively by L^ATEX, with the contents of the second set of braces processed solely by L^ATEX2HTML.

Warning: Only small pieces of text work reliably in this way. With whole paragraphs or contained sub-environments, the ``conditional'' environments should be used instead.
^96.1

     

  
%begin{latexonly}

Another variant of the latexonly environment is available, in which everything between 151 is ignored by \latextohtml. The difference is that the \env{latexonly} environment puts the contents into a group, in which all definitions are local. There is no such scoping with the \verb since L^ATEX sees the initial %s simply as starting comments.

 
The following example should clarify what happens:

\newcommand{\A}{The letter A.}
\newcommand{\B}{The letter B.}

\begin{latexonly}
\renewcommand{\A}{Not the letter A.}
\end{latexonly}
154 \indent\indent\verb |
155 \begin{tex2html_preform}verbatim11#\end{tex2html_preform} If you process this with \LaTeX, the result is: \quad\quad The letter A. Not the letter B. \smallskip\noindent Note the \hyperref[page]{warning}{warning at the bottom of page~}{}{env:warn} concerning how the environment delimiters should be used in the \LaTeX{} source code. \medskip\index{conditional text!avoid using counters}\html{\\}\noindent \textbf{Warning:}156 Be careful when using \LaTeX{} commands which alter the values of counters (e.g. numbered figures or equations) in conditional text, because this may cause the counter values in the electronic version to lose synchronisation with the values of the corresponding counters in the \LaTeX{} version. \htmlrule[width=300] \index{imagesonly@\env{imagesonly} environment}157 \index{environment!imagesonly@\env{imagesonly}}158 \paragraph*{\Lc{begin\char123imagesonly\char125}\label{imagesonly}} \cbversion{97.1}\begin{changebar} This environment is used to put \LaTeX{} code into the \fn{images.tex} file, to be used when generating images. Typically this is used to add commands to the preamble of \fn{images.tex}, such as setting the text or background color. However code can be added at any other point as well; e.g. to change the background color of all images after a certain point in the document. \end{changebar}159 \smallskip\noindent Note the \hyperref[page]{warning}{warning at the bottom of page~}{}{env:warn} concerning how the environment delimiters should be used in the \LaTeX{} source code. \index{makeimage@\env{makeimage} environment}160 \index{environment!makeimage@\env{makeimage}}161 \paragraph*{\Lc{begin\char123makeimage\char125}\label{makeimage}} \cbversion{97.1}\begin{changebar} This is a special environment which forces an image to be made of its contents. That is, one gets effectively a snapshot of a portion of a page that has been typeset using \LaTeX. Within the normal \LaTeX{} typeset version of the document, this environment is completely transparent, adding its contents to the page as usual. \index{makeimage@\env{makeimage} environment!inside@inside a \env{figure}}\html{\\}162 One further important use of the \env{makeimage} environment is as follows. If a \env{makeimage} environment occurs as a sub-environment within a \env{figure} environment, then an image will \emph{not} be made of the \env{figure}'s contents. Instead, the contents are treated as normal text, each part being handled as if there were no \env{figure} at all, except that everything is placed within a single cell of a \HTMLtag{TABLE}...\HTMLtag{/TABLE} construction in \HTMLiii. The contents of any \Lc{caption} commands are placed between \HTMLtag{CAPTION}...\HTMLtag{/CAPTION} tags for the \HTMLtag{TABLE}. \index{makeimage@\env{makeimage} environment!empty sub-environment}\html{\\}163 Normally an image of the entire contents of the \env{figure} would be placed within the single cell of the \HTMLtag{TABLE}. Now images are made of any subparts of those \env{figure}'s contents that really need it, in particular the \env{makeimage} sub-environments. An empty \env{makeimage} sub-environment does not generate an image of itself, yet still it inhibits an image being made of the whole \env{figure}. These comments apply also to \env{table} environments. \end{changebar}\html{\\} \subsection{Symbolic References shown as Hyperized Text\label{hyperized}164 165 \index{references@references\protect\label{IIIrefs}}}166 \tableofchildlinks* \index{cross-references!seereferences       
In printed documents cross-references are shown through a numeric or symbolic indirection e.g. ``see Figure 1'' (numeric indirection), or ``see section `Changes' '' (symbolic indirection). L^ATEX2HTML can mirror this mechanism using the same numeric or symbolic references, or when these are not appropriate by using iconic references.

   
In a hypertext document however, cross-references can be shown without any indirection, just by highlighting a relevant piece of text. This can make a document more readable as it removes unnecessary information.

 

  
\hyperref

A single new L^ATEX command \hyperref can be used for specifying how a cross-reference should appear, both in the printed document and in the hypertext version. For example, assuming that the label {sec:cond}  is defined somewhere within a document, the command \hyperref, taking 4 arguments, can be used in that document as follows:    

\emph{Is the concept of
\hyperref
 % This will be highlighted in the hypertext version
{conditional text} % argument #1
% This will be shown in the printed version 
 % followed by a numeric reference ...      
{conditional text (see Section } % argument #2
% ... followed by this text
{ for more information)} % argument #3
% This is the common label 
{sec:cond} % argument #4
a good idea? }

Here is how it will be shown:

Is the concept of conditional text a good idea?

In the printed version what would appear is:

Is the concept of conditional text (see Section 4.2 for more information) a good idea?

^97.1
An extended syntax for \hyperref uses an optional argument, which determines what information is to be placed in the L^ATEX version of the document. The value of this optional argument can also affect the number of required arguments. These forms are recognised:

 \hyperref[ref]{<HTML-text>}{<LaTeX-text> }{<post-LaTeX>}{<label>}
\hyperref{<HTML-text>}{<LaTeX-text> }{<post-LaTeX>}{<label>}

\hyperref[pageref]{<HTML-text>}{<LaTeX-text> }{<post-LaTeX>}{<label>}
\hyperref[page]{<HTML-text>}{<LaTeX-text> }{<post-LaTeX>}{<label>}

\hyperref[noref]{<HTML-text>}{<LaTeX-text> }{<label>}
\hyperref[no]{<HTML-text>}{<LaTeX-text> }{<label>}

The first two are the defaults, where L^ATEX uses \ref{ <label>}. With the next two L^ATEX uses \pageref{ <label>}, while with the final two L^ATEX completely ignores the <label>, setting just the <LaTeX-text>.
^97.1

 
For creating hyperlinks to other documents using symbolic reference <label>s, see also the \externalref command.

The preceding paragraph is an example of the use of the \hyperref[page] option. Its source code is:

For creating hyperlinks to other documents
using symbolic reference \Meta{label}s, 
see also the \Lc{externalref} 
\hyperref[page]{command}{command, described on page~}{}{externref}.

which appears in the L^ATEX typeset version as:

For creating hyperlinks to other documents using symbolic reference <label>s, see also the \externalref command, described on page 31.

In fact both \hyperref and the \htmlref command, to be described next, permit textual hyperlinks based on symbolic <label>s from external files.

   

  
\htmlref

Another command also defined in html.sty html.sty is \htmlref which has the same effect as \hyperref during the conversion to HTML. It takes two arguments, some text and a label. In the HTML version the text will be ``hyperized'', pointing to the label. In the paper version the text will be shown as it is and the label will be ignored; e.g.  

With \verb|\htmlref| \htmlref{it's easy to make links}{fig:example}.

which produces:

With \htmlref it's easy to make links.

In the L^ATEX typeset version it will appear simply as:

With \htmlref it's easy to make links.