summaryrefslogtreecommitdiff
path: root/support/classpack/README
blob: 99d3d81e45646251bd78ac9c5b1987ae6b7bf4a0 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
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.