[l2h] Another proposal for a new definition of \externalref in html.sty

[Robert Petry]

This is a multi-part message in MIME format.
--------------16712C7DF0DAEAE4D1BD3126
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit

Hi again,
    This is a followup to my suggestion in an earlier contribution to
redefine \externallabels and \externalref by adding optional arguments.
This was to allow for labels to be included from external documents in
the latex dvi files.  It was pointed out to me by Ross Moore that this
would not be possible.  This is because these commands both apparently
have an optional [<prefix>] already which causes such external labels to
be prepended by the prefix to distinguish them from labels in the
current document.  Apparently this is documented in the Latex Web
Companion, but unfortunately my docs didn't have this so I apologize.
    I tried using the optional prefix in both commands but found that I
couldn't use \externalref[<prefix>]{<label>} successfully.  Only
\externalref{<prefix><label>} seemed to work. (I'm using latex2html
Version 99.2beta6).  Does \externalref really allow the prefix to be
entered as an optional argument?  If so could someone give me an example
which works?
    The next point of followup is that I had written a package called
externlabels.sty distributed with my last message which contained a
command \externlabels{} to include labels from another document's
auxilliary file into the latex dvi file.  I have since found out that
the command \externaldocument[<prefix>]{full_path} in the xr.sty package
does precisely this where full_path is the path to the .aux file of the
external document without the .aux extension.  This is the proper route
to include external labels in a dvi file.  While one may use
\ref{<prefix><label>} and \pageref with labels included using
\externaldocument, these (or at least \pageref) do not work with
latex2html properly and secondly they don't show that a label's source
is from a document external to the current latex file so there is a need
to improve the situation.
  This leaves only the question of how \externalref[ ]{} could be
defined in html.sty to work in latex to solve the problem.  As mentioned
before its current behaviour is to put nothing in the dvi file.  If it
doesn't really take an optional argument it could still be defined as in
my previous suggestion to take optional arguments of [ref], [pageref],
[noref], etc. with the default behaviour of putting a \ref in the
document.  Alternatively if it really does allow the [<prefix>] optional
argument, then I would propose that the following three commands should
be defined in html.sty, all of which would have the same behaviour in
latex2html of placing a hyperlink, but
which produce either a \ref, \pageref, or no reference at all in the dvi
file:

\externalref[<prefix>]{<label>}     OR  \externalref{<prefix><label>}
\externalpageref[<prefix>]{<label>} OR
\externalpageref{<prefix><label>}
\externalnoref[<prefix>]{<label>}   OR  \externalnoref{<prefix><label>}

The \externalref command would do  the equivalent of \ref in the dvi
file, the \externalpageref would do a \pageref, while \externalnoref
would produce no reference in the dvi file.  All would place the same
link in the html files produced by latex2html.  \externalnoref would
have the same behaviour as the current \externalref command.  The
<prefix> would be the same as the <prefix> used in \externaldocument and
\externallabels.

Attached to this email is a new package to define these commands called
externalref.sty.  See the documentation inside it on how it should be
used.  Essentially just include the package AFTER html.sty and use
\externallabels (from html.sty) and \externaldocument (from xr.sty) to
include the html and .aux labels.  Add the lines

\begin{htmlonly}
\def\externalpageref{\externalref}
\def\externalnoref{\externalref}
\end{htmlonly}

at the top of the latex document in order to use \externalpageref and
\externalnoref with latex2html properly. (latex2html ignores style files
it doesn't recognize so these lines can't be in externalref.sty.)
Obviously my desire is that externalref.sty would be incorporated into
html.sty, but this would work in the meantime (or if it is considered
undesirable to add these definitions to html.sty).

Note that my reasoning for \externalref to really do something in a
latex file is not because there aren't other commands (like hyperref)
which COULD be used to handle this.  The point however is to have a
command which can be used in latex documents which are not necessarily
destined to be converted to html, but which could be easily converted
should the need arise.  For such documents one just wants an easy way to
refer to labels in external document with NO consideration of how the
references could be better constructed in an html document.

I'd be interested in knowing what others think about this suggestion for
definitions of \externalref or my former one as well as whether
externalref really does currently work with an option argument in
latex2html.


-Robert Petry


--------------16712C7DF0DAEAE4D1BD3126
Content-Type: text/plain; charset=us-ascii; name="externalref.sty"
Content-Transfer-Encoding: 7bit
Content-Disposition: inline; filename="externalref.sty"

