summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/support/classpack/README.md
blob: 98aca922ca5b75f0cd7e537bef53b82683f9e213 (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
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206

[//]: # (classpack LaTeX package)

# classpack

This is the README.md file for the classpack LaTeX package v1.19 (2020-05-19)
generated by ClassPack v.1.19 (2020-05-19) on 20 May 2020 at 14:32:36 

## Summary

LaTeX document classes and packages are conventionally created,
maintained, and distributed in DocTeX (`.dtx`) format using the _ltxdoc_
class, which provides for interleaved code and documentation (“literate
programming”). However, the accurate construction of these files is
technically challenging, and editing them is tedious and error-prone.

_ClassPack_ allows a developer to create a _DocBook5_ XML document for a
class or package, containing the documentation and annotated code, and
it provides XSLT3 scripts to generate the `.dtx`, `.ins`, and other
files, which can be combined into a zip file suitable for submission to
CTAN.

_This package __classpack__ contains the small typographic adjustments
and utilities needed to re-typeset the documentation of classes and
packages developed using __classpack-dev__. It is not used for any other
purpose and is not required for using any other class or package, only
for the documentation of __ClassPack__–developed classes and packages._

**You do not need to install the upcoming development package
**_classpack-dev_** unless you want to develop classes or packages by
using **_ClassPack_** yourself.**

_ClassPack_ is a work-in-progress. A paper describing an earlier version
was presented at the Balisage markup conference in Montréal (Flynn,
2013).


## Automated installation

If this package is distributed from CTAN, it should be in a zip file
which allows it to be installed automatically by the TeX Live Manager
(tlmgr) and similar automated installers.

If you are using automated LaTeX package installation, no further action
is required: the package will be installed the first time you use it in
a LaTeX document.

If you are using the TeX Live Manager (_tlmgr_) program manually, you
can install this package with the command:

    $ tlmgr install classpack


## TDS installation

This package is also available as a TeX Directory System (TDS) zip file
(`.tds.zip`). This is the standard directory layout for a modern TeX
installation which enables the package to be unzipped directly into your
Personal TeX Directory without the need to use _tlmgr_. If you haven’t
yet created a Personal TeX Directory, see below for details of what one
is, and how to create it.
  *  You can install this package on any TDS-compliant personal system
(laptop, desktop, workstation, table, smartphone, PDA, etc) by unzipping
it straight into your Personal TeX Directory. This will put all the
files into the right places, so you can start using them immediately.
  *  On a shared (multiuser) system like a server, the administrator can
unzip it into the `$TEXMFLOCAL` directory instead (see below), and run
your TeX directory-indexing program (eg _texhash_, _mktexlsr_, etc) so
that everyone can use it.
  *  If you are using an old non-TDS-compliant system, see below under Manual
Installation.

### Your Personal TeX Directory

This is a directory (folder) where you should put all local manual
modifications (updates, additions such as new or updated classes,
packages, and fonts) that are _not_ handled automatically by _tlmgr_.
The name and location are fixed (for all practical purposes):
  *  Apple Mac OS X

    ~/Library/texmf
  *  Unix and GNU/Linux

    ~/texmf
  *  MS-Windows 95/XP/NT

    C:\texmf
  *  MS-Windows 2007 and above

    Computer\System\YOURNAME\texmf

Create that folder now if it does not already exist. Put (or unzip) all
additions to your system that are _not_ handled by _tlmgr_ into this
directory, following _exactly_ the subdirectory structure that is used
in your main TeX distribution (unzipping a TDS file does this for you).
This is what enables LaTeX to find stuff automatically.


> ####  If you are a Windows user running _MiKTeX_
> When you create the folder for your Personal TeX Directory, 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 Directory, you MUST then click on the `Update FNDB` button in the `General` tab of the _MiKTeX Maintenance/Settings_ program, otherwise _MiKTeX_ will not find them and nothing will work!
> 

Unix (Mac and GNU/Linux) users do not need to (indeed, should not) run
their filename database indexer program (_mktexlsr_ or _texhash_) for
files put into a personal TeX directory.


## 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 unzip these files.

Do not forget to run your local TeX filename database indexer program
(_texhash_ or _mktexlsr_) after installation, otherwise the files will
not be found by LaTeX and nothing will work!


## Manual installation (non-TDS systems)

To install this software manually, download and unzip the _non-_TDS zip
file into a temporary directory and move the class and/or package
file[s] and other files to the proper locations where LaTeX will find
them on your system. This is 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 and may need replacing.



## Online systems and “last resort” systems

Some online LaTeX systems use CTAN, so a package from there should be
available on demand. For other online LaTeX systems where you do not
have access to the file system, unzip the _non-_TDS zip file into a
temporary directory and upload the files to the online system. Follow
their instructions for where to put them.

In an emergency, or as a last resort on unmanageable systems, it is
possible simply to put the class and/or package file[s] into 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, images etc) not being found.


## Usage

Include the line shown below in the Preamble of your LaTeX document; a
`\documentclass` line should be at the top; a `\usepackage` command
normally goes anywhere in the Preamble:

    \usepackage[options]{classpack}

(similarly for other classes or packages if more than one is supplied
with this package). Read the documentation for the options available, if
any. The documentation is distributed as a PDF document in the zip file.
You can also regenerate it by typesetting the `classpack.dtx` file with
`xelatex` (and `biber` and _makeindex_) in the normal way.


## Bugs and TODO

No outstanding reported bugs at the time of this version.

For TODO items, see the PDF documentation.


## Copyright

The following statement is included in the source code:

     Transformed from classpack.xml by ClassPack db2dtx.xsl
     version 1.19 (2020-05-19) on Wednesday 20 May 2020 at 14:32:36
    
     classpack.sty is copyright © 2012-2020 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 , 
     and any other ancillary files listed in the MANIFEST.