Selathco 0.91 Documentation Previous Next

5. Defining LaTeX commands

Since version 0.9, Selathco offers two ways of defining unknown LaTeX commands: Both ways manipulate with the "LatexParser.def" file, which has a simple structure:

       
# Definitions of LaTeX commands
# <command> = <class> 
#             <#nonmandatory prms> 
#             <#mandatory prms> 
#             <has free prms>

\               = Skips                 1 0 false
appendix        = Xref$Appendix         0 0 false
bf              = TypeFaces             0 0 false
begtt           = BegTT                 0 0 false
bibitem         = Biblio$BibItem        1 1 false
bigskip         = Skips                 0 0 false
...
The first word represents the LaTeX command name, after the '=' sign follows: the command handler class name (stored in the "<install_directory>/selathco/handlers" directory), the number of mandatory and nonmandatory command parameters and a boolean value indicating possible presence of free (TeX) parameter(s).

5.1 Scripting

Simple LaTeX commands that only write some simple string to the output, can be defined easily by adding one line to the "Script.def" file and adding appropriate definition to "LatexParser.def" - the handler must be Script. The basic structure of "Script.def" follows: 

# <command> = output text

dots		= ...
LaTeX		= <STRONG>LaTeX</STRONG>
multicolumn	= <TABLE BORDER="0"><TR><TD>$2</TD></TR></TABLE>
underline	= <U>$0</U>

The meaning of each line is quite obvious. Brief explanations requires only the $0 token (in underline command definition), which represents first mandatory parameter. Similarly, $1, $2, ... , $x would represent any of the following ones. The nonmandatory parameters can be acessed as $N0, $N1, ... , $Nx.

Example: scripting "\underline"
  1. Add a standard definintion to "LatexParser.def": 
    # <command> = <class> <#nonmandatory prms> <#mandatory prms> <has free prms>
underline   = Script  0                    1                 false
  2. Add the script defininition to "Script.def": 
    # <command> = output text
underline   = <U>$0</U>
LaTeX source... ...will be converted to HTML... ...and shown as
\underline{Hello}

<U>Hello</U>
Hello

5.2 Java programming

For more complex command handling you need to write a command handler. The command handler is a Java class that implements selathco.CommandHandler interface, which looks as follows:

       
public interface CommandHandler {
   public void handleCommand(LatexParser parser, 
			     String commandName, 
                             String[] nonmandParams, 
                             String[] mandParams, 
                             boolean hasFreeParams) throws Exception;

   public void endOfBlock(LatexParser parser, 
                          String commandName) throws Exception;
}

  • The handleCommand() method - is called when the command is matched and it is passed both mandatory and nonmadatory parsed parameters.
  • The endOfBlock() method - is called upon the enclosure of LaTeX block. It is used by typeface commands, for example, because HTML has a different font closing syntaxe:

    Example: typeface commands
    LaTeX source... ...is converted to HTML... ...which is shown as
    \tt {\it Hello
\bf world} !!!

    <TT></TT><I>Hello </I>
<B>world </B><TT>!!!
    		Hello world !!!
Most useful methods in the command hanlder:
  • parser.echo(String), parser.echo(int) - sends parameter to the output HTML file,
  • parser.peekByte() - peeks the top character of the input,
  • parser.readByte() - reads the top character of the input (may cause calling another sequence listener),
  • parser.pushbackBuffer() - pushes back internal parser buffer to the reader.
  • parser.getReader() - returns the current input file reader.
  • parser.getWriter() - returns the current output file writer.
  • parser.addSequenceListener(String, SequenceListener), parser.removeSequenceListener(String, SequenceListener) - adds/removes a sequence listener,
  • setListenersEnabled(boolean) - switches on/off all parser' sequence listeners.
  • Main.getPass() - returns pass number (1 or 2).
  • Debug.msg(String), Debug.finalMsg(String) - logs a message.
  • Debug.warn(String) - logs a warning.
Example: simple command handler
In the "LatexParser.def" file has to be a line: 
dots = Dots 0 0 false
saying that the \dots command has no parameters. The code itself is simple: 
package selathco.handlers;

import java.io.*;
import selathco.LatexParser;

public final class Dots extends CommandAdapter {
   public void handleCommand(LatexParser parser, 
                             String commandName, 
                             String[] nonmandParams, 
                             String[] mandParams, 
                             boolean hasFreeParams) throws IOException;
      parser.echo("...");
   }
}
The LaTeX \dots command prints three dots (taking care of the typography). HTML has no similar command, therefore it just prints "..." in the output. Notice that the Dots class extends CommandAdapter - an abstract class implementing the CommandHandler interface (both methods empty) - which is used just for convenience.

Note: Simple commands, such as \dots, can be handled more easier via scripting.

Here is a short list of notable command handler sources: