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