diff options
Diffstat (limited to 'support/classpack/README')
-rw-r--r-- | support/classpack/README | 129 |
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. + |