[latex3-commits] [git/LaTeX3-latex3-latex2e] develop: Standardise README files (88cf7e54)
Joseph Wright
joseph.wright at morningstar2.co.uk
Wed Jul 10 22:50:43 CEST 2019
Repository : https://github.com/latex3/latex2e
On branch : develop
Link : https://github.com/latex3/latex2e/commit/88cf7e54959d25ca19acbf6e65cd3b87e092bfb5
>---------------------------------------------------------------
commit 88cf7e54959d25ca19acbf6e65cd3b87e092bfb5
Author: Joseph Wright <joseph.wright at morningstar2.co.uk>
Date: Wed Jul 10 21:50:43 2019 +0100
Standardise README files
To be reviewed by the real 2e people!
>---------------------------------------------------------------
88cf7e54959d25ca19acbf6e65cd3b87e092bfb5
README.md | 2 +-
base/README.md | 96 ++++++++++++++++++++++++++++++
doc/README-doc.md | 22 +++++++
required/amsmath/README.md | 92 +++++++++++------------------
required/graphics/README.md | 139 +++++++++-----------------------------------
required/tools/README.md | 82 ++++++++------------------
required/tools/README.txt | 97 -------------------------------
7 files changed, 206 insertions(+), 324 deletions(-)
diff --git a/README.md b/README.md
index c61ca308..f0f0af80 100644
--- a/README.md
+++ b/README.md
@@ -72,4 +72,4 @@ The LaTeX kernel is developed by [The LaTeX3 Project](https://latex-project.org)
## Copyright
-This README file is copyright 2019 The LaTeX3 Project.
+This README file is copyright 2019 The LaTeX Project.
diff --git a/base/README.md b/base/README.md
new file mode 100644
index 00000000..4970f052
--- /dev/null
+++ b/base/README.md
@@ -0,0 +1,96 @@
+The LaTeX kernel
+================
+
+Release 2019-10-01 pre-release 1
+
+Overview
+--------
+
+This bundle provides the core LaTeX kernel. In addition to this bundle,
+a minimal LaTeX system also needs the files contained in the
+
+- LaTeX team documentation (`doc`)
+- Packages which must be available (`required`). These are
+ - Essential tools (`tools`)
+ - Core graphics and color support (`graphics`)
+ - Key mathematics support (`amsmath`)
+
+This file contains a small set of pointers to other more complete
+documentation on installing and using a LaTeX system.
+
+Documentation
+-------------
+
+Full documentation of the LaTeX system is provided by
+
+- _LaTeX: A Document Preparation System_; Lamport, Addison-Wesley
+- _The LaTeX Companion_, 2ed; Mittelbach and Goossens with Braams, Carlisle
+ and Rowley, Addison-Wesley
+- _Guide to LaTeX_, 4ed; Kopka and Daly, Addison-Wesley
+
+The distribution is described in files ending `.txt` or `.md`; briefly,
+the most significant of these files are
+
+- `README.md` is this file
+- `manifest.txt` lists all the files in this LaTeX distribution,
+ with one line of information about the contents
+- `unpacked.txt` lists all the files in the unpacked LaTeX distribution
+- `legal.txt` and `lppl.txt` (LaTeX Project Public License) describe the
+ LaTeX copyright, warranty and copying restrictions.
+- `patches.txt` describes the how important changes will be distributed
+ between releases
+- `texpert.txt` contains information about the system that may still be
+ useful for TeX experts
+- `tex2.txt` contains important information for users of extremely
+ old versions of TeX (pre 1990)
+- `autoload.txt` describes a variant of LaTeX that is no longer supported
+- `bugs.txt` describes how to submit a bug report for LaTeX
+
+Other documentation files include files with names of the form:
+
+ <xxx>guide.tex
+
+You will probably need to update your system before you can typeset
+these files. Each file needs three LaTeX runs. Some of these are
+also available as PDF files on [CTAN](https://www.ctan.org).
+
+The following files contain further information:
+
+- `ltx3info.tex` gives you some historical information about the LaTeX3
+ project
+- `manual.err` lists errata in _LaTeX: A Document Preparation System_ (Lamport)
+- `tlc2.err` lists errata in _The LaTeX Companion_ (Mittelbach et al.)
+
+The files `ltnews*.tex` (part of the `doc` bundle) contain the LaTeX
+newsletters, the highest number being the most recent.
+
+For historical reasons, the base distribution and the core documentation
+are bundled separately. Documentation is found in the `doc` bundle. In an
+installed TeX system, `base` and `doc` should be placed within the same
+location; the distinction is therefore primarily of importance when looking
+at the development code.
+
+Installation
+------------
+
+We no longer distribute installation instructions for the various TeX
+implementations. All modern TeX systems include LaTeX as-standard, and end
+users should in general use the release versions supplied in this way.
+
+Release distribution is carried out only through the CTAN archives.
+
+Requirements
+------------
+
+The LaTeX kernel requires the e-TeX extensions to TeX, which were finalised
+in the late 1990s and are available in modern TeX-derived engines. Some new
+features require `\ifincsname`, which is currently available in release
+versions of pdfTeX, XeTeX and LuaTeX, and is being introduced shortly in
+e-pTeX and e-upTeX.
+
+-----
+
+<p>Copyright (C) 1989-2019 The LaTeX3 Project <br />
+<a href="http://latex-project.org/">http://latex-project.org/</a> <br />
+All rights reserved.</p>
+
diff --git a/doc/README-doc.md b/doc/README-doc.md
new file mode 100644
index 00000000..3ab4384c
--- /dev/null
+++ b/doc/README-doc.md
@@ -0,0 +1,22 @@
+Documentation for the LaTeX kernel
+==================================
+
+Release 2019-10-01 pre-release 1
+
+Overview
+--------
+
+This bundle provides the core documentation supporting the LaTeX kernel.
+
+For historical reasons, the base distribution and the core documentation
+are bundled separately. Documentation is found in the `doc` bundle. In an
+installed TeX system, `base` and `doc` should be placed within the same
+location; the distinction is therefore primarily of importance when looking
+at the development code.
+
+-----
+
+<p>Copyright (C) 2019 The LaTeX3 Project <br />
+<a href="http://latex-project.org/">http://latex-project.org/</a> <br />
+All rights reserved.</p>
+
diff --git a/required/amsmath/README.md b/required/amsmath/README.md
index 9b2de985..8c4c9b6d 100644
--- a/required/amsmath/README.md
+++ b/required/amsmath/README.md
@@ -1,71 +1,61 @@
-## README for latex-amsmath bundle
+The amsmath bundle for LaTeX
+============================
+Release 2019-10-01 pre-release 1
-### OVERVIEW
+Overview
+--------
-The amsmath package is an extension package for LaTeX that provides
+The `amsmath` package is an extension package for LaTeX that provides
additional features to facilitate mathematical typesetting. It has been
-developed by the American Mathematical Society and released for general
+developed by the American Mathematical Society (AMS) and released for general
use as a service to the mathematical community. A number of smaller
-auxiliary packages are also distributed with the amsmath package.
+auxiliary packages are also distributed with the `amsmath` package.
-Effective in 2016, maintenance of amsmath was transferred from AMS to
-the LaTeX3 Project; as amsmath is considered a "required" package, this
+Effective in 2016, maintenance of `amsmath was transferred from AMS to
+the LaTeX Project; as `amsmath` is considered a "required" package, this
centralizes control over the core LaTeX components.
+Installation
+------------
-### INSTALLATION AND GETTING STARTED
+We no longer distribute installation instructions for the various TeX
+implementations. All modern TeX systems include `amsmath` as-standard, and end
+users should in general use the release versions supplied in this way.
-In order to use amsmath you need to have TeX installed first.
-For information on getting TeX see one of the following:
+Release distribution is carried out only through the CTAN archives.
- - [LaTeX Project Website](https://www.latex-project.org/)
- - [TeX User Group](https://www.tug.org/)
- - [TeX resources (AMS infos for authors)](https://www.ams.org/tex/tex-resources)
+Documentation
+-------------
-It is recommended to install a comprehensive distribution, such as
-TeX Live, MiKTeX for Windows, or MacTeX for Macintosh.
-As part of the "required" LaTeX package subset, amsmath
-will already be available if one of these distributions is chosen.
-
-If you are installing amsmath manually, the most recent version
-will be available from the CTAN archives
-https://www.ctan.org/pkg/amsmath
-
-
-The primary documentation for amsmath is in
-
- - amsldoc.pdf
+The primary documentation for `amsmath` is in provided as `amsldoc.pdf`.
Additional documentation files include:
- - diffs-m.txt
- - subeqn.pdf
- - technote.pdf
- - testmath.pdf
+ - `diffs-m.txt`
+ - `subeqn.pdf`
+ - `technote.pdf`
+ - `testmath.pdf`
which are included in the collection. All of these can be accessed
easily with most distributions by entering `texdoc` *filename* at the
command line, or via [TeXdoc Online](http://texdoc.net).
-
-
-
-### CHANGE LOG
+Change logs
+-----------
The file `changes.txt` lists recent changes in reverse chronological order.
The file `diffs-m.txt` contains information on development and changes
prior to 2000.
+Reporting Bugs
+--------------
-### Reporting Bugs
-
-If you wish to report a problem or bug in any of these packages
-please use the
-[Issue Tracker for LaTeX2e on GitHub](https://github.com/latex3/latex2e/issues)
-and follow the guidelines that pop up if you press the `New issue` button.
-
+If you wish to report a problem or bug in the `amsmath` bundle
+please use the [Issue Tracker for LaTeX2e on
+GitHub](https://github.com/latex3/latex2e/issues)
+and follow the guidelines that pop up if you press the "New issue" button.
In particular, to check that you are really seeing a bug, please write
a short, self-contained document that shows the problem. This should
@@ -77,22 +67,8 @@ for further details, or if you need to obtain the `latexbug` package.
If the bug turns out to be with third-party software then please
contact the developer, and not us!
+-----
-### Copyright
-
-Copyright 2001-2004, 2007, 2008, 2010, 2011, 2013 American Mathematical Society.
-Copyright 2016-2018 LaTeX3 Project and American Mathematical Society.
-
-This work may be distributed and/or modified under the
-conditions of the LaTeX Project Public License, either version 1.3c
-of this license or (at your option) any later version.
-The latest version of this license is in
- https://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 the LaTeX3 Project.
+<p>Copyright (C) 2001-2004, 2007, 2008, 2010, 2011, 2013 American Mathematical Society. <br />
+<p>Copyright (C) 2016-2018 The LaTeX Project and American Mathematical Society. <br />
-This README file is copyright 2016-2018 The LaTeX3 Project.
diff --git a/required/graphics/README.md b/required/graphics/README.md
index 54dbc108..12e1de65 100644
--- a/required/graphics/README.md
+++ b/required/graphics/README.md
@@ -1,118 +1,40 @@
-## README for the Standard LaTeX `Graphics` bundle
+The LaTeX `graphics` bundle
+===========================
-This bundle consists of LaTeX2e packages written and supported by
-members of the LaTeX3 Project Team.
+Release 2019-10-01 pre-release 1
-It is a collection of LaTeX packages for:
-- producing colour
-- including graphics (eg PostScript) files
-- rotation and scaling of text
-in LaTeX documents.
+Overview
+--------
+This bundle consists of packages supporting basic color, graphics and text
+manipulation operations in LaTeX. The packages provided here are
+- `color`: Core color support
+- `graphics`: The original LaTeX graphics inclusion interface
+- `graphicx`: Extended interface for graphics inclusion
+- `lscape`: Production of landscape pages
+- `keyval`: Core key-value support for LaTeX
+- `rotating`: Support for rotating material
+- `trig`: Support for fast trigonometric calculations in TeX
-### THIS DIRECTORY CONTAINS
+plus the legacy stub `epsfig` (now subsumed into `graphics`).
-#### Support files
+Installation
+------------
-| File | Notes |
-| --- | --- |
-| README.md | This file |
-| changes.txt | Log of changes to the packages |
-| graphics.ins | Install file for docstrip |
+We no longer distribute installation instructions for the various TeX
+implementations. All modern TeX systems include `graphics` as-standard, and end
+users should in general use the release versions supplied in this way.
-#### Basic packages
+Release distribution is carried out only through the CTAN archives.
-| File | Notes |
-| --- | --- |
-| color.dtx | Source for color package |
-| graphics.dtx | Source for graphics package |
-| trig.dtx | Source for trig package (required by graphics) |
-
-#### Extension Packages
-
-| File | Notes |
-| --- | --- |
-| graphicx.dtx | Source for graphicx package (extension of graphics) |
-| epsfig.dtx | Source for epsfig package (extension of graphicx). |
-| rotating.dtx | Source for rotating package (extension of graphicx). |
-| keyval.dtx | Source for keyval pacakge (required by both the above) |
-| lscape.sty | Produce landscape pages in a (mainly) portrait document |
-
-#### Driver Files
-
-| File | Notes |
-| --- | --- |
-| drivers.dtx | Source for driver files for supported drivers |
-
-#### User Documentation
-
-| File | Notes |
-| --- | --- |
-| grfguide.tex | User Guide to all the packages in this bundle |
-| | **WARNING:** *This file calls color and graphics packages without a driver option. You **must** therefore set up two files `color.cfg` and `graphics.cfg` containing (for example) `\ExecuteOptions{dvips}` before running this file.* |
-| rotex.tex | Examples of use of rotating package |
-
-
-
-### TO UNPACK THE PACKAGES
-
- latex graphics.ins
-
-This will produce the `.sty` package files.
-
-Similarly you can run
-
- latex graphics-drivers.ins
-
-to produce the `.def` driver files.
-
-Not all supported drivers are included in this file as they are
-maintained elsewhere.
-
-
-### USING THE PACKAGES
-
-Move files ending in `.sty` or `.def` to a standard TeX input directory.
-
-Make a default option for your site by creating two files `color.cfg` and `graphics.cfg`
-containing (if dvips is your default driver)
- \ExecuteOptions{dvips}
-
-You may then LaTeX the user guide by running:
-
- latex grfguide.tex
-
-
-
-### Copyright
-
-Copyright is maintained on each of these packages by the author(s)
-of the package.
-
-
-### Distribution Conditions
-
-All the files in this bundle may be distributed under the conditions
-of the LaTeX Project Public License, either version 1.3c of this
-license or (at your option) any later version. The latest version of
-this license is in
- https://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.
-
-The list of all files belonging to this bundle is listed above.
-
-The use of these files is otherwise unrestricted.
-
-
-### Reporting Bugs
-
-If you wish to report a problem or bug in any of these packages
-please use the
-[Issue Tracker for LaTeX2e on GitHub](https://github.com/latex3/latex2e/issues)
-and follow the guidelines that pop up if you press the `New issue` button.
+Reporting Bugs
+--------------
+If you wish to report a problem or bug in the `graphics` bundle
+please use the [Issue Tracker for LaTeX2e on
+GitHub](https://github.com/latex3/latex2e/issues)
+and follow the guidelines that pop up if you press the "New issue" button.
In particular, to check that you are really seeing a bug, please write
a short, self-contained document that shows the problem. This should
@@ -124,9 +46,6 @@ for further details, or if you need to obtain the `latexbug` package.
If the bug turns out to be with third-party software then please
contact the developer, and not us!
+-----
-
-### Copyright
-
-This README file is copyright 1993-2017 The LaTeX3 Project.
-
+<p>Copyright (C) 1993-2019 The LaTeX Project <br />
diff --git a/required/tools/README.md b/required/tools/README.md
index cbd8f80e..9322f3f6 100644
--- a/required/tools/README.md
+++ b/required/tools/README.md
@@ -1,67 +1,30 @@
-## README for the `tools` bundle
+The LaTeX `tools` bundle
+===========================
+Release 2019-10-01 pre-release 1
-This bundle consists of LaTeX2e packages written and supported by
-members of the LaTeX3 Project Team.
+Overview
+--------
-The documented source code of each package is in a file with extension
-`.dtx`. Running LaTeX on the file `tools.ins` will produce all the
-package files, and some associated files.
+This bundle consists of packages providing a range of basic tools for
+LaTeX users. It is a required part of a LaTeX installation.
-So you should first process `tools.ins`:
+Installation
+------------
- latex tools.ins
+We no longer distribute installation instructions for the various TeX
+implementations. All modern TeX systems include `graphics` as-standard, and end
+users should in general use the release versions supplied in this way.
-The files with extensions `.sty` and `.tex` (including a file whose
-name is just `.tex`) should then be moved to a directory on LaTeX's
-standard input path.
+Release distribution is carried out only through the CTAN archives.
-Documentation for the individual packages may then be obtained by
-running LaTeX on the `.dtx` files.
-
-For example:
-
- latex array.dtx
-
-will produce the file `array.pdf`, documenting the array package.
-
-
-The file `manifest.txt` contains a list of the main files in the
-distribution together with a one-or-two line summary of each package.
-
-
-### Copyright
-
-Copyright is maintained on each of these packages by the author(s)
-of the package.
-
-
-### Distribution Conditions
-
-All the files in this bundle may be distributed under the conditions
-of the LaTeX Project Public License, either version 1.3c of this
-license or (at your option) any later version. The latest version of
-this license is in
- https://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.
-
-The list of all files belonging to the Tools Bundle is
-given in the file `manifest.txt`.
-
-Commercial users of the `multicol` package are asked to read the
-notice at the head of the file multicol.dtx.
-
-The use of these files is otherwise unrestricted.
-
-
-### Reporting Bugs
-
-If you wish to report a problem or bug in any of these packages
-please use the
-[Issue Tracker for LaTeX2e on GitHub](https://github.com/latex3/latex2e/issues)
-and follow the guidelines that pop up if you press the `New issue` button.
+Reporting Bugs
+--------------
+If you wish to report a problem or bug in the `tools` bundle
+please use the [Issue Tracker for LaTeX2e on
+GitHub](https://github.com/latex3/latex2e/issues)
+and follow the guidelines that pop up if you press the "New issue" button.
In particular, to check that you are really seeing a bug, please write
a short, self-contained document that shows the problem. This should
@@ -73,9 +36,12 @@ for further details, or if you need to obtain the `latexbug` package.
If the bug turns out to be with third-party software then please
contact the developer, and not us!
+-----
+
+<p>Copyright (C) 1993-2019 The LaTeX Project <br />
+
+
-### Copyright
-This README file is copyright 1993-2017 The LaTeX3 Project.
diff --git a/required/tools/README.txt b/required/tools/README.txt
deleted file mode 100644
index 1020fac5..00000000
--- a/required/tools/README.txt
+++ /dev/null
@@ -1,97 +0,0 @@
-
-%
-% Copyright 1993-2017
-% The LaTeX3 Project and any individual authors listed elsewhere
-% in this file.
-%
-% This file is part of the Standard LaTeX `Tools Bundle'.
-% -------------------------------------------------------
-%
-% It may be distributed and/or modified under the
-% conditions of the LaTeX Project Public License, either version 1.3c
-% of this license or (at your option) any later version.
-% The latest version of this license is in
-% https://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.
-%
-% The list of all files belonging to the LaTeX `Tools Bundle' is
-% given in the file `manifest.txt'.
-%
-
-
-README for the `tools' bundle
-=============================
-
-This `bundle' consists of LaTeX2e packages written and supported by
-members of the LaTeX3 Project Team.
-
-The documented source code of each package is in a file with extension
-`.dtx'. Running LaTeX on the file tools.ins will produce all the
-package files, and some associated files.
-
-So you should first process tools.ins:
-
- latex tools.ins
-
-The files with extensions `.sty' and `.tex' (including a file whose
-name is just `.tex') should then be moved to a directory on LaTeX's
-standard input path.
-
-See the Note at the end of this file if you have problems processing
-the tools.ins file.
-
-Documentation for the individual packages may then be obtained by
-running LaTeX on the `.dtx' files.
-
-For example:
-
- latex array.dtx
-
-will produce the file array.dvi, documenting the array package.
-
-
-The file manifest.txt contains a list of the main files in the
-distribution together with a one-or-two line summary of each package.
-
-
-Copyright
-=========
-Copyright is maintained on each of these packages by the author(s)
-of the package.
-
-
-Distribution Conditions
-=======================
-
-All the files in this bundle may be distributed under the conditions
-of the LaTeX Project Public License, either version 1.1 of this
-license or (at your option) any later version. The latest version of
-this license is in
- https://www.latex-project.org/lppl.txt
-and version 1.1 or later is part of all distributions of LaTeX
-version 1999/06/01 or later.
-
-The list of all files belonging to the `Tools Bundle' is
-given in the file `manifest.txt'.
-
-Commercial users of the multicol package are asked to read the
-notice at the head of the file multicol.dtx.
-
-The use of these files is otherwise unrestricted.
-
-
-Reporting Bugs
-==============
-
-If you wish to report a problem or bug in any of these packages, use
-the latexbug.tex program that comes with the standard LaTeX
-distribution. Please ensure that you enter `tools' category when
-prompted with a menu of categories, so that the message will be
-automatically forwarded to the appropriate part of our database.
-
-When reporting bugs, please produce a small test file that shows the
-problem, and ensure that you are using the current version of the
-package, and of the base LaTeX software.
-
-
More information about the latex3-commits
mailing list