%%% EXTERNALREF.STY %%%
%
%   This style file creates several commands for using labels in one
% latex document from a separate latex document in a way which is
% compatible with the latex2html command \externalref.  externalref.sty
% redefines the default behaviour of \externalref defined in html.sty
% which comes with the latex2html installation.  That default behaviour
% is to produce no output in the latex DVI file and a hyperlink in the
% html files produced in latex2html.
%
%   For those using externalref.sty and html.sty, externalref.sty must be
% included AFTER html.sty due to the redefinitions.  In addition the following
% lines should be uncommented and placed at the beginning of any file which
% wishes to use \externalpageref and \externalnoref defined below with
% latex2html.
% 
% \begin{htmlonly}
% \def\externalpageref{\externalref}
% \def\externalnoref{\externalref}
% \end{htmlonly}
%
% Ultimately it is desired that all of externalref.sty be incorporated
% into html.sty so this will not be necessary.  Currently latex2html ignores
% style files for which it has no perl equivalent which makes these four
% lines of code necessary in the actual tex document.
%
%   To include external references in just a latex dvi file, the standard
% latex package "xr.sty" contained in the tools bundle should be included
% in the preamble and the \externaldocument command executed:
%
% \usepackage{xr}
% \externaldocument[<prefix>]{<full_path>}
%
% where <full_path> is the pathname of the external document whose labels
% are to be accessed WITHOUT ANY EXTENSION ON THE FILENAME.  \externaldocument
% adds the extension ".aux" to full_path to access the auxilliary file
% which contains the labels.  If the external document is a remote document a
% local copy of the .aux file will have to be made with <full_path>.aux
% pointing to it. <prefix> is an optional argument added to
% all the labels of the external document so that labels can be
% distinguished from the current document.  Note that there is no delimeter
% placed between the prefix and the label, so you may wish to end your prefix
% with a ":" for instance.
%
%   To include the external references in the html docs produced by
% latex2html, one also has to use the \externallabels command in the html.sty
% package in the preamble:
%
% \usepackage{html}
% \externallabels[<prefix>]{<URL to directory of external document>} 
%    {<local copy of external document labels.pl file>}
%
% See the latex2html documentation for details.  The optional <prefix> label
% should be the same as above.
%
%   Finally to reference the labels in the tex document, the externalref.sty
% package defines the following commands:
%
% \externalref[<prefix>]{<label>}     OR  \externalref{<prefix><label>}
% \externalpageref[<prefix>]{<label>} OR  \externalpageref{<prefix><label>}
% \externalnoref[<prefix>]{<label>}   OR  \externalnoref{<prefix><label>}
%
% The \externalref command does the equivalent of \ref, the \externalpageref
% does a \pageref, while the \externalnoref produces no reference in the dvi
% file but places a link in the html files produced by latex2html.  (The
% current version of \externalref defined in html.sty has the same behaviour
% as \externalnoref.)  The <prefix> must be the same as the <prefix> used
% in \externaldocument and \externallabels.  Finally note that as of
% the writing of this document the first versions of the \externalref family of
% commands where the <prefix> is entered as an optional argument do not
% seem to work with latex2html (Version 99.2beta6) so the second format of
% each of the commands is preferred until html.perl is altered.  Note as
% well that latex2html has more sophisticated reference commands such
% as \hyperref for more serious latex web documents.  \externalref is for
% users who are writing latex documents that share references which they
% want the option of easily porting to html format with references intact.
%
% Finally note that one can use \ref and \pageref with labels included
% using \externaldocument, but \externalref and \externalpageref are
% preferable because they will be usable by latex2html and they
% indicate that the source of the label is outside the document.  
%  
% SOURCE
% This was written by Robert Petry on March 10, 2000 in an attempt to
% make \externalref useful within normal latex dvi files.
%
%%% 
%
% The following (pseudo)command tells latex2html to ignore these
% definitions.  This is currently unnecessary since latex2html typically
% ignores style files for which it has no perl implementation, but we
% put this just to be safe.
%begin{latexonly}
%
% The following command is used in if statements in \externalref and
% \externalnoref to deal with the case when no optional
% argument is given to the command.
\def\nooptgiven{nooptgiven}
%
% EXTERNALREF
\ifx\undefined\externalref
 \def\next{\newcommand}
\else
 \def\next{\renewcommand}
\fi
\next{\externalref}[2][nooptgiven]{
\begingroup
  \def\firstargument{#1}
  \ifx\firstargument\nooptgiven
    \ref{#2}
  \else
    \ref{#1#2}
  \fi
\endgroup
}
%
% EXTERNALPAGEREF
\ifx\undefined\externalpageref
 \def\next{\newcommand}
\else
 \def\next{\renewcommand}
\fi
\next{\externalpageref}[2][nooptgiven]{
\begingroup
  \def\firstargument{#1}
  \ifx\firstargument\nooptgiven
    \pageref{#2}
  \else
    \pageref{#1#2}
  \fi
\endgroup
}
%
% EXTERNALNOREF
\ifx\undefined\externalnoref
  \def\next{\newcommand}
\else
  \def\next{\renewcommand}
\fi
\next{\externalnoref}[2][nooptgiven]{}
%
\let\next=\relax

% The following is a pseudo command for latex2html - leave it in.
%end{latexonly}

--------------16712C7DF0DAEAE4D1BD3126--