summaryrefslogtreecommitdiff
path: root/support/classpack/README
diff options
context:
space:
mode:
Diffstat (limited to 'support/classpack/README')
-rw-r--r--support/classpack/README129
1 files changed, 129 insertions, 0 deletions
diff --git a/support/classpack/README b/support/classpack/README
new file mode 100644
index 0000000000..99d3d81e45
--- /dev/null
+++ b/support/classpack/README
@@ -0,0 +1,129 @@
+README
+This is the README file for the classpack package.
+1 Summary
+LaTeX document classes and packages are normally created, maintained,
+and distributed in .dtx format using the ltxdoc class, which provides
+facilities for modular or fragmentary coding combined with interleaved
+documentation. However, the accurate construction of these files is
+technically challenging.
+ClassPack allows a developer to create an XML document containing user
+documentation and annotated code, based on the DocBook vocabulary (with
+some minor abuses). An XSLT2 script then generates the .dtx and .ins
+files, ensuring that all the relevant pieces are emitted in the correct
+order and in the correct syntax.
+This is experimental software, and is incomplete. It has been
+successfully used in-house by the author since 2008 for several
+institutional and commercial packages and classes. There are some known
+deficiencies which remain to be corrected, and some legacy code
+(originally included for one specific package) which needs to be removed
+to an external file.
+A paper describing the system has been accepted for the Balisage markup
+conference 2013 in Montréal.
+
+2 Normal installation
+This package is distributed as a .tds.zip file (TDS is the TeX Directory
+Structure, the standard layout for a modern TeX installation). Install
+it on any personal TDS-compliant TeX system by unzipping it into your
+personal TeX directory (folder). This will put all the files into the
+right places, so you can start using them immediately.
+If you haven't yet created a personal TeX directory, see below for
+details of what one is, and how to create it.
+On a shared (multiuser) system like a server, unzip it into the
+$TEXMFLOCAL directory instead (see below), and run your TeX
+directory-indexing program (eg texhash, mktexlsr, Update FNDB, etc) so
+that everyone can use it.
+If you are using an old non-TDS-compliant system, see below under Manual
+Installation.
+2.1 Your personal TeX directory
+This is a directory (folder) on single-user systems like desktops and
+laptops where you put all your local manual modifications, updates, and
+additions such as classes, packages, and fonts. The name and location
+are fixed:
+ Apple Mac OS X
+ ~/Library/texmf
+ Unix and GNU/Linux
+ ~/texmf
+ MS-Windows 95/XP
+ C:\texmf
+ MS-Windows 2007 and above
+ Computer\System\YOURNAME\texmf
+Create that folder if it does not already exist.
+ WARNING: If you are a Windows user running MiKTeX
+ !
+ ! When you create the folder, you must add it to MiKTeX's list of
+ ! supported folders. Run the MiKTeX Maintenance/Settings program,
+ ! select the Roots tab, and add the folder. You only have to do this
+ ! once.
+ !
+ ! Each time you add or remove software in your personal TeX folder,
+ ! you MUST also click on the Update FNDB button in the General tab.
+
+Unix (Mac and GNU/Linux) users do not need to (indeed, should not) run
+their filename database indexer (mktexlsr or texhash) for files put in
+your personal TeX directory.
+2.2 Installation on shared systems
+On multi-user systems (Unix-based), identify the shared local directory
+tree with the command
+ kpsewhich -expand-var '$TEXMFLOCAL'
+
+This will give you the location of the shared texmf directory into which
+you must install these files.
+Do not forget to run the texhash or mktexlsr (filename indexer) program
+after installation, otherwise the files will not be found by LaTeX and
+nothing will work!
+
+3 Manual installation (non-TDS systems)
+To install this software manually, unzip the zip file into a temporary
+directory and move the classpack.sty file from the tex/latex/classpack
+directory to a location (directory/folder) where LaTeX will find it on
+your system. This referred to in some documentation as "the TEXINPUTS
+directory", although it may be called something else on your system.
+IT IS YOUR RESPONSIBILITY TO KNOW WHERE THIS LOCATION IS. See the
+question in the TeX FAQ at
+http://www.tex.ac.uk/cgi-bin/texfaq2html?label=inst-wlcf for more
+information. If you do not know, or cannot find it, or do not have
+access to it, your TeX system may be out of date need replacing.
+3.1 Last resort
+In an emergency, and as a last resort on unmanageable systems, it is
+possible simply to put the classpack.sty file in your current working
+directory (the same folder as your .tex file[s]).
+While this may work, it is not supported, and may lead to other
+resources (packages, fonts, etc) not being found.
+
+4 Usage
+Make this the first line of your LaTeX document:
+ \usepackage[options]{classpack}
+
+Read the documentation for the options available. The documentation is
+distributed as a PDF document in the zip file. You can also regenerate
+it by typesetting the classpack.dtx file with LaTeX (and BiBTeX and
+makeindex) in the normal way.
+
+5 Bugs and TODO
+No outstanding reported bugs at the time of this version, but there are
+many facilities and features unimplemented, and the documentation is
+incomplete.
+
+6 Copyright
+The following statement is included in the source code:
+% Extracted from classpack.xml
+% classpack.sty is copyright © 2012-2013 by Peter Flynn <peter@silmaril.ie>
+%
+% This work may be distributed and/or modified under the
+% conditions of the LaTeX Project Public License, either
+% version 1.3 of this license or (at your option) any later
+% version. The latest version of this license is in:
+%
+% http://www.latex-project.org/lppl.txt
+%
+% and version 1.3 or later is part of all distributions of
+% LaTeX version 2005/12/01 or later.
+%
+% This work has the LPPL maintenance status `maintained'.
+%
+% The current maintainer of this work is Peter Flynn <peter@silmaril.ie>
+%
+% This work consists of the files classpack.dtx and classpack.ins,
+% the derived file classpack.sty, and any ancillary files listed
+% in the MANIFEST.
+