summaryrefslogtreecommitdiff
path: root/support/classpack/readme.xml
blob: f87175b79fe517423814518218a9659f7876f25b (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
<?xml version="1.0"?>
<!DOCTYPE chapter PUBLIC "+//Silmaril//DTD DocBook 5.0//EN"
  "/dtds/docbook/docbook-5.0/dtd/docbook.dtd" [
<!ENTITY TeX "TeX">
<!ENTITY LaTeX "LaTeX">
<!ENTITY BiBTeX "BiBTeX">
<!ENTITY LaTeX3 "LaTeX3">
<!ENTITY mdash " — ">
<!ENTITY nbsp " ">
<!ENTITY thinsp " ">
<!ATTLIST sect1 targetptr CDATA #IMPLIED type CDATA #IMPLIED>
<!ATTLIST anchor targetptr CDATA #IMPLIED type CDATA #IMPLIED>
]>
<chapter xml:id="readme" version="0.03" xml:lang="en:IE"
  revision="2012-06-16" annotations="Copyright © 2012 &LaTeX3; Project">
  <title>README</title>
  <para>This is the README file for the <olink targetptr="book"
      type="xml:id"/> <olink targetptr="book" type="arch"/>.</para>
  <sect1 targetptr="abstract" type="content">
    <title>Summary</title>
    <anchor targetptr="abstract" type="*" remap="title"/>
  </sect1>
  <sect1>
    <title>Normal installation</title>
    <para>This <olink targetptr="book" type="arch"/> is distributed as
      a <filename>.tds.zip</filename> file (TDS is the &TeX; Directory
      Structure, the standard layout for a modern &TeX; installation).
      Install it on any personal <acronym>TDS</acronym>-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.</para>
    <para>If you haven't yet created a personal &TeX; directory, see
      below for details of what one is, and how to create it.</para>
    <para>On a shared (multiuser) system like a server, unzip it into
      the <varname>$TEXMFLOCAL</varname> directory instead (see
      below), and run your &TeX; directory-indexing program (eg
      <productname>texhash</productname>,
      <productname>mktexlsr</productname>,
      <productname>Update&nbsp;FNDB</productname>, etc) so that
      everyone can use it.</para>
    <para>If you are using an old non-<acronym>TDS</acronym>-compliant
      system, see below under Manual Installation.</para>
    <sect2>
      <title>Your personal &TeX; directory</title>
      <para>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:</para>
      <variablelist>
	<varlistentry>
	  <term>Apple Mac OS&thinsp;X</term>
	  <listitem>
	    <para><systemitem>~/Library/texmf</systemitem></para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>Unix and GNU/Linux</term>
	  <listitem>
	    <para><systemitem>~/texmf</systemitem></para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>MS-Windows 95/XP</term>
	  <listitem>
	    <para><systemitem>C:\texmf</systemitem></para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>MS-Windows 2007 and above</term>
	  <listitem>
	    <para><systemitem>Computer\System\<replaceable>YOURNAME</replaceable>\texmf</systemitem></para>
	  </listitem>
	</varlistentry>
      </variablelist>
      <para>Create that folder if it does not already exist.</para>
      <warning>
	<title>If you are a Windows user running
	  <productname>MiK&TeX;</productname></title>
	<para>When you create the folder, you must add it to
	  <productname>MiK&TeX;</productname>'s list of supported
	  folders. Run the <productname>MiK&TeX;
	    Maintenance/Settings</productname> program, select the
	  <guilabel>Roots</guilabel> tab, and add the folder. You only
	  have to do this once.</para>
	<para>Each time you add or remove software in your personal
	  &TeX; folder, you <emphasis>must</emphasis> also click on
	  the <guibutton>Update FNDB</guibutton> button in the
	  <guilabel>General</guilabel> tab.</para>
      </warning>
      <para>Unix (Mac and GNU/Linux) users do not need to (indeed,
	should not) run their filename database indexer
	(<productname>mktexlsr</productname> or
	<productname>texhash</productname>) for files put in
	your personal &TeX; directory.</para>
    </sect2>
    <sect2>
      <title>Installation on shared systems</title>
      <para>On multi-user systems (Unix-based), identify the shared
	local directory tree with the command</para>
      <programlisting>kpsewhich -expand-var '$TEXMFLOCAL'</programlisting>
      <para>This will give you the location of the shared
	<filename>texmf</filename> directory into which you must
	install these files.</para>
      <para>Do not forget to run the
	<productname>texhash</productname> or
	<productname>mktexlsr</productname> (filename indexer) program
	after installation, otherwise the files will not be found by
	&LaTeX; and nothing will work!</para>
    </sect2>
  </sect1>
  <sect1>
    <title>Manual installation (non-TDS systems)</title>
    <para>To install this software manually, unzip the zip file into a
      temporary directory and move the <filename><olink
	  targetptr="book" type="xml:id"/>.<olink targetptr="book"
	  type="userlevel"/></filename> file from the
      <filename>tex/latex/<olink targetptr="book"
	  type="xml:base"/></filename> directory to a location
      (directory/folder) where &LaTeX; will find it on your system.
      This referred to in some documentation as <phrase>the
	<varname>TEXINPUTS</varname> directory</phrase>, although it
      may be called something else on your system.</para>
    <para><emphasis>It is your responsibility to know where this
	location is.</emphasis> See the question in the &TeX;
      <acronym>FAQ</acronym> at
      <uri>http://www.tex.ac.uk/cgi-bin/texfaq2html?label=inst-wlcf</uri> 
      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.</para>
    <sect2>
      <title>Last resort</title>
      <para>In an emergency, and as a last resort on unmanageable
	systems, it is possible simply to put the <filename><olink
	    targetptr="book" type="xml:id"/>.<olink targetptr="book"
	    type="userlevel"/></filename> file in your current working
	directory (the same folder as your <filename>.tex</filename>
	file[s]).</para>
      <para>While this may work, it is not supported, and may lead to
	other resources (packages, fonts, etc) not being found.</para>
    </sect2>
  </sect1>
  <sect1>
    <title>Usage</title>
    <para>Make this the first line of your &LaTeX; document:</para>
    <programlisting condition="class">\documentclass[options]{<olink
	targetptr="book" type="xml:id"/>}</programlisting> 
    <programlisting condition="package">\usepackage[options]{<olink
	targetptr="book" type="xml:id"/>}</programlisting> 
    <para>Read the documentation for the options available. The
      documentation is distributed as a <acronym>PDF</acronym>
      document in the zip file. You can also regenerate it by
      typesetting the <filename><olink targetptr="book"
	  type="xml:id"/>.dtx</filename> file with &LaTeX; (and
      &BiBTeX; and <productname>makeindex</productname>) in the normal
      way.</para>
  </sect1>
  <sect1 xml:id="bugs">
    <title>Bugs and TODO</title>
    <para>No outstanding reported bugs at the time of this version.</para>
  </sect1>
  <sect1 targetptr="copright" type="content">
    <title>Copyright</title>
    <para>The following statement is included in the source code:</para>
    <anchor targetptr="copyright" type="*"/>
  </sect1>
</chapter>