58510024be
BIRD uses hacked LinuxDocTools for building documentation, keeping some parts locally and using remaining parts from system-installed one. This setup breaks when LinuxDocTools makes some internal changes and is hard to keep consistent. Just include full LinuxDocTools code (both hacked and unmodified parts) to avoid consistency issues. Note that we still need some binaries from LinuxDocTools, so it still needs to be installed to build documentation.
185 lines
5 KiB
Perl
185 lines
5 KiB
Perl
#
|
|
# 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;
|