summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/latex-tds/readme.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/latex-tds/readme.txt')
-rw-r--r--Master/texmf-dist/source/latex/latex-tds/readme.txt415
1 files changed, 415 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/latex-tds/readme.txt b/Master/texmf-dist/source/latex/latex-tds/readme.txt
new file mode 100644
index 00000000000..f56555c7145
--- /dev/null
+++ b/Master/texmf-dist/source/latex/latex-tds/readme.txt
@@ -0,0 +1,415 @@
+readme.txt for project latex-tds, 2006/08/28
+
+TABLE OF CONTENTS
+=================
+A. Abbreviations, Glossary
+B. Project latex-tds
+C. Download
+D. Installation Hints
+E. Copyright, License
+F. Manifest
+G. Design Principles
+H. Remarks
+I. Build Hints
+J. History
+
+
+A. ABBREVIATIONS, GLOSSARY
+==========================
+[CTAN]
+ Comprehensive TeX Archive Network.
+ FAQ entry: http://www.tex.ac.uk/cgi-bin/texfaq2html?label=archives
+ For example, you can resolve the prefix `CTAN:' by using
+ `ftp://ftp.ctan.org/tex-archive/'.
+[latex-tds]
+ The name of this project.
+[TDS]
+ TeX Directory Structure.
+ FAQ entry: http://www.tex.ac.uk/cgi-bin/texfaq2html?label=tds
+ Specification: CTAN:tds.zip
+
+
+B. PROJECT LATEX-TDS
+====================
+
+How it has started
+------------------
+The project started as I wanted to install the new LaTeX release 2005/12/01
+that was announced at 2006/04/27. However the files aren't packed in
+TDS format, ready for unpacking in the destination directory. And
+the documentation files were not yet generated or the provided
+PDF files are lacking of basic features such as bookmarks or link support.
+Thus this project has started. I thought it could be finished during
+the afternoon at the day of the announcement ...
+
+Goals of the project
+--------------------
+* From the sources a TDS compliant tree is constructed and populated.
+ The zipped result is distributed.
+* All the documentation is generated from the sources. The PDF files
+ are user friendly and provide navigational support with bookmarks
+ and links.
+* The PDF files are post-processed to reduce the file size.
+
+Scope
+-----
+I don't have the time to assemble a TeX distribution with
+thousands of packages. Therefore I restricted myself to the
+LaTeX base distribution and the required bundles.
+In the following I will use the term `module' for a package bundle.
+
+Module list
+-----------
+* base CTAN:macros/latex/base.zip
+* tools CTAN:macros/latex/required/tools.zip
+* cyrillic CTAN:macros/latex/required/cyrillic.zip
+* amslatex CTAN:macros/latex/required/amslatex.zip
+ ftp://ftp.ams.org/pub/tex/amslatex.zip
+ ftp://ftp.ams.org/pub/tex/amsrefs.zip
+* psnfss CTAN:macros/latex/required/psnfss.zip
+* babel CTAN:macros/latex/required/babel.zip
+* tds CTAN:tds.zip
+
+Author
+------
+Heiko Oberdiek <oberdiek at uni-freiburg.de>
+
+
+C. DOWNLOAD
+===========
+
+The home of the project is located at:
+ CTAN:macros/latex/contrib/latex-tds/
+
+The following files can be downloaded:
+* readme.txt (this file)
+* The module distribution files, see the module list above
+ for the available modules, e.g:
+ base.zip
+ tools.zip
+ ...
+* The sources, mainly the build script, configuration and
+ driver files, and patches:
+ source.zip
+ Some of the used tools are not provided, see section
+ `Building Hints'.
+* And the universe, the contents of all the ZIP files above,
+ merged together:
+ latex-tds.zip
+
+It is possible that some or all ZIP archive files are also available
+in the install subtree, then possible locations could be:
+ CTAN:install/macros/latex/base.zip
+ CTAN:install/macros/latex/required/tools.zip
+ ...
+
+
+C. INSTALLATION HINTS
+=====================
+
+Hopefully the result of this project helps you in the installation
+process. You get a TDS compliant tree just by unpacking.
+
+Example:
+ cd /some/where/texmf
+ unzip latex-tds
+or unzip's option `-d':
+ unzip latex-tds -d /some/where/texmf
+
+Instead of the universe ZIP files single modules can be selected.
+
+Important to remember, point your unpack process right in
+the root directory of your TDS tree. The directory structure
+in the ZIP files start with the top-level directories:
+ doc/latex/base/...
+ tex/latex/tools/...
+ source/...
+Rationale: The root directory of a TDS tree can have different
+names, such as texmf-dist, texmf-local, ...
+
+Hints
+-----
+* Refresh the file name database.
+* Be aware that unpacking can insert and update files, but never
+ deletes obsolete ones. Remainders of previous releases can
+ cause trouble.
+* Depending on the module further installation steps can be
+ necessary, consult the module's own documentation.
+
+[base]
+ * The default texsys.cfg that LaTeX provides is put
+ into tex/latex/base. It must be removed, if you need
+ a specialized version. Consult your TeX distribution
+ and doc/latex/base/source2e.pdf (module ltdirchk).
+ Usually changes are not required for many TeX distributions
+ such as Unix (web2c), MikTeX, ...
+ * Formats need rebuilding (e.g., fmtutil).
+[babel]
+ * Most hyphenation patterns aren't provided here. Usually you can
+ find them somewhere below CTAN:language/hyphenation.
+ * Language configuration (language.dat), see the documentation of
+ your TeX distribution.
+ * Formats need rebuilding.
+[psnfss]
+ * The map files need further configuring (e.g., updmap).
+[graphics]
+ * Module graphics doesn't provide all driver files, because some are
+ developed independently (pdftex.def, ...).
+
+
+D. COPYRIGHT, LICENSE
+=====================
+
+Copyright 2006 Heiko Oberdiek.
+
+License is LPPL 1.3c:
+
+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.3c 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 Heiko Oberdiek.
+
+See the following section `Manifest' for a list of all files
+belonging to the project `latex-tds'.
+
+
+E. MANIFEST
+===========
+
+Included are the projects `adjust_checksum' and `ziptimetree'.
+They are projects of their own.
+
+Documentation
+-------------
+ readme.txt this file
+
+Licenses
+--------
+ license/lppl.txt LPPL (The LaTeX Project Public License)
+ for latex-tds and adjust_checksum
+ license/ziptimetree/lgpl.txt LGPL (GNU Lesser General Public License)
+ for ziptimetree
+
+Scripts
+-------
+ build.pl main script for building the distribution
+ lib/adjust_checksum.pl Perl script that runs a DTX file through
+ LaTeX and corrects its \Checksum if necessary
+ lib/ziptimetree.pl Perl script that generates a ZIP file from
+ a directory tree with sorted entries (LGPL)
+
+Configuration
+-------------
+ tex/docstrip.cfg enables TDS feature and creates directories
+ tex/errata.cfg for errata lists of latex/base
+ tex/hyperref.cfg hyperref configuration file
+ tex/ltnews.cfg for LaTeX News of latex/base
+ tex/ltxdoc.cfg setup for class ltxdoc
+ tex/ltxguide.cfg setup for the guide manuals in latex/base
+ and required/psnfss
+ tex/manual.cfg setup for errata list of the LaTeX manual
+ in latex/base
+ tex/tdsguide.cfg setup for class tdsguide.cls
+
+Documentation driver
+--------------------
+ tex/ams.drv generic doc driver for files from the
+ amslatex and babel bundle
+ tex/babel.tex doc driver with patches for babel.drv
+ tex/doc_lppl.tex doc driver for base/lppl.tex
+ tex/greek-usage.tex doc driver with patches for babel/usage.tex
+ tex/ltnews.tex master file that merges all base/ltnews*.tex
+ tex/ltxcheck.drv doc driver with patches for ltxcheck.tex
+ tex/psnfss2e.drv doc driver with patches for psnfss2e.tex
+ tex/tools-overview.cls class for tools.tex
+ tex/tools.tex master file for tools overview, generated
+ by the build.pl script from tools/manifest.txt
+
+Patches
+-------
+ patch/classes.dtx.diff patch for base/classes.dtx
+ patch/albanian.dtx.diff patch for babel/albanian.dtx
+ patch/athnum.dtx.diff patch for babel/athnum.dtx
+ patch/bbcompat.dtx.diff patch for babel/bbcompat.dtx
+ patch/finnish.dtx.diff patch for babel/finnish.dtx
+ patch/frenchb.dtx.diff patch for babel/frenchb.dtx
+ patch/greek.ins.diff patch for babel/greek.ins
+
+
+F. DESIGN PRINCIPLES
+====================
+
+* Compliance with the latest TDS specification.
+* No redundancy.
+* User friendly PDF files with navigational support:
+ * bookmarks
+ * links
+* Complete documentation. The documentation generation with
+ enhanced PDF files is the tricky part and should be saved
+ from the user.
+* Output format of generated documentation is PDF, see above.
+ Other formats such as DVI or PS are not generated and provided.
+* Documentation bundles are preferred to many partial documentation
+ files (e.g. source2e.pdf or ltnews.pdf).
+* If several expansion stages of a documentation are available,
+ then just the most complete expansion stage should be used.
+* Files that do not fit in a program sub tree of TDS stay below
+ TDS:source (e.g. latexbug.el from latex/base). Then they do not
+ get lost at least.
+* Page layout: a4paper with reduced vertical margins (exception: ltnews).
+ (This also decreases the page number usually.)
+* ...
+
+
+G. REMARKS
+==========
+
+Base
+----
+* source2e.pdf is used instead of many single lt*.pdf files.
+* ltnews.pdf is introduced to avoid cluttering the doc directory
+ with many single sheet ltnews*.pdf files.
+* ...
+
+Tools
+-----
+* Added: tools.pdf as overview/contents/index file with links
+ and short descriptions of the single packages. (It uses
+ the data from manifest.txt).
+* ...
+
+AmSLaTeX
+--------
+* The distribution from the AMS ftp site is used, because
+ the files are already sorted in TDS:
+ ftp://ftp.ams.org/pub/tex/amslatex.zip
+ ftp://ftp.ams.org/pub/tex/amsrefs.zip
+* ...
+
+Babel
+-----
+* Babel's TeX files consists of three groups of files:
+ 1. Hyphenation pattern, see below
+ 2. Generic files:
+ *.ldf (language definition files)
+ *.sty (from bbcompat.dtx, these are plain-TeX files,
+ LaTeX user have the package babel)
+ babel.def, switch.def
+ plain.def
+ b*plain.tex
+ esbst.tex
+ 3. LaTeX files:
+ *.fd
+ *enc.def (for package fontenc)
+ cp*.def, 8859-8.def, si960.def (for package inputenc)
+ babel.sty
+ romanidx.tex
+ athnum.sty, grmath.sty, grsymb.sty (greek.ins)
+ heb*.sty
+ Full TDS compliance would use different format subtrees
+ for the generic and LaTeX files. However practice (TeX Live, teTeX,
+ VTeX, ...) put them in `generic', mainly because of maintenance issues.
+ Also babel's *.ins files specify \usedir{tex/generic/babel}.
+ There can be problems, if different TDS trees have different
+ babel versions installed and the same file can be found both
+ in generic and latex. The natural search strategy for TDS compliant
+ trees would be to look first in tex/latex across the trees, then
+ in tex/generic. Thus it can happen to use files from the same
+ package, but different versions.
+ --> Therefore latex-tds put theses files in the generic subtree.
+* Babel already contains babel.pdf as documentation. It is a superset
+ of user.pdf. Thus I have dropped the latter one to avoid redundancy.
+ Also the name `babel.pdf' is much more useful (texdoc).
+* It is unclear, which hyphenation patterns are in the control of babel.
+ Comparing the version of duplicate hyphenation pattern files
+ in CTAN, I decided:
+ * iahyphen.tex -> TDS:tex/generic/hyphen
+ * icehyph.tex -> TDS:tex/generic/hyphen
+ * lahyph.tex -> TDS:source/generic/babel
+ * The Bulgarian patterns are removed, because they form a new CTAN
+ project: CTAN:language/hyphenation/bghyphen
+* It seems, nobody has generated the documentation since a long time.
+ Several patches are necessary for error free compiling.
+* ...
+
+
+H. BUILD HINTS
+==============
+
+The most important advice I can give: `forget it'!
+The purpose of the source files are rather to show, what was
+done in which way.
+The *.zip with TDS trees are the goal of the project, not the
+build process. Some remarks, if someone wants to build the
+modules himself:
+* TeX compiler: recent pdfTeX, below 1.30 some of the packages
+ will not work.
+* An up-to-date LaTeX installation is recommended.
+* Additional packages can be necessary, e.g. I had to install
+ language/armenian, fonts/tipa, fonts/wsuipa, fonts/fc,
+ fonts/utopia, fonts/greek/cbfonts, ...
+ Probably TeX Live would be a good idea (I haven't tested).
+* Some new packages of mine I will put on CTAN, but at time
+ of writing, they aren't available yet.
+* PDF post-processing, I have used two steps:
+ 1. a) I have written a tool that analyzes page stream contents and
+ optimizes them (removal of unnecessary color settings, minimize
+ translation operations, ...).
+ --> pdfbox-rewrite.jar
+ b) For reading and writing the PDF file I have used PDFBox
+ --> PDFBox-0.7.2.jar (http://www.pdfbox.org/)
+ c) To get better results I patched some of the classes
+ of PDFBox (especially the write module).
+ --> pdfbox-rewrite.jar
+ 2. The final conversion step was done by Multivalent, because
+ it makes a very good job in PDF compression:
+ --> Multivalent20060102.jar (http://multivalent.sourceforge.net/)
+ Multivalent and PDFBox are available, pdfbox-rewrite.jar, however,
+ is just a first prototype, not ripe for a release.
+ Therefore this step of post-processing is optional for the
+ project latex-tds. The build script looks for the library and
+ skips this steps automatically if necessary.
+ If you give the build script the option --nopostprocess,
+ then it will skip the postprocess steps (building is faster,
+ the pdf files a little larger).
+ Install the jar files in the directory 'lib' where
+ they are expected by the build script.
+* Unix, Perl background is expected.
+* No support or documentation.
+
+
+I. HISTORY
+==========
+
+2006/04/27
+ * Start of the project (without babel, amslatex, psnfss).
+2006/06/01
+ * Module amslatex added.
+2006/06/03
+ * Modules psnfss and babel added, now all modules are covered.
+2006/06/07
+ * The project uploaded to CTAN.
+2006/07/31
+ * Index added to base/classes.dtx.
+ * ZIP files renamed: '*-tds.zip' -> '*.zip'
+ * Comment added to ZIP files.
+ * Update of readme.txt.
+2006/08/26
+ * Module tds for CTAN:tds/ added.
+ * Obsolete hyphenation patterns added to babel's source directory
+ to avoid violation of LPPL.
+ * Script adjust_checksum added and scripts are put below TDS:scripts.
+ * TDS:makeindex/base/ renamed to TDS:makeindex/latex/
+ * Exception for sample2e.tex and small2e.tex that now go into
+ TDS:tex/latex/base/.
+2006/08/28
+ * Default texsys.cfg is generated.
+ * adjust_checksum.pl and ziptimetree.pl now moved from the scripts
+ branch to TDS:source/latex/latex-tds/lib/.