<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">#
#  BackEnd.pm
#
#  $Id: BackEnd.pm,v 1.1 1997/09/12 14:49:09 cg Exp $
#
#  Dummy module containing backend specification.
#
#  © Copyright 1997, Cees de Groot
#
package SGMLTools::BackEnd;

die "This is a documentation package only!";

=head1 NAME

SGMLTools::BackEnd - SGMLTools back-end specification

=head1 SYNOPSIS

  require SGMLTools::BackEnd;
  $BackEnd-&gt;{...};

=head1 DESCRIPTION

SGML-Tools backend modules need to conform to a certain interface which is
detailed in this document. The interface makes sure that new backend modules
(or customer overrides) are compatible with what the main B&lt;SGMLTools&gt;
package expects. Note that this interface is still subject to change, you
should check this document on new releases of SGML-Tools.

=head1 INTERFACE

The interface between the main package and individual backends is very
minimal - only one global variable is modified, everything else is local. It
relies heavily on references and complex datatypes, so you want to make
sure that you're up-to-date with Perl5.

Every backend creates a reference to a hash and stores this reference in
the global I&lt;%Formats&gt; hash:

  my $BackEnd = {};
  $Formats{"BackEnd"} = $BackEnd;

The rest of this document will deal with the entries in the local hash
referenced by I&lt;$BackEnd&gt;.

=head1 HASH ENTRIES

=over 4

=item NAME

Specify the name of the backend, for help messages etcetera.

  $BackEnd-&gt;{NAME} = "BackEnd";

=item HELP

Specify an optional extra help message printed when the default usage
function is executed (see L&lt;SGMLTools::Utils&gt;).

  $BackEnd-&gt;{HELP} = "This is just and example message";

=item OPTIONS

This specifies the local set of options, which is added to the global set
of options (available in I&lt;$global&gt;). The options are specified as an
array of hashes containing a number of keys:

=over 4

=item option

The long option name

=item type

The type of the option, one of B&lt;f&gt; (flag), B&lt;l&gt; (list of allowed values),
B&lt;s&gt; (string), or B&lt;i&gt; (integer).

=item values

An array of allowed values, in case the option is of the list type.

=item short

A short (single-letter) version of the option name.

=back

Options can be specified as long options:

  --papersize=a4

or as short options:

  -p a4

Note that both the long options as the short options must not conflict with
the global options (an override is not - yet - possible) and should not
conflict with other backends.

  $BackEnd-&gt;{OPTIONS} = [
     { option =&gt; "split", type =&gt; "l", 
       'values' =&gt; [ "0", "1", "2" ], short =&gt; "s" },
     { option =&gt; "dosnames", type =&gt; "f", short =&gt; "D" },
     { option =&gt; "imagebuttons", type =&gt; "f", short =&gt; "I"}
  ];

The long names themselves function as hash keys; a default can be given
here and the option processing function will store any values found
at the same place:

  $BackEnd-&gt;{'split'}  = 1;
  $BackEnd-&gt;{dosnames}  = 0;
  $BackEnd-&gt;{imagebuttons}  = 0;

=item preNSGMLS

If defined, this should contain a subroutine that normally does two things: it
can modify the global value C&lt;$global-E&lt;gt&gt;{NsgmlsOpts}&gt; and it can set the
global value C&lt;$global-E&lt;gt&gt;{NsgmlsPrePipe}&gt;. The first variable contains
the option string passed to B&lt;nsgmls&gt;, and the second variable can contain
a command that generates the input for B&lt;nsgmls&gt;, presumably using the
current input file in some way (the current input file can be found
in C&lt;$global-E&lt;gt&gt;{file}&gt;).

  $BackEnd-&gt;{preNSGMLS} = sub {
    $global-&gt;{NsgmlsOpts} .= " -ifmtBackEnd ";
    $global-&gt;{NsgmlsPrePipe} = "sed 's/\@/\@\@/g' $global-&gt;{file}";
  };

=item preASP

If defined, this should contain a subroutine accepting an input and an output
file descriptor. The input file descriptor contains the raw output from
B&lt;nsgmls&gt;, and the output file descriptor should be filled with input 
to B&lt;sgmlsasp&gt;. This stage is often used to munch character entities
before they're fed to B&lt;sgmlsasp&gt;, see L&lt;SGMLTools::CharEnts&gt;. If the routine
doesn't return C&lt;0&gt;, SGMLTools aborts.

  $BackEnd-&gt;{preASP} = sub
  {
    my ($infile, $outfile) = @_;

    while (&lt;$infile&gt;)
      {
         s/([^\\])\\n/$1 \\n/g;
	 print $outfile $_;
      }
    return 0;
  };

=item postASP

This entry should always be defined, because it needs to contain a routine
that receives the output from B&lt;sgmlsasp&gt; which normally needs finalization.
SGMLTools itself doesn't know about file-naming conventions, etcetera, of
the backend so writing the final file is left to the backend. The subroutine
receives a reference to a filehandle (containing B&lt;sgmlsasp&gt; output) and
should do whatever it likes with this datastream.

  $BackEnd-&gt;{postASP} = sub
  {
    my $infile = shift;

    copy ($infile, "$global-&gt;{filename}.ext");
    return 0;
  };

=back

=head1 SEE ALSO

L&lt;SGMLTools&gt; and subpackages.

=head1 AUTHOR

Cees de Groot, C&lt;E&lt;lt&gt;cg@pobox.comE&lt;gt&gt;&gt;, and various SGML-Tools contributors as
listed in C&lt;CONTRIBUTORS&gt;.

=cut
1; 
</pre></body></html>