[l2h] adding perl implementations of commands to init

[Ross Moore]

Hello Martin,

On Tue, 21 Oct 2003 mjreed at essex.ac.uk wrote:

> Hi,
>
> I am trying to add some custom commands to be implemented in a
> latex2html init file.
>
> I think I can pull all the information out of latex2html.pl and other
> style.pl files to implement the code however I cannot get latex2html
> to properly call my code.

Yes, that is the right approach, at least for *simple* macros.

>
> say I have a latex macro
>
> \def\mymacro#1#2{do with #1 and something with #2}
>
> and I want to create a quick an dirty implementation in perl for it (I
> do not have a style file and do not want to create one) so I put the
> following in a latex2html init file:
>
> sub do_cmd_mymacro{
> 	# do some processing
> 	join('', "command placeholder", $_);
> }
>
> latex2html ignores the perl code with a complaint:
>
> *** wrap_cmd_mymacro not defined, cannot wrap \mymacro

The code has not been ignored.
There should be no need for wrapping *unless* there is a 2nd
definition for \mymacro in your job.

e.g. does your LaTeX document source still contain the definition
for \mymacro ?
  ... so that the document processess under (non-HTML) LaTeX.

If so, then you should wrap that definition in *conditional comments*

  %begin{latexonly}
   \newcommand{\mymacro}[2]{......  #1 ..... #2 ....}
  %end{latexonly}

This should be enough, provided the expansion of \mymacro is *constant*,
that is, can be expanded at any time in the processing, to give the *same*
result.


>
> However, if I implement a command as follows (just guessing from warning!)
>
> sub wrap_cmd_mymacro{
> 	# do some processing
> 	join('', "command placeholder", $_);
> }

No, the wrap_cmd_mymacro is *in addition to* the  do_cmd_mymacro.
It should not provide the expansion.

The purpose of *wrapping* is to control the time of expansion
of a macro to fit into the environment-order of the document.
Otherwise the expansion is either:

   1. done immediately, for user-defined macros
      (i.e. \newcommand, \providecommand, or \def, etc.
       within the document source)
OR
   2. done at the last stage of processing the contents
      of the macro-invocation's surrounding environment
      (last of all, if there is no such environment)
      when there is a  &do_cmd_<name> subroutine.

This is different to the usual TeX-processing order, but if the
expansion is constant, then the result should be correct.

The purpose of *wrapping* is to override this default mechanism
when the result of expansion would be different, according to when
the expansion takes place.


>
> It runs the command but not in a way that seems compatible with
> do_cmd_mymacro type of invocation (it appears to repeat the beginning
> of a line with the macro on). Is there a way to get Latex2html to call
> do_cmd_mymacro as it does for commands in a style file?
>
> I have played around with commands like
>
> &process_commands_wrap_deferred (<<_RAW_ARG_DEFERRED_CMDS_);
> mymacro # {} # {}
> _RAW_ARG_DEFERRED_CMDS_

Yes; this is the correct way to declare a macro be wrapped;
i.e. expanded in environment-order rather than be left until later.


> in the init file after the definition but this does not seem to help
> (and I really do not know what this is doing anyway!)

My guess is that you still have the \newcommand{\mymacro}...
(or \def\mymacro#1#2{..} ) unprotected within the document source.

Since &do_cmd_mymacro  is already known, then this changes the
\newcommand into a \renewcommand , which then invokes the
wrapping mechanism.
Failure to find  &wrap_cmd_mymacro  is *not* an error;
you may still get the correct results. The wrap_cmd_<name>
subroutines are for special cases where a macro may have
non-standard TeX-like syntax; e.g.
  \def\coords(#1,#2){....}
(rather than  \newcommand{\coords}[2]{.....}  ).


> There have been quite a few posts in the mail archive asking similar
> questions but I have not seen any answers - maybe answering might open
> a whole can of worms! Even an answer like "this is too hard" would be

LaTeX2HTML's expansion model is necessarily different from usual
TeX/LaTeX due to the need to create self-contained HTML pages in which
the tagging for environments is correctly nested, according to the
rules defined by the HTML recommendations.

The different kinds of declaration, of which there are 5 or 6,
are to help ensure that the right kind of interpretation is applied
to specific TeX macros/commands.
This applies to whether a command, or group of commands, is treated
as requiring an image --- should the image be placed inline with
the current paragraph, or is it displayed material ---
as well as handling whether or not it is dependent on the order of
its placement in the document source, or can it be ignored as being
irrelevant for HTML pages.

It's not really hard, but certainly "hard to describe" succinctly.  :-)


> better than nothing....

Hope this helps,

	Ross Moore

>
> Thanks,
>
> Martin
> --
> Dr. M.J. Reed                               Room:          4SB.6.15
> Dept. Electronic Systems Engineering         Tel:+44 (0)1206 872479
> University of Essex, Colchester CO4 3SQ, UK  FAX:+44 (0)1206 872900
> mailto:mjreed at essex.ac.uk    Web: http://esewww.essex.ac.uk/~mjreed
> _______________________________________________
> latex2html mailing list
> latex2html at tug.org
> http://tug.org/mailman/listinfo/latex2html
>