From e0c6872cf40896c7be36b11dcc744620f10adf1d Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Mon, 2 Sep 2019 13:46:59 +0900 Subject: Initial commit --- support/frankenbundle/README-Frankenbundle | 352 +++++++++++++++++++++++++++++ 1 file changed, 352 insertions(+) create mode 100644 support/frankenbundle/README-Frankenbundle (limited to 'support/frankenbundle/README-Frankenbundle') diff --git a/support/frankenbundle/README-Frankenbundle b/support/frankenbundle/README-Frankenbundle new file mode 100644 index 0000000000..d94f1c4a04 --- /dev/null +++ b/support/frankenbundle/README-Frankenbundle @@ -0,0 +1,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 + -- cgit v1.2.3