<?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>
