bird/tools/linuxdoc-tools/LinuxDocTools/BackEnd.pm
Ondrej Zajicek (work) 58510024be Doc: Include full LinuxDocTools code
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.
2021-04-25 02:21:05 +02:00

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;