/usr/share/perl5/LinuxDocTools/BackEnd.pm is in linuxdoc-tools 0.9.71-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 | #
# 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;
|