summaryrefslogtreecommitdiff
path: root/support/frankenbundle/README-Frankenbundle
blob: d94f1c4a04f7604b38a7afe2c2f5960b4cd843ab (plain)
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>