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;
|
