#
#  BackEnd.pm
#
#  $Id: BackEnd.pm,v 1.1.1.1 2001/05/24 15:57:41 sano Exp $
#
#  Dummy module containing backend specification.
#
#  © Copyright 1997, Cees de Groot
#
package LinuxDocTools::BackEnd;

die "This is a documentation package only!";

=head1 NAME

LinuxDocTools::BackEnd - LinuxDocTools back-end specification

=head1 SYNOPSIS

  require LinuxDocTools::BackEnd;
  $BackEnd->{...};

=head1 DESCRIPTION

LinuxDoc-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<LinuxDocTools>
package expects. Note that this interface is still subject to change, you
should check this document on new releases of LinuxDoc-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<%Formats> hash:

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

The rest of this document will deal with the entries in the local hash
referenced by I<$BackEnd>.

=head1 HASH ENTRIES

=over 4

=item NAME

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

  $BackEnd->{NAME} = "BackEnd";

=item HELP

Specify an optional extra help message printed when the default usage
function is executed (see L<LinuxDocTools::Utils>).

  $BackEnd->{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<$global>). 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<f> (flag), B<l> (list of allowed values),
B<s> (string), or B<i> (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->{OPTIONS} = [
     { option => "split", type => "l", 
       'values' => [ "0", "1", "2" ], short => "s" },
     { option => "dosnames", type => "f", short => "D" },
     { option => "imagebuttons", type => "f", short => "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->{'split'}  = 1;
  $BackEnd->{dosnames}  = 0;
  $BackEnd->{imagebuttons}  = 0;

=item preNSGMLS

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

  $BackEnd->{preNSGMLS} = sub {
    $global->{NsgmlsOpts} .= " -ifmtBackEnd ";
    $global->{NsgmlsPrePipe} = "sed 's/\@/\@\@/g' $global->{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<nsgmls>, and the output file descriptor should be filled with input 
to B<sgmlsasp>. This stage is often used to munch character entities
before they're fed to B<sgmlsasp>, see L<LinuxDocTools::CharEnts>. If the routine
doesn't return C<0>, LinuxDocTools aborts.

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

    while (<$infile>)
      {
         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<sgmlsasp> which normally needs finalization.
LinuxDocTools 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<sgmlsasp> output) and
should do whatever it likes with this datastream.

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

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

=back

=head1 SEE ALSO

L<LinuxDocTools> and subpackages.

=head1 AUTHOR

SGML-Tools are written by Cees de Groot, C<E<lt>cg@cdegroot.comE<gt>>, 
and various SGML-Tools contributors as listed in C<CONTRIBUTORS>.
Taketoshi Sano C<E<lt>sano@debian.org<gt>> rename it to LinuxDocTools,
and do some bug-fixes and updates on it.

=cut
1;