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
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
|
FRANKENBUNDLE
a system for maintaining and distributing LaTeX and BibTeX macros
available at
CTAN:/support/frankenbundle/*
------------------------------------------------------------------------
CONTENTS
OVERVIEW
COMPONENTS & FEATURES
REQUIREMENTS
HOW TO USE FRANKENBUNDLE
BUGS & FEEDBACK
DISTRIBUTION CONDITIONS
TERMINOLOGY
AUTHOR
------------------------------------------------------------------------
OVERVIEW
Frankenbundle allows an author to maintain and distribute a bundle
of one or more LaTeX packages and classes and BibTeX bibliography
styles, their documentation, and any support files with a high
degree of sophistication, consistency, and convenience for both the
bundle's author and the bundle's users, who will receive it in
a form easy to understand and use.
------------------------------------------------------------------------
COMPONENTS & FEATURES
Frankenbundle assists the author and users of a bundle in all
aspects of working with the bundle: development, distribution, and
evaluation & installation.
Frankenbundle assists development:
a comprehensive and easy-to-use Makefile makes the development
cycle easy;
Frankenbundle provides an Emacs major mode for editing .dtx
documents and managing their version numbers and CheckSums (you
don't have to use this to use the rest of Frankenbundle, but it's
pretty convenient, if I do say so myself);
Frankenbundle assists distribution:
Frankenbundle can prepare the bundle for distribution to
CTAN,
[ NOT YET--> ]
upload it to CTAN, and compose and send a proper email
to the CTAN archive managers;
[ NOT YET--> ]
Frankenbundle can register the bundle with the TeX Catalogue by
composing and sending a proper email to the TeX Catalogue manager;
Frankenbundle prepares all the bundle's files with proper
copyright notices and licenses them with either the GNU General
Public License (GPL) or the LaTeX Project Public License (LPPL).
It is easy to add facilities for other licences.
Frankenbundle assists evaluation & installation:
The distribution contains all DVI documentation prebuilt: end
users don't have to understand how to compile .dtx files and don't
have to take the trouble just in order to find out more detailed
information about your macros -- they can read the DVI
documentation straight from CTAN or the TeX Catalogue;
The DVI documentation contains an index and, when needed, a
bibliography (users can rebuild the DVI documentation if they
want);
Distributed macros are ready-to-use; End users without Make can
install simply by placing the directory (as found on CTAN) where
LaTeX and/or BibTeX can find it. No extraction or compiling is
necessary; users with Make or willing to take a few extra steps
can fine-tune their installation.
With one command, you and/or the end user can:
rebuild all the documentation
install all the macros, documentation, and sources into the
appropriate places in the TeX installation
as above, but using faster, stripped versions of the macros
bring all the macros up to date with respect to their sources
bundle up all the files into an archive ready to upload to CTAN
upload the archive and send emails to the archive managers and the
TeX Catalogue maintainer
Frankenbundle accommodates:
the GPL and the LPPL out of the box; other licences with minimal
configuration
three distinct sets of files: stable, beta, and alpha
"Stable" and "beta" files are distributed to CTAN in two
different directories (or the same one). "Alpha" files are not
distributed; they are for the developer's use only. When files
are installed into a TeX installation, stable, beta, and alpha
files all go to the same directory of the appropriate type,
e.g., macros, latex documentation, bibtex documentation, etc.
dependencies among packages and classes:
When one fileset is built or installed, filesets it depends on
it are also built and installed. For the end user, this can
include non-bundle filesets.
non-bundle filesets:
You can link non-bundle files from elsewhere on CTAN into your
CTAN directory so that the user who downloads your directory
will get ALL the files they need. You can write rules that will
class and package option and configuration files
packages and bibstyles having the same name
documentation containing BibTeX bibliographies
Frankenbundle can extract a minimal .bib file from a master .bib
file and distribute it with your bundle. Requires bibtool
(CTAN:/biblio/bibtex/utils/bibtool or
http://www.uni-koblenz.de/~gerd/ftp/BibTool).
------------------------------------------------------------------------
REQUIREMENTS
You, the author of the bundle, need a Unix-like environment and GNU
Make (ftp://gnu.mit.edu/pub/gnu).
I developed with Debian GNU/Linux and GNU Make v3.77--v3.79. It
should work with the free Cygwin GNU environment for Win9x operating
systems (http://www.cygwin.com). If your setup requires changes,
please send me advice on how to make Frankenbundle work better with
your system.
The end user does not need GNU Make, although installation is
particularly easy if they do have it.
You need a rudimentary understanding of Make and Makefiles. I think
you could know almost nothing and do fine just imitating the
included example file.
You need the Frankenstein bundle installed in your TeX installation.
See CTAN:/macros/latex/contrib/supported/frankenstein. You might
already have it in TDS:/texmf/tex/latex/frankenstein.
------------------------------------------------------------------------
HOW TO USE FRANKENBUNDLE
For each package, class, or bibstyle X in your bundle, you maintain
one file: X.dtx. For simplicity, let's assume it's a package, since
I don't have a good word for "package, class, or bibstyle". If
you're starting from scratch, start with the file template.dtx. If
you're adapting a package you've already written, look at the
template to see how to (re)organize your existing package.
Certain parts of the template are crucial. Other parts are just
suggestions for how to structure your documentation. The crucial
parts are the lines with four of the six \def's (comments tell you
which), and the lines with \CheckSum, \part{Implementation}, and
\Finale.
Look over the user documentation for the compsci package in the
Frankenstein bundle. It defines lots of nice macros that will help
you document your package clearly.
X.dtx will contain all the macros and documentation for your
package. On your command, Frankenbundle will combine X.dtx with
boilerplate in the files make/part1.dtx, make/part2.dtx, and
make/part3-dtx to produce X.sty, which is a USABLE package file.
Frankenbundle automatically produces files X.ins and X.tex from the
files make/extractor.ins and make/driver.tex. Running X.tex through
LaTeX produces X.dvi, the package documentation. Running X.ins
through (La)TeX produces X.stq, which is X.sty stripped of all
comments, and must be renamed X.sty before it can be used. End
users can do this themselves, or of course Frankenbundle can do it.
The four files that ultimately compose the distributed X package
fileset are: X.sty, X.dvi, X.ins, and X.tex. If you have a package
configuration file, X.cfg, or any package option files (.sto), these
will also be part of the distributed fileset.
We have assumed X is a package. Classes are parallel. If X is a
bibstyle, the fileset will contain X.bst, X-bst.dvi, X-bst.ins,
X-bst.tex, and X-bst.ver. The extra file X-bst.ver is necessary to
rebuild X-bst.dvi.
Package and class files share the same namespace. The fileset name
(i.e., how you refer to the package on the Make command line, and
when listing packages or classes in the Makefile) is simply the
package or class rootname. Package and class rootnames should NOT
end with -bst. Bibstyles have their own namespace. The fileset
name is the bibstyle rootname plus "-bst". All names should be
monocase. Thus, supposing you have:
stable-packages = gull raven
stable-classes = chickadee
then you cannot have a class named "gull" or "raven" and you cannot
have a package named "chickadee". You can have a bibstyle named
"gull", "raven", or "chickadee". Suppose you have a bibstyle called
"gull":
stable-bibstyles = gull
Then the "gull" fileset refers to the package fileset (e.g.,
gull.dtx, gull.sty, gull.ins, gull.tex, gull.cfg, gull-bst.dvi), and
the "gull-bst" fileset refers to the bibstyle fileset (e.g,
gull.bst, gull-bst.dtx, gull-bst.ins, gull-bst.tex, gull-bst.dvi,
gull-bst.ver). This is true even if you have just the bibstyle or
just the package. Notice that none of the names conflict but that
the loadable file of each fileset shares the same rootname, i.e.,
gull.sty and gull.bst.
So much for the concepts, here's how to actually set up
Frankenbundle and use it.
The Frankenbundle directory as you found it on CTAN will become the
development directory for your bundle.
If you are going to have more than one bundle, you probably want all
your bundles to share the same "make" subdirectory. To do this,
move the "make" subdirectory somewhere else convenient, maybe
calling it "frankenbundle", and change the make-dir variable in
Makefile to point to it. The TeX Directory Standard location is
TDS:/texmf/make/frankenbundle, so why not use that.
If you want to use the Emacs mode, move the files swiftex.el and
hilit-swiftex.el to where Emacs can find it, and byte-compile them.
See instructions in the comments of swiftex.el for how to use it and
how to set up Emacs to use `doctex' major mode for your .dtx, .cfg,
.sto, and .clo files.
I like having the development directory in my TeX search path, but
this is up to you.
Read through the following files and make changes as necessary.
There will be further notes in comments in the files themselves.
Makefile
Here is where you set up all your definitions that describe
your bundle. Documentation is in the file.
The brief top part of this file is all that the bundle's end
users should need to read and perhaps alter. If they have a
web2c-based TeX installation and a TDS-compliant texmf tree,
they should not have to alter anything.
Makefile as distributed is an example file from the
Frankenstein bundle, the project which motivated the
development of Frankenbundle. It shows you everything that
Frankenbundle can do. Your file will most likely be MUCH
simpler -- Frankenstein is a pretty complicated bundle.
make/part-1.dtx
Change the copyright notice to suit you.
make/extractor.ins
Change the copyright notice to suit you.
make/driver.tex
Change the copyright notice and the argument to \author.
If you want to use a different bibstyle than achicago, change
the contents of the first \IfCitations.
make/Frankenfile
You should not need to change much if anything in this file.
You may want to change the text of the help: target.
Please let me know if you find anything you think I should
change.
This is the file that does all the work. The idea is that
neither you nor users of your bundle have to understand or
even read this file.
If any Unix programs on your system have unusual names, you
should override their definitions with environment variables
or the Make command line. The default definitions in
Frankenfile should remain the most common ones in general use
because this is what is going to serve your users best when
you distribute your bundle.
If you use Emacs, outline-minor-mode is turned on
automatically, and you will find the file divided into
sections.
Finally, type run make with no arguments. The help message
displayed will describe to you all that you can do with
Frankenbundle.
------------------------------------------------------------------------
BUGS & FEEDBACK
If you need to make changes in Frankenfile to suit your project,
please describe them to me. If you find any problems or other
suggestions, please describe them to me.
------------------------------------------------------------------------
DISTRIBUTION CONDITIONS
The Frankenbundle files are given into the public domain. Please
acknowledge my work when appropriate. Such reflected glory is all I
get from releasing this work to you.
The files extractor.ins, part-1.dtx, part-2.dtx, and part-3.dtx in
the "make" subdirectory contain copyright notices mentioning my
name. These files are templates from which other files are
generated during the use of the Frankenbundle suite; the idea is
that you will replace those notices with your own notice of
distribution conditions. I leave them there first as an example and
second because I do not want to maintain two sets of templates, one
with my name in them and one without. I use those same templates to
distribute the Frankenstein bundle.
------------------------------------------------------------------------
TERMINOLOGY
fileset: A group of files related to a single LaTeX package, LaTeX
class, or BibTeX bibliography style and any accompanying
option or configuration files. The files in a package or
class fileset have the same root name but different
filename extensions. In bibstyle filesets, some root names
differ by a "-bst" suffix.
CTAN: Comprehensive TeX Archive Network: a system of TeX-related
file archives available via FTP (see
ftp://ctan.tug.org/tex-archive/CTAN.sites) and often
reproduced on CDROMs.
TDS: TeX Directory Structure: a recommended directory structure
for TeX installations. See
ftp://ctan.tug.org/tex-archive/tds.
------------------------------------------------------------------------
AUTHOR
Matt Swift
<swift@alum.mit.edu>
|