summaryrefslogtreecommitdiff
path: root/support/frankenbundle/README-Frankenbundle
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /support/frankenbundle/README-Frankenbundle
Initial commit
Diffstat (limited to 'support/frankenbundle/README-Frankenbundle')
-rw-r--r--support/frankenbundle/README-Frankenbundle352
1 files changed, 352 insertions, 0 deletions
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
+ <swift@alum.mit.edu>