From e0c6872cf40896c7be36b11dcc744620f10adf1d Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Mon, 2 Sep 2019 13:46:59 +0900 Subject: Initial commit --- macros/latex-dev/doc/README-doc.md | 29 + macros/latex-dev/doc/README.md | 1 + macros/latex-dev/doc/cfgguide.pdf | Bin 0 -> 219621 bytes macros/latex-dev/doc/cfgguide.tex | 561 ++++++++++ macros/latex-dev/doc/changes-doc.txt | 32 + macros/latex-dev/doc/clsguide.pdf | Bin 0 -> 371876 bytes macros/latex-dev/doc/clsguide.tex | 1874 ++++++++++++++++++++++++++++++++ macros/latex-dev/doc/cyrguide.pdf | Bin 0 -> 223453 bytes macros/latex-dev/doc/cyrguide.tex | 398 +++++++ macros/latex-dev/doc/encguide.pdf | Bin 0 -> 1244414 bytes macros/latex-dev/doc/encguide.tex | 1481 +++++++++++++++++++++++++ macros/latex-dev/doc/fntguide.pdf | Bin 0 -> 356631 bytes macros/latex-dev/doc/fntguide.tex | 1907 +++++++++++++++++++++++++++++++++ macros/latex-dev/doc/latexchanges.pdf | Bin 0 -> 385193 bytes macros/latex-dev/doc/latexchanges.tex | 756 +++++++++++++ macros/latex-dev/doc/ltnews.pdf | Bin 0 -> 831633 bytes macros/latex-dev/doc/ltnews.tex | 276 +++++ macros/latex-dev/doc/ltnews01.tex | 152 +++ macros/latex-dev/doc/ltnews02.tex | 154 +++ macros/latex-dev/doc/ltnews03.tex | 145 +++ macros/latex-dev/doc/ltnews04.tex | 143 +++ macros/latex-dev/doc/ltnews05.tex | 158 +++ macros/latex-dev/doc/ltnews06.tex | 149 +++ macros/latex-dev/doc/ltnews07.tex | 146 +++ macros/latex-dev/doc/ltnews08.tex | 154 +++ macros/latex-dev/doc/ltnews09.tex | 142 +++ macros/latex-dev/doc/ltnews10.tex | 153 +++ macros/latex-dev/doc/ltnews11.tex | 141 +++ macros/latex-dev/doc/ltnews12.tex | 154 +++ macros/latex-dev/doc/ltnews13.tex | 201 ++++ macros/latex-dev/doc/ltnews14.tex | 169 +++ macros/latex-dev/doc/ltnews15.tex | 169 +++ macros/latex-dev/doc/ltnews16.tex | 161 +++ macros/latex-dev/doc/ltnews17.tex | 230 ++++ macros/latex-dev/doc/ltnews18.tex | 51 + macros/latex-dev/doc/ltnews19.tex | 116 ++ macros/latex-dev/doc/ltnews20.tex | 153 +++ macros/latex-dev/doc/ltnews21.tex | 255 +++++ macros/latex-dev/doc/ltnews22.tex | 244 +++++ macros/latex-dev/doc/ltnews23.tex | 257 +++++ macros/latex-dev/doc/ltnews24.tex | 263 +++++ macros/latex-dev/doc/ltnews25.tex | 137 +++ macros/latex-dev/doc/ltnews26.tex | 239 +++++ macros/latex-dev/doc/ltnews27.tex | 135 +++ macros/latex-dev/doc/ltnews28.tex | 365 +++++++ macros/latex-dev/doc/ltnews29.tex | 526 +++++++++ macros/latex-dev/doc/ltnews30.tex | 297 +++++ macros/latex-dev/doc/ltx3info.pdf | Bin 0 -> 197812 bytes macros/latex-dev/doc/ltx3info.tex | 474 ++++++++ macros/latex-dev/doc/modguide.pdf | Bin 0 -> 226660 bytes macros/latex-dev/doc/modguide.tex | 412 +++++++ macros/latex-dev/doc/usrguide.pdf | Bin 0 -> 396659 bytes macros/latex-dev/doc/usrguide.tex | 1817 +++++++++++++++++++++++++++++++ 53 files changed, 15777 insertions(+) create mode 100644 macros/latex-dev/doc/README-doc.md create mode 120000 macros/latex-dev/doc/README.md create mode 100644 macros/latex-dev/doc/cfgguide.pdf create mode 100644 macros/latex-dev/doc/cfgguide.tex create mode 100644 macros/latex-dev/doc/changes-doc.txt create mode 100644 macros/latex-dev/doc/clsguide.pdf create mode 100644 macros/latex-dev/doc/clsguide.tex create mode 100644 macros/latex-dev/doc/cyrguide.pdf create mode 100644 macros/latex-dev/doc/cyrguide.tex create mode 100644 macros/latex-dev/doc/encguide.pdf create mode 100644 macros/latex-dev/doc/encguide.tex create mode 100644 macros/latex-dev/doc/fntguide.pdf create mode 100644 macros/latex-dev/doc/fntguide.tex create mode 100644 macros/latex-dev/doc/latexchanges.pdf create mode 100644 macros/latex-dev/doc/latexchanges.tex create mode 100644 macros/latex-dev/doc/ltnews.pdf create mode 100644 macros/latex-dev/doc/ltnews.tex create mode 100644 macros/latex-dev/doc/ltnews01.tex create mode 100644 macros/latex-dev/doc/ltnews02.tex create mode 100644 macros/latex-dev/doc/ltnews03.tex create mode 100644 macros/latex-dev/doc/ltnews04.tex create mode 100644 macros/latex-dev/doc/ltnews05.tex create mode 100644 macros/latex-dev/doc/ltnews06.tex create mode 100644 macros/latex-dev/doc/ltnews07.tex create mode 100644 macros/latex-dev/doc/ltnews08.tex create mode 100644 macros/latex-dev/doc/ltnews09.tex create mode 100644 macros/latex-dev/doc/ltnews10.tex create mode 100644 macros/latex-dev/doc/ltnews11.tex create mode 100644 macros/latex-dev/doc/ltnews12.tex create mode 100644 macros/latex-dev/doc/ltnews13.tex create mode 100644 macros/latex-dev/doc/ltnews14.tex create mode 100644 macros/latex-dev/doc/ltnews15.tex create mode 100644 macros/latex-dev/doc/ltnews16.tex create mode 100644 macros/latex-dev/doc/ltnews17.tex create mode 100644 macros/latex-dev/doc/ltnews18.tex create mode 100644 macros/latex-dev/doc/ltnews19.tex create mode 100644 macros/latex-dev/doc/ltnews20.tex create mode 100644 macros/latex-dev/doc/ltnews21.tex create mode 100644 macros/latex-dev/doc/ltnews22.tex create mode 100644 macros/latex-dev/doc/ltnews23.tex create mode 100644 macros/latex-dev/doc/ltnews24.tex create mode 100644 macros/latex-dev/doc/ltnews25.tex create mode 100644 macros/latex-dev/doc/ltnews26.tex create mode 100644 macros/latex-dev/doc/ltnews27.tex create mode 100644 macros/latex-dev/doc/ltnews28.tex create mode 100644 macros/latex-dev/doc/ltnews29.tex create mode 100644 macros/latex-dev/doc/ltnews30.tex create mode 100644 macros/latex-dev/doc/ltx3info.pdf create mode 100644 macros/latex-dev/doc/ltx3info.tex create mode 100644 macros/latex-dev/doc/modguide.pdf create mode 100644 macros/latex-dev/doc/modguide.tex create mode 100644 macros/latex-dev/doc/usrguide.pdf create mode 100644 macros/latex-dev/doc/usrguide.tex (limited to 'macros/latex-dev/doc') diff --git a/macros/latex-dev/doc/README-doc.md b/macros/latex-dev/doc/README-doc.md new file mode 100644 index 0000000000..aaf48be918 --- /dev/null +++ b/macros/latex-dev/doc/README-doc.md @@ -0,0 +1,29 @@ +Documentation for the LaTeX kernel +================================== + +Release 2019-10-01 pre-release 2 + +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. + +License +------- + +The contents of this bundle are distributed under the [LaTeX Project +Public License](https://www.latex-project.org/lppl/lppl-1-3c/), +version 1.3c or later. + +----- + +

Copyright (C) 2019 The LaTeX3 Project
+http://latex-project.org/
+All rights reserved.

+ diff --git a/macros/latex-dev/doc/README.md b/macros/latex-dev/doc/README.md new file mode 120000 index 0000000000..564c261ef5 --- /dev/null +++ b/macros/latex-dev/doc/README.md @@ -0,0 +1 @@ +README-doc.md \ No newline at end of file diff --git a/macros/latex-dev/doc/cfgguide.pdf b/macros/latex-dev/doc/cfgguide.pdf new file mode 100644 index 0000000000..9568b6fac1 Binary files /dev/null and b/macros/latex-dev/doc/cfgguide.pdf differ diff --git a/macros/latex-dev/doc/cfgguide.tex b/macros/latex-dev/doc/cfgguide.tex new file mode 100644 index 0000000000..7ac0208ba4 --- /dev/null +++ b/macros/latex-dev/doc/cfgguide.tex @@ -0,0 +1,561 @@ +% \iffalse meta-comment +% +% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 +% The LaTeX3 Project and any individual authors listed elsewhere +% in this file. +% +% This file is part of the LaTeX base system. +% ------------------------------------------- +% +% 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 +% 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 file has the LPPL maintenance status "maintained". +% +% The list of all files belonging to the LaTeX base distribution is +% given in the file `manifest.txt'. See also `legal.txt' for additional +% information. +% +% The list of derived (unpacked) files belonging to the distribution +% and covered by LPPL is defined by the unpacking scripts (with +% extension .ins) which are part of the distribution. +% +% \fi +% Filename: cfgguide.tex + +\NeedsTeXFormat{LaTeX2e}[1995/12/01] + +\documentclass{ltxguide}[1995/11/28] + +\newcommand{\filesection}[1]{\subsection{\sffamily{#1}}} +\newcommand{\iniTeX}{ini\TeX} + +\setcounter{secnumdepth}{0} + +\title{Configuration options for \LaTeXe} + +\author{\copyright~Copyright 1998, 2001, 2003 \LaTeX3 Project Team.\\ + All rights reserved.} + +\date{14 February 2003} + +\begin{document} + +\maketitle + +\tableofcontents + +\newpage + +\section{Configuring \LaTeX} + +Since one of the main aims of the new standard \LaTeX{} is to give all +users the freedom provided by a reliable document processing system +linked to a highly portable document format, the number of +configuration possibilities is strictly limited. The reasons for this +are explained in more detail in the article +\textit{Modifying \LaTeX{}} in the file \texttt{modguide.tex}. +An important consequence of this is that any document that relies on +any extension package must declare this package within the document +file; this helps to ensure that the document will work at a different +site, where the \LaTeX{} system may be configured differently. + +Local configuration options are, by convention, placed in +`configuration files', which have extension |.cfg|. This document +describes the possibilities for configuration in this release of +\LaTeX; it also explains how to configure the font definition files to +take advantage of the available fonts. + +The last section considers briefly how to proceed if you require +further customisation of the formatter. + + +\section{System configuration} + +\filesection{texsys.cfg} + +This is the only configuration file that \emph{must} be present. +During installation, if \LaTeX\ cannot find a file with this name +then a default file |texsys.cfg|, consisting entirely of comments, is +written out and used. Note that, until this file has been read, +\LaTeX{} is not able to test reliably whether a given file exists on +the system. + +The contents of the file |texsys.cfg| allow \LaTeX{} to cope with +various differences between the behaviours of different \TeX{} systems, +mainly in relation to file handling. The default version of this file +contains, in its comments, possible settings that may be needed for a +range of \TeX{} systems. For more information, typeset the file +|ltdirchk.dtx|. + +If you have copied your \LaTeX{} installation from a computer that +used a different operating system then you may well have a version of +|texsys.cfg| that will make it difficult to install \LaTeX{} on your +system. If this happens then start the process again with an empty +|texsys.cfg| file; this will produce an installation that should, at +least, allow you to typeset the documentation. However, it is +possible that \LaTeX{} can still find only those files that are in the +current directory; in this case you must set the macro |\input@path| +correctly for your system. + + +\section{Configuring the \LaTeX\ format} + +There are four configuration files that enable personal preferences to +be incorporated into the \LaTeX{} format file |latex.fmt|. The range +of preferences that can be configured by these files is strictly +limited as this helps to ensure document portability. + +All four files work in the same way: if the file \m{file}|.cfg| is +found, it will be input by \iniTeX; otherwise a default file +\m{file}|.ltx| will be input; this is sometimes done via a +minimal \m{file}|.cfg| that simply inputs \m{file}|.ltx|. Thus, +providing your own version of any of these |.cfg| files can completely +override any settings in the corresponding default standard |.ltx| +file. + + +\subsection{Font configuration} + +Before you even think about configuring the font declarations by +producing a file |fontmath.cfg| or |fonttext.cfg|, you should +read the documented file |fontdef.dtx|. This is the source file from +which the default files |fonttext.ltx| and |fontmath.ltx| are +produced; it contains information concerning the +contents of the default files and what sort of customisation is +possible. In particular, it describes in detail the effects of +individual customisations on document portability including: which +customisations can be made without endangering the ability to exchange +documents with other sites (even if the formatting differs); and which +things should be left untouched because they will make your system so +different from others that the documents it produces will be +non-portable. + +\textbf{WARNING } Please note that use of either of these font +configuration files has the following consequences. + \begin{itemize} + \item Since the content of the file |fontdef.dtx| \emph{might} + change in the future, anyone writing a font configuration file + must be prepared to update it for use with future releases. + \item Documents produced on your system are likely, at best, to be + portable only in the sense of being processable at a different + site---the actual formatting will not be the same if different + fonts are used. + \item The \LaTeX3 project team will not be able to support you in + diagnosing problems if these cannot be reproduced with a format + that does not use any configuration files. + \end{itemize} + +\filesection{fonttext.cfg} + +The file |fonttext.cfg| can contain declarations relating to the use +of fonts in text modes. + +If it exists, it defines which font shapes, families and encodings are +normally used in text mode, as well as the behavior of font attribute +commands such as |\textbf| etc. + +It could be used, for example, to produce a \LaTeX\ format that, by +default, typesets documents using Times fonts. Be warned, however, +that such customisation can have unfortunate consequences; so please +read carefully this section and the file |fontdef.dtx| below if you +are thinking of doing this. + +Please note carefully the above \textbf{warning}. + +\filesection{fontmath.cfg} + +The file |fontmath.cfg| can contain declarations relating to the use +of fonts in math mode. + +If it exists, it defines which fonts in which sizes are used in math +mode, and how they are used. It also defines all the math mode +commands that `are likely to' depend on the choice of math fonts used +(e.g.~commands that depend on the position of a glyph in a math font). + +The main reason for the existence of this file is to provide for future +updates when a standard math font encoding is available. Right now we +do \emph{not} encourage the use of this configuration file other than +for special applications. Writing a proper configuration file for math +mode needs expert knowledge! + +Please note carefully the above \textbf{warning}. + +\filesection{preload.cfg} + +The contents of the file |preload.cfg| can control the preloading of +commonly used fonts. Preloading fonts speeds up the processing of +documents but, because fonts cannot be `unloaded', you should not +preload too many; otherwise you may be unable to process documents +requiring unusual font families. + +The default file |preload.ltx| is produced from |preload.dtx|. It +loads only a few fonts and these are a good choice if you normally use +documents at the default, 10\,pt, size. If you normally use 11\,pt +or~12\,pt then the time for \LaTeX\ to startup may be noticeably +decreased if you preload the corresponding fonts for the sizes you +use. Similarly, if you normally use a different font family, for +example Times Roman (|ptm|) then you may want to preload fonts in this +family rather than the default Computer Modern fonts. + +\subsection{Hyphenation configuration} + +\filesection{hyphen.cfg} + +In order to hyphenate text, \TeX{} must have hyphenation patterns and, +since these patterns can be loaded only by \iniTeX, the choice of +which patterns to load must be made when the format is created. + +The hyphenation patterns for American English are stored in the file +named |hyphen.tex|; \LaTeX~2.09 always loaded this file when its +format was made. + +With \LaTeXe{} it is possible to configure which hyphenation patterns +are to be loaded into the format. When \iniTeX{} is processing +|latex.ltx|, it looks for a file called |hyphen.cfg|; this file can +be used to control which hyphenation patterns are loaded. If a file +|hyphen.cfg| cannot be found then \iniTeX{} will load the file +|hyphen.ltx|. + +The file |hyphen.ltx| loads the file |hyphen.tex| if it can find it; +otherwise it stops with an error since a format with no hyphenation +patterns is not very useful. It then sets |\language=0| and it sets +the values |\lefthyphenmin=2| and |\righthyphenmin=3|, which are +needed for American English. + +Thus, if you want any other patterns to be loaded then you should +create a file |hyphen.cfg|. For each language for which you wish to +load hyphenation patterns this file should: +\begin{itemize} +\item set |\language=|\m{number}; +\item load the file which contains the hyphenation patterns for that + language. +\end{itemize} +If the patterns you use require some definitions or assignments then +a group should be used to keep such changes local to their file. + +\textbf{Note.} The hyphenation files that are read in should \emph{only} +set the hyphenation tables for the language, using the commands +|\hyphenation| and |\patterns|. In particular they should make no +assignments to the lowercase/uppercase tables (|\lccode| and +|\uccode|) and should not make any global command definitions to be +used after the file has been read. Unfortunately some older +hyphenation files do contain such settings; thus they are +\emph{incompatible} with the mechanisms \LaTeX\ uses to ensure +independence of input and output encodings. + +After this the file |hyphen.cfg| should: +\begin{itemize} +\item set |\language| to its default value; +\item set |\lefthyphenmin| and |\righthyphenmin| to the correct values + for this default language. +\end{itemize} + +There are packages available, such as `french', that can help you with +this configuration. The `babel' collection contains many examples of +setting up a multi-lingual \LaTeX{} format. The documentation in +|lthyphen.dtx| (the source file for |hyphen.ltx|) also contains some +useful examples. + +[We intend in a future release of \LaTeX{} to provide a set of +standard commands for use in configuring hyphenation.] + + +\section{Configuring the font definition files} + +If you have special fonts available (or if some fonts are unavailable) +at your site then you may need to produce customised versions of the +font definition files; these have extension \texttt{.fd} and are read +by \LaTeX{} to obtain information about the font files installed at your +system and when to load them. + +Although we do not encourage such customisation, you will find +information about the content of these files and its syntax in the +documented source file \texttt{cmfonts.fdd} and +\textit{\LaTeXe{} font selection} in the file \texttt{fntguide.tex}. +[We hope to be able to provide further information and examples on +this subject at some time in the future.] + +Please note that the use of customised font definition files has the +following consequences. + \begin{itemize} + \item Documents produced on your system will, at best, to be + portable only in the sense of being processable at a different + site---the actual formatting will not be the same if different + fonts are used. + \item The \LaTeX3 project team will not be able to support you in + diagnosing problems if these cannot be reproduced with a format + that does not use any customised font definition files. + \end{itemize} + +Please also note that the whilst licence conditions on the standard +font definition files allow you to produce a customised version for +your own use, they do not allow you to distribute such a customised +font definition file under the original file name! + + +\subsection*{Note to system administrators} + +If you install a version of \LaTeX{} with a locally configured font +set-up then this system is likely to produce documents that are no +longer `formatting compatible'; for example, the use of different +default fonts will most likely produce different line and page breaks. +If you do install, on a multi-user system, a system that is configured +in such a way that it is not `formatting compatible' then you should +consider carefully the needs of users who need to create portable +documents. A good way to provide for their needs is to make +available, in addition, a standard form of \LaTeX{} without any +`formatting incompatible' customisations. + + +\section{Configuring compatibility mode} + +When processing documents that begin with |\documentstyle|, \LaTeXe{} +tries to emulate the old \LaTeX~2.09 system as far as possible. + +\filesection{latex209.cfg} + +Whenever a \LaTeX{} document starts with |\documentstyle|, rather than +with |\documentclass|, \LaTeX{} assumes that it is a \LaTeX~2.09 +document and therefore processes it in `compatibility mode'. This +does the following: +\begin{itemize} +\item sets the flag |\@compatibilitytrue|; +\item inputs the file |latex209.def|; +\item inputs the file |latex209.cfg| if it exists. +\end{itemize} + +The \LaTeX~2.09 set-up allowed the format itself to be customised. +When making the format with \iniTeX, the process ended with this +request: +\begin{quote}\tt + Input any local modifications here. +\end{quote} + +If your site did input any modifications at that point then the +\LaTeXe{} `compatibility mode' will not fully emulate \LaTeX~2.09 +\emph{as installed at your site}. In this case you should put all +these `local modifications' into a file called |latex209.cfg| and put +this file in the default input path at your site. These `local +modifications', although not stored in the format, will then be loaded +before any old-style document is processed. This should ensure that +you can continue to process any old documents that made use of this +local customisation. + + +\section[Configuration files for standard packages and classes]% + {Configuration files for standard packages\\ and classes} + +Most of the packages in the distribution do not have any associated +configuration files. The exceptions are listed here. + +\filesection{sfonts.cfg} + +The file |sfonts.cfg| can contain declarations relating to the use of +fonts in the slides class. +If it exists, it is read instead of the file |sfonts.def|. + +Please note that use of this configuration file has the following +consequences. + \begin{itemize} + \item Since the font set-up for slides has not yet been revised to + fit modern usage, the content of this file should be completely + updated sometime. Thus anyone writing such a configuration + file must be prepared to update it for use with future releases. + \item Documents are portable only in the sense of being processable + at a different site---the actual formatting will not be the same + if different fonts are used. + \item The \LaTeX3 project team will not be able to support you in + diagnosing problems if these cannot be reproduced with a format + that does not use this configuration file. + \end{itemize} + + +\filesection{ltnews.cfg} + +The file |ltnews.cfg| can be used to customise some aspects of the +behaviour of the \textsf{ltnews} class; this class is used to typeset +the the one page newsletter accompanying every \LaTeX{} distribution. +If this file is present then it is read in at the beginning of the +file |ltnews.cls|. + + +\filesection{ltxdoc.cfg} + +The file |ltxdoc.cfg| can be used to customise some aspects of the +behaviour of the \textsf{ltxdoc} class; this class is used to typeset +the documented code in the |.dtx| files. If this file is present then +it is read in at the beginning of the file |ltxdoc.cls|. + +As this file is read before the \textsf{article} class is loaded, you +may pass options to \textsf{article}. For example the following line +might be added to |ltxdoc.cfg| to format the documentation for A4 paper +instead of the default US letter paper size. +\begin{quote} +|\PassOptionsToClass{a4paper}{article}| +\end{quote} +You should note however, that even if paper size options are specified, +the \textsf{ltxdoc} class always sets the |\textwidth| parameter to +355\,pt, to enable 72 columns of text to appear in the verbatim code +listings. If you really need to over-ride this you could use: +\begin{quote} +|\AtEndOfClass{\setlength{\textwidth}{ ...}}| +\end{quote} +To set the |\textwidth| to your desired value at the end of the +\textsf{ltxdoc} class. + +By default, most of the |.dtx| documented code files in the +distribution will produce a `description' section followed by full +source listing of the package. If you wish to suppress the source +listings you may add the following line to |ltxdoc.cfg|: +\begin{quote} +|\AtBeginDocument{\OnlyDescription}| +\end{quote} + +The documentation of the \textsf{ltxdoc} package, which may be typeset +from the file |ltxdoc.dtx|, contains more examples of the use of this +configuration file. + +\filesection{ltxguide.cfg} + +The class \textsf{ltxguide} is used by the `guide' documents, such as +this document, in the \LaTeX\ distribution. A configuration file +|ltxguide.cfg| may be used with this class in a way very similar to +the customisation of the \textsf{ltxdoc} class described in the +previous section. + +\section{Configuration for other supported packages} + +The `graphics' bundle of packages needs two configuration files, +primarily to specify the driver used to process the |.dvi| file that +\LaTeX{} produces. More documentation on these files comes with the +graphics bundle but we mention them here for completeness. + +\filesection{graphics.cfg} + Normally this file just specifies a default option, by calling + |\ExecuteOptions|, for example |\ExecuteOptions{dvips}| or + |\ExecuteOptions{textures}|. + + This file is read by the \textsf{graphics} package, and so affects + all the packages in the bundle that are based on \textsf{graphics}: + \textsf{graphicx}, \textsf{epsfig}, \textsf{lscape}. + +\filesection{color.cfg} + Normally this file is identical to |graphics.cfg|. It specifies the + default driver option for the \textsf{color} package. + +\section{Non-standard versions} + +If you feel the need to make a version of \LaTeX{} that differs from +the standard version in ways that are not possible using the above +configuration possibilities, then you should first read +\textit{Modifying \LaTeX{}} in the file |modguide.tex|; this +will probably make you realise that you do not have any such need. + +Thus we are sure that you will never need to create a non-standard +version and, even if you do create one, we hope that you will not +distribute such a version. Nevertheless, you are permitted to do this +provided you take great care to do the following: +\begin{itemize} +\item +respect the conditions in legal.txt and individual files regarding +modification of files and changing the name; + +\item +change all the relevant `|\typeout| banners': i.e.~those produced by +all the non-standard files in your version and by the format; + +\item + ensure that the method used to run your version is clearly + distinguished from that used to run standard \LaTeX{}; e.g.~by using + a command name or menu entry that is clearly different from + \texttt{latex} (or \texttt{LaTeX} etc). +\end{itemize} + +\subsection{Examples} + +Since we have been prompted, despite our misgivings, to document how +to do this by members of the League for Programming Freedom, it seems +appropriate to describe here a possible modification of \LaTeX{} to +produce a system called fsf\TeX. + +To do this, you should create a file called \texttt{fsftex.tex} and +then run it using \iniTeX{} and the standard \LaTeX{} format. + +The contents of the file \texttt{fsftex.tex} should be as shown on +page \pageref{fsfcode}. The particular changes to the \LaTeX{} kernel +that you wish to make need to be added to the file at the position +indicated. You can also choose the extensions you want to use for the +class and package files in your system. + +\newpage +\label{fsfcode} + +\begin{footnotesize} +\begin{verbatim} +% fsftex.tex +% +% iniTEX Source code to make a `fsftex' format. +% +% To make this format on Unix: +% +% initex \&latex fsftex +% +% Then to run the format on file.tex: +% +% tex &fsftex file +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% *** VERY IMPORTANT!!! *** +% Change the typeout banner so users know that they +% are NOT running Standard LaTeX. +\everyjob{\typeout{fsfTeX 1.0 based on LaTeX2e \fmtversion}} +\makeatletter + +% fsfTeX changes some LaTeX internals: +% ... put what you like here ... +\def \fsf@xxxx {Some arbitrary \emph{freely modifiable} code goes here} + +% fsfTeX class files have extension .fcl (this week): +\def \@clsextension {fcl} + +% fsfTeX package files have extension .fsy: +\def \@pkgextension {fsy} + +% Change the file handling so that when a fsfTeX package or class +% is not available, the standard LaTeX file will be read. +% +% For example, \documentclass{article} will load article.fcl if such +% a file exists, but article.cls otherwise. This allows arbitrary +% processing on `article' documents without changing the standard +% article.cls file. + +\let\fsf@missingfileerror\@missingfileerror + +\def\@missingfileerror#1#2{% + \ifx #2\@clsextension + \InputIfFileExists {#1.cls}% + {\wlog {fsfTeX: loading #1.cls rather than #1.#2.}}% + {\fsf@missingfileerror {#1}{#2}}% + \else + \ifx #2\@pkgextension + \InputIfFileExists {#1.sty}% + {\wlog {fsfTeX: loading #1.sty rather than #1.#2.}}% + {\fsf@missingfileerror {#1}{#2}}% + \else + \fsf@missingfileerror {#1}{#2}% + \fi + \fi +} + +\makeatother +\dump +\end{verbatim} +\end{footnotesize} + +\end{document} diff --git a/macros/latex-dev/doc/changes-doc.txt b/macros/latex-dev/doc/changes-doc.txt new file mode 100644 index 0000000000..cd70fad506 --- /dev/null +++ b/macros/latex-dev/doc/changes-doc.txt @@ -0,0 +1,32 @@ +This file lists changes to the LaTeX2e files in reverse chronological order. +It is provided for convenience only. It therefore makes no claims to +completeness or accuracy and it contains some references to files that +are not part of the distribution. +======================================================================= + +2016-03-31 Joseph Wright + + * latexchanges.tex: Bring up to date to 2016/03/31 + +2016-02-01 Joseph Wright + + * latexchanges.tex: Bring up to date to 2016/02/01 + +2015-10-27 Joseph Wright + + * latexchanges.tex: Bring up to date to 2015/10/01 PL2 + +2015-07-01 David Carlisle + + * latexchanges.tex: describe the patch level system + +2015-04-05 Joseph Wright + * Clarify reason for \typein change in LuaTeX + +2015-04-03 David Carlisle + + * ltnews22.tex: set date back to Jan + +2015-03-31 Joseph Wright + * New changes.txt file for LaTeX2e core documentation + diff --git a/macros/latex-dev/doc/clsguide.pdf b/macros/latex-dev/doc/clsguide.pdf new file mode 100644 index 0000000000..9becca0547 Binary files /dev/null and b/macros/latex-dev/doc/clsguide.pdf differ diff --git a/macros/latex-dev/doc/clsguide.tex b/macros/latex-dev/doc/clsguide.tex new file mode 100644 index 0000000000..be77a5f244 --- /dev/null +++ b/macros/latex-dev/doc/clsguide.tex @@ -0,0 +1,1874 @@ +% \iffalse meta-comment +% +% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 +% The LaTeX3 Project and any individual authors listed elsewhere +% in this file. +% +% This file is part of the LaTeX base system. +% ------------------------------------------- +% +% 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 +% 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 file has the LPPL maintenance status "maintained". +% +% The list of all files belonging to the LaTeX base distribution is +% given in the file `manifest.txt'. See also `legal.txt' for additional +% information. +% +% The list of derived (unpacked) files belonging to the distribution +% and covered by LPPL is defined by the unpacking scripts (with +% extension .ins) which are part of the distribution. +% +% \fi +% Filename: clsguide.tex + +\NeedsTeXFormat{LaTeX2e}[1995/12/01] + +\documentclass{ltxguide}[1995/11/28] + +\title{\LaTeXe~for class and package writers} + +\author{Copyright \copyright~1995--2006 The \LaTeX3 Project\\ + All rights reserved} + +\date{15 February 2006} + +\begin{document} + +\maketitle + +\tableofcontents + +\section{Introduction} + +This document is an introduction to writing classes and packages for +\LaTeX{}, with special attention given to upgrading existing +\LaTeX~2.09 packages to \LaTeXe{}. The latter subject is also +covered in an article by Johannes Braams published in TUGboat~15.3. + +\subsection{Writing classes and packages for \LaTeXe} + +\LaTeX{} is a document preparation system that enables the document +writer to concentrate on the contents of their text, without bothering +too much about the formatting of it. For example, chapters are +indicated by |\chapter{}| rather than by selecting 18pt bold. + +The file that contains the information about how to turn logical +structure (like `|\chapter|') into formatting (like `18pt bold ragged +right') is a \emph{document class}. In addition, some features (such +as colour or included graphics) are independent of the document class +and these are contained in \emph{packages}. + +One of the largest differences between \LaTeX~2.09 and \LaTeXe{} is in +the commands used to write packages and classes. In \LaTeX~2.09, +there was very little support for writing |.sty| files, and so writers +had to resort to using low-level commands. + +\LaTeXe{} provides high-level commands for structuring packages. +It is also much easier to build classes and packages on top of each +other, for example writing a local technical report class |cetechr| +(for the Chemical Engineering department) based on |article|. + +\subsection{Overview} + +This document contains an overview of how to write classes and +packages for \LaTeX{}. It does \emph{not} introduce all of the +commands necessary to write packages: these can be found in either +\emph{\LaTeXbook} or \emph{\LaTeXcomp}. But it does describe the new +commands for structuring classes and packages. + +\begin{description} + +\item[Section~\ref{Sec:general}] contains some general advice about + writing classes and packages. It describes the difference between + classes and packages, the command naming conventions, the use of + |doc| and |docstrip|, how \TeX's primitive file and box commands + interact with \LaTeX{}. It also contains some hints about general + \LaTeX{} style. + +\item[Section~\ref{Sec:structure}] describes the structure of classes + and packages. This includes building classes and packages on top of + other classes and packages, declaring options and declaring + commands. It also contains example classes. + +\item[Section~\ref{Sec:commands}] lists the new class and package + commands. + + \item[Section~\ref{Sec:upgrade}] gives detailed advice on how to + upgrade existing \LaTeX~2.09 classes and packages to \LaTeXe{}. + +\end{description} + +\subsection{Further information} + +For a general introduction to \LaTeX{}, including the new features of +\LaTeXe{}, you should read \emph{\LaTeXbook} +by Leslie Lamport~\cite{A-W:LLa94}. + +A more detailed description of the new features of \LaTeX, including an +overview of more than 200 packages and nearly 1000 ready to run examples, is +to be found in \emph{\LaTeXcomp\ second edition} by Frank Mittelbach and +Michel Goossens~\cite{A-W:MG2004}. + +The \LaTeX{} system is based on \TeX{}, which is +described in \emph{The \TeX book} by Donald E.~Knuth~\cite{A-W:DEK91}. + +There are a number of documentation files which accompany every copy +of \LaTeX{}. A copy of \emph{\LaTeX{} News} will come out with each +six-monthly release of \LaTeX{}, and is found in the files +|ltnews*.tex|. The author's guide \emph{\usrguide} describes the new +\LaTeX{} document features; it is in |usrguide.tex|. The guide +\emph{\fntguide} describes the \LaTeX{} font selection scheme for +class- and package-writers; it is in |fntguide.tex|. Configuring +\LaTeX{} is covered by the guide \emph{\cfgguide} in +\texttt{cfgguide.tex} whilst the philosophy behind our policy on +modifying \LaTeX{} is described in \emph{\modguide} in +\texttt{modguide.tex}. + +The documented source code (from the files used to produce the kernel +format via |latex.ltx|) is now available as +\emph{The \LaTeXe\ Sources}. +This very large document also includes an index of +\LaTeX{} commands. It can be typeset from the \LaTeX{} file +|source2e.tex| in the |base| directory, using the source files and +the class file |ltxdoc.cls| from this directory. + +For more information about \TeX{} and \LaTeX{}, please contact your +local \TeX{} Users Group, or the international \TeX{} Users Group. +Addresses and other details can be found at: +\begin{quote}\small\label{addrs} + \texttt{http://www.tug.org/lugs.html} +\end{quote} + + +\subsection{Policy on standard classes} + +Many of the problem reports we receive concerning the standard classes +are not concerned with bugs but are suggesting, more or less politely, +that the design decisions embodied in them are `not optimal' and +asking us to modify them. + +There are several reasons why we should not make such changes to these +files. +\begin{itemize} +\item + However misguided, the current behaviour is clearly what was + intended when these classes were designed. +\item + It is not good practice to change such aspects of `standard classes' + because many people will be relying on them. +\end{itemize} + +We have therefore decided not to even consider making such +modifications, nor to spend time justifying that decision. This does +not mean that we do not agree that there are many deficiencies in the +design of these classes, but we have many tasks with higher priority +than continually explaining why the standard classes for \LaTeX{} +cannot be changed. + +We would, of course, welcome the production of better classes, or of +packages that can be used to enhance these classes. So your first +thought when you consider such a deficiency will, we hope, be ``what +can I do to improve this?'' + +Similar considerations apply to those parts of the kernel that are +implementing design decisions, many of which should be left to the +class file but are not in the current system. We realise that in such +cases it is much more difficult for you to rectify the problem +yourself but it is also the case that making such changes in the +kernel would probably be a major project for us; therefore such +enhancements will have to wait for \LaTeX3. + +\section{Writing classes and packages} +\label{Sec:writing} + +This section covers some general points concerned with writing +\LaTeX{} classes and packages. + + +\subsection{Old versions} + +If you are upgrading an existing \LaTeX~2.09 style file then we +recommend freezing the 2.09 version and no longer maintaining it. +Experience with the various dialects of \LaTeX{} which existed in the +early 1990's suggests that maintaining packages for different versions +of \LaTeX{} is almost impossible. It will, of course, be necessary +for some organisations to maintain both versions in parallel for some +time but this is not essential for those packages and classes +supported by individuals: they should support only the new standard +\LaTeXe{}, not obsolete versions of \LaTeX{}. + + +\subsection{Using `docstrip' and `doc'} + +If you are going to write a large class or package for \LaTeX{} then +you should consider using the |doc| software which comes with +\LaTeX{}. +\LaTeX{} classes and packages written using this can be +processed in two ways: they can be run through \LaTeX{}, to produce +documentation; and they can be processed with |docstrip|, to produce +the |.cls| or |.sty| file. + +The |doc| software can automatically generate indexes of definitions, +indexes of command use, and change-log lists. It is very useful for +maintaining and documenting large \TeX{} sources. + +The documented sources of the \LaTeX{} kernel itself, and of the +standard classes, etc, are |doc| documents; they are in the |.dtx| +files in the distribution. You can, in fact, typeset the source code +of the kernel as one long document, complete with index, by running +\LaTeX{} on |source2e.tex|. Typesetting these documents uses the +class file |ltxdoc.cls|. + +For more information on |doc| and |docstrip|, consult the files +|docstrip.dtx|, |doc.dtx|, and \emph{\LaTeXcomp}. For examples of its +use, look at the |.dtx| files. + +\subsection{Is it a class or a package?} +\label{Sec:classorpkg} + +The first thing to do when you want to put some new \LaTeX{} commands +in a file is to decide whether it should be a \emph{document class} or a +\emph{package}. The rule of thumb is: +\begin{quote} + If the commands could be used with any document class, then make + them a package; and if not, then make them a class. +\end{quote} + +There are two major types of class: those like |article|, |report| or +|letter|, which are free-standing; and those which are extensions or +variations of other classes---for example, the |proc| document class, +which is built on the |article| document class. + +Thus, a company might have a local |ownlet| class for printing letters +with their own headed note-paper. Such a class would build on top of +the existing |letter| class but it cannot be used with any other +document class, so we have |ownlet.cls| rather than |ownlet.sty|. + +The |graphics| package, in contrast, provides commands for including +images into a \LaTeX{} document. Since these commands can be used +with any document class, we have |graphics.sty| rather than +|graphics.cls|. + + +\subsection{Command names} + +\LaTeX{} has three types of command. + +There are the author commands, such as |\section|, |\emph| and +|\times|: most of these have short names, all in lower case. + +There are also the class and package writer commands: +most of these have long mixed-case names such as the following. +\begin{verbatim} + \InputIfFileExists \RequirePackage \PassOptionsToClass +\end{verbatim} + +Finally, there are the internal commands used in the \LaTeX{} +implementation, such as |\@tempcnta|, |\@ifnextchar| and |\@eha|: +most of these commands contain |@| in their name, which means they +cannot be used in documents, only in class and package files. + +Unfortunately, for historical reasons the distinction between these +commands is often blurred. For example, |\hbox| is an internal +command which should only be used in the \LaTeX{} kernel, whereas +|\m@ne| is the constant $-1$ and could have been |\MinusOne|. + +However, this rule of thumb is still useful: if a command has |@| in +its name then it is not part of the supported \LaTeX{} language---and +its behaviour may change in future releases! If a command is +mixed-case, or is described in \emph{\LaTeXbook}, then you can rely on +future releases of \LaTeXe{} supporting the command. + +\subsection{Box commands and colour} +\label{Sec:colour} + +Even if you do not intend to use colour in your own documents, by +taking note of the points in this section you can ensure that your +class or package is compatible with the |color| package. This may +benefit people using your class or package who have access to colour +printers. + +The simplest way to ensure `colour safety' is to always use \LaTeX{} +box commands rather than \TeX{} primitives, that is use |\sbox| rather +than |\setbox|, |\mbox| rather than |\hbox| and |\parbox| or +the |minipage| environment rather than |\vbox|. +The \LaTeX{} box commands have new options which mean that they are now +as powerful as the \TeX{} primitives. + +As an example of what can go wrong, consider that in +|{\ttfamily <text>}| +the font is restored just \emph{before} the |}|, whereas in the +similar looking construction +|{\color{green} <text>}| +the colour is restored just \emph{after} the final |}|. Normally this +distinction does not matter at all; but consider a primitive \TeX{} +box assignment such as: +\begin{verbatim} + \setbox0=\hbox{\color{green} <text>} +\end{verbatim} +Now the colour-restore occurs after the |}| and so is \emph{not} +stored in the box. Exactly what bad effects this can have depends on +how colour is implemented: it can range from getting the wrong +colours in the rest of the document, to causing errors in the +dvi-driver used to print the document. + +Also of interest is the command |\normalcolor|. This is +normally just |\relax| (i.e., does nothing) +but you can use it rather like |\normalfont| to +set regions of the page such as captions or section headings to the +`main document colour'. + + +\subsection{Defining text and math characters} +\label{Sec:chars} + +Because \LaTeXe{} supports different encodings, definitions of commands +for producing symbols, accents, composite glyphs, etc.\ must be +defined using the commands provided for this purpose and described in +\emph{\fntguide}. This part of the system is still under development +so such tasks should be undertaken with great caution. + +Also, |\DeclareRobustCommand| should be used for encoding-independent +commands of this type. + +Note that it is no longer possible to refer to the math font set-up +outside math mode: for example, neither |\textfont 1| nor +|\scriptfont 2| are guaranteed to be defined in other modes. + + +\subsection{General style} +\label{Sec:general} + +The new system provides many commands designed to help you produce +well-structured class and package files that are both robust and +portable. This section outlines some ways to make intelligent use of +these. + +\subsubsection{Loading other files} +\label{Sec:loading} + +\NEWdescription{1995/12/01} +\LaTeX{} provides these commands: +\begin{verbatim} + \LoadClass \LoadClassWithOptions + \RequirePackage \RequirePackageWithOptions +\end{verbatim} +for using classes or packages inside other classes or packages. We +recommend strongly that you use them, rather than the primitive +|\input| command, for a number of reasons. + +Files loaded with |\input <filename>| will not be listed in the +|\listfiles| list. + +If a package is always loaded with |\RequirePackage...| or |\usepackage| +then, even if its loading is requested several times, it will be +loaded only once. By contrast, if it is loaded with |\input| then it +can be loaded more than once; such an extra loading may waste time and +memory and it may produce strange results. + +If a package provides option-processing then, again, strange results +are possible if the package is |\input| rather than loaded by means of +|\usepackage| or |\RequirePackage...|. + +If the package |foo.sty| loads the package |baz.sty| by use of +|\input baz.sty| then the user will get a warning: +\begin{verbatim} + LaTeX Warning: You have requested package `foo', + but the package provides `baz'. +\end{verbatim} +Thus, for several reasons, using |\input| to load packages is not a +good idea. + +Unfortunately, if you are upgrading the file |myclass.sty| to a class +file then you have to make sure that any old files which contain +|\input myclass.sty| still work. + +This was also true for the standard classes (|article|, |book| and +|report|), since a lot of existing \LaTeX~2.09 document styles contain +|\input article.sty|. The approach which we use to solve this is +to provide minimal files |article.sty|, |book.sty| and |report.sty|, +which simply load the appropriate class files. + +For example, |article.sty| contains just the following lines: +\begin{verbatim} + \NeedsTeXFormat{LaTeX2e} + \@obsoletefile{article.cls}{article.sty} + \LoadClass{article} +\end{verbatim} +You may wish to do the same or, if you think that it is safe to do so, +you may decide to just remove |myclass.sty|. + +\subsubsection{Make it robust} + +We consider it good practice, when writing packages and classes, to use +\LaTeX{} commands as much as possible. + +Thus, instead of using |\def...| we recommend using one of +|\newcommand|, |\renewcommand| or |\providecommand|; |\CheckCommand| is +also useful. Doing this makes +it less likely that you will inadvertently redefine a command, giving +unexpected results. + +When you define an environment, use |\newenvironment| or +|\renewenvironment| instead |\def\foo{...}| and |\def\endfoo{...}|. + +If you need to set or change the value of a \m{dimen} or \m{skip} +register, use |\setlength|. + +To manipulate boxes, use \LaTeX{} commands such as |\sbox|, +|\mbox| and |\parbox| rather than |\setbox|, |\hbox| and |\vbox|. + +Use |\PackageError|, |\PackageWarning| or |\PackageInfo| (or the +equivalent class commands) rather than |\@latexerr|, |\@warning| or +|\wlog|. + +It is still possible to declare options by defining |\ds@<option>| and +calling |\@options|; but we recommend the |\DeclareOption| and +|\ProcessOptions| commands instead. These are more powerful and use +less memory. So rather than using: +\begin{verbatim} + \def\ds@draft{\overfullrule 5pt} + \@options +\end{verbatim} +you should use: +\begin{verbatim} + \DeclareOption{draft}{\setlength{\overfullrule}{5pt}} + \ProcessOptions\relax +\end{verbatim} + +The advantage of this kind of practice is that your code is more +readable and, more important, that it is less likely to break when +used with future versions of \LaTeX{}. + +\subsubsection{Make it portable} + +It is also sensible to make your files are as portable as possible. To +ensure this; they should contain only visible 7-bit text; and the +filenames should contain at most eight characters (plus the three +letter extension). Also, of course, it \textbf{must not} have the +same name as a file in the standard \LaTeX{} distribution, however +similar its contents may be to one of these files. + +It is also useful if local classes or packages have a common prefix, +for example the University of Nowhere classes might begin with |unw|. +This helps to avoid every University having its own thesis class, all +called |thesis.cls|. + +If you rely on some features of the \LaTeX{} kernel, or on a package, +please specify the release-date you need. For example, the package +error commands were introduced in the June 1994 release so, if you use +them then you should put: +\begin{verbatim} + \NeedsTeXFormat{LaTeX2e}[1994/06/01] +\end{verbatim} + +\subsubsection{Useful hooks} + +Some packages and document styles had to redefine the command +|\document| or |\enddocument| to achieve their goal. This is no +longer necessary. You can now use the `hooks' |\AtBeginDocument| and +|\AtEndDocument| (see Section~\ref{Sec:delays}). Again, using these +hooks makes it less likely that your code breaks with future versions +of \LaTeX{}. It also makes it more likely that your package can work +together with someone else's. + +\NEWdescription{1996/12/01} +However, note that code in the |\AtBeginDocument| hook is part of the +preamble. Thus there are restrictions on what can be put there; in +particular, no typesetting can be done. + +\section{The structure of a class or package} +\label{Sec:structure} + +\LaTeXe{} classes and packages have more structure than \LaTeX~2.09 +style files did. The outline of a class or package file is: +\begin{description} +\item[Identification] The file says that it is a \LaTeXe{} package or + class, and gives a short description of itself. +\item[Preliminary declarations] + Here the file declares some commands and can also load + other files. Usually these commands will be just those needed for + the code used in the declared options. +\item[Options] The file declares and processes its options. +\item[More declarations] This is where the file does most of its work: + declaring new variables, commands and fonts; and loading other files. +\end{description} + +\subsection{Identification} + +The first thing a class or package file does is identify itself. +Package files do this as follows: +\begin{verbatim} + \NeedsTeXFormat{LaTeX2e} + \ProvidesPackage{<package>}[<date> <other information>] +\end{verbatim} +For example: +\begin{verbatim} + \NeedsTeXFormat{LaTeX2e} + \ProvidesPackage{latexsym}[1994/06/01 Standard LaTeX package] +\end{verbatim} +Class files do this as follows: +\begin{verbatim} + \NeedsTeXFormat{LaTeX2e} + \ProvidesClass{<class-name>}[<date> <other information>] +\end{verbatim} +For example: +\begin{verbatim} + \NeedsTeXFormat{LaTeX2e} + \ProvidesClass{article}[1994/06/01 Standard LaTeX class] +\end{verbatim} +\NEWdescription{1998/06/19} +The \m{date} should be given in the form `\textsc{yyyy/mm/dd}' and +must be present if the optional argument is used (this is also true +for the |\NeedsTeXFormat| command). +Any derivation from this syntax will result in low-level \TeX{} +errors---the commands expect a valid syntax to speed up the daily +usage of the package or class and make no provision for the case that +the developer made a mistake! + +This date is checked whenever a user specifies a date in their +|\documentclass| or |\usepackage| command. For example, if you wrote: +\begin{verbatim} + \documentclass{article}[1995/12/23] +\end{verbatim} +then users at a different location +would get a warning that their copy of |article| was out of +date. + +The description of a class is displayed when the class is used. The +description of a package is put into the log file. These descriptions +are also displayed by the |\listfiles| command. The phrase +\texttt{Standard LaTeX} \textbf{must not} be used in the identification +banner of any file other than those in the standard \LaTeX{} +distribution. + + +\subsection{Using classes and packages} + +The first major difference between \LaTeX~2.09 style files and +\LaTeXe{} packages and classes is that \LaTeXe{} supports +\emph{modularity}, in the sense of building files from small +building-blocks rather than using large single files. + +A \LaTeX{} package or class can load a package as follows: +\begin{verbatim} + \RequirePackage[<options>]{<package>}[<date>] +\end{verbatim} +For example: +\begin{verbatim} + \RequirePackage{ifthen}[1994/06/01] +\end{verbatim} +This command has the same syntax as the author command |\usepackage|. +It allows packages or classes to use features provided by other +packages. For example, by loading the |ifthen| package, a package +writer can use the `if\dots then\dots else\dots' commands provided +by that package. + +A \LaTeX{} class can load one other class as follows: +\begin{verbatim} + \LoadClass[<options>]{<class-name>}[<date>] +\end{verbatim} +For example: +\begin{verbatim} + \LoadClass[twocolumn]{article} +\end{verbatim} +This command has the same syntax as the author command |\documentclass|. +It allows classes to be based on the syntax and appearance of another +class. For example, by loading the |article| class, a class writer +only has to change the bits of |article| they don't like, rather than +writing a new class from scratch. + +\NEWfeature{1995/12/01} +The following commands can be used in the common case that you want to +simply load a class or package file with exactly those options that +are being used by the current class. +\begin{verbatim} + \LoadClassWithOptions{<class-name>}[<date>] + \RequirePackageWithOptions{<package>}[<date>] +\end{verbatim} +For example: +\begin{verbatim} + \LoadClassWithOptions{article} + \RequirePackageWithOptions{graphics}[1995/12/01] +\end{verbatim} + +\subsection{Declaring options} + +\NEWdescription{1998/12/01} +The other major difference between \LaTeX~2.09 styles and \LaTeXe{} +packages and classes is in option handling. Packages and classes can +now declare options and these can be specified by authors; for +example, the |twocolumn| option is declared by the |article| class. +Note that the name of an option should contain only those characters +allowed in a `\LaTeX{} name'; in particular it must not contain any +control sequences. + +An option is declared as follows: +\begin{verbatim} + \DeclareOption{<option>}{<code>} +\end{verbatim} +For example, the |dvips| option (slightly simplified) +to the |graphics| package is implemented as: +\begin{verbatim} + \DeclareOption{dvips}{\input{dvips.def}} +\end{verbatim} +This means that when an author writes |\usepackage[dvips]{graphics}|, +the file |dvips.def| is loaded. As another example, the |a4paper| +option is declared in the |article| class to set the |\paperheight| +and |\paperwidth| lengths: +\begin{verbatim} + \DeclareOption{a4paper}{% + \setlength{\paperheight}{297mm}% + \setlength{\paperwidth}{210mm}% + } +\end{verbatim} +Sometimes a user will request an option which the class +or package has not explicitly declared. By default this will produce +a warning (for classes) or error (for packages); this behaviour +can be altered as follows: +\begin{verbatim} + \DeclareOption*{<code>} +\end{verbatim} +For example, to make the package |fred| produce a warning rather than +an error for unknown options, you could specify: +\begin{verbatim} + \DeclareOption*{% + \PackageWarning{fred}{Unknown option `\CurrentOption'}% + } +\end{verbatim} +Then, if an author writes |\usepackage[foo]{fred}|, they will get a +warning \texttt{Package fred Warning: Unknown option `foo'.} As +another example, the |fontenc| package tries to load a file +|<ENC>enc.def| whenever the \m{ENC} option is used. This +can be done by writing: +\begin{verbatim} + \DeclareOption*{% + \input{\CurrentOption enc.def}% + } +\end{verbatim} +\NEWdescription{1998/12/01} +It is possible to pass options on to another package or class, using +the command |\PassOptionsToPackage| or |\PassOptionsToClass| (note +that this is a specialised operation that works only for option +names). For example, to pass every unknown option on to the |article| +class, you can use: +\begin{verbatim} + \DeclareOption*{% + \PassOptionsToClass{\CurrentOption}{article}% + } +\end{verbatim} +If you do this then you should make sure you load the class at some +later point, otherwise the options will never be processed! + +So far, we have explained only how to declare options, not how to +execute them. To process the options with which the file was called, +you should use: +\begin{verbatim} + \ProcessOptions\relax +\end{verbatim} +This executes the \m{code} for each option that was both specified and +declared (see Section~\ref{Sec:commands.options} for details of how +this is done). + +For example, if the |jane| package file contains: +\begin{verbatim} + \DeclareOption{foo}{\typeout{Saw foo.}} + \DeclareOption{baz}{\typeout{Saw baz.}} + \DeclareOption*{\typeout{What's \CurrentOption?}} + \ProcessOptions\relax +\end{verbatim} +and an author writes |\usepackage[foo,bar]{jane}|, then they will see +the messages \texttt{Saw foo.} and \texttt{What's bar?} + +\subsection{A minimal class file} + +Most of the work of a class or package is in defining new commands, or +changing the appearance of documents. This is done in the body of the +package, using commands such as |\newcommand| or |\setlength|. + +\LaTeXe{} provides several new commands to help class and package +writers; these are described in detail in Section~\ref{Sec:commands}. + +There are four things that every class file \emph{must} contain: these +are a definition of |\normalsize|, values for |\textwidth| and +|\textheight| and a specification for page-numbering. So a minimal +document class file\footnote {This class is now in the standard +distribution, as \texttt{minimal.cls}.} looks like this: +\begin{verbatim} + \NeedsTeXFormat{LaTeX2e} + \ProvidesClass{minimal}[1995/10/30 Standard LaTeX minimal class] + \renewcommand{\normalsize}{\fontsize{10pt}{12pt}\selectfont} + \setlength{\textwidth}{6.5in} + \setlength{\textheight}{8in} + \pagenumbering{arabic} % needed even though this class will + % not show page numbers +\end{verbatim} +However, this class file will not support footnotes, marginals, +floats, etc., nor will it provide any of the 2-letter font commands +such as |\rm|; thus most classes will contain more than this minimum! + +\subsection{Example: a local letter class} + +A company may have its own letter class, for setting letters in the +company style. This section shows a simple implementation of such a +class, although a real class would need more structure. + +The class begins by announcing itself as |neplet.cls|. +\begin{verbatim} + \NeedsTeXFormat{LaTeX2e} + \ProvidesClass{neplet}[1995/04/01 NonExistent Press letter class] +\end{verbatim} +Then this next bit passes any options on to the |letter| class, which +is loaded with the |a4paper| option. +\begin{verbatim} + \DeclareOption*{\PassOptionsToClass{\CurrentOption}{letter}} + \ProcessOptions\relax + \LoadClass[a4paper]{letter} +\end{verbatim} +In order to use the company letter head, it redefines the +|firstpage| page style: this is the page style that is used on +the first page of letters. +\begin{verbatim} + \renewcommand{\ps@firstpage}{% + \renewcommand{\@oddhead}{<letterhead goes here>}% + \renewcommand{\@oddfoot}{<letterfoot goes here>}% + } +\end{verbatim} +And that's it! + +\subsection{Example: a newsletter class} + +A simple newsletter can be typeset with \LaTeX{}, using a variant of the +|article| class. +The class begins by announcing itself as |smplnews.cls|. +\begin{verbatim} + \NeedsTeXFormat{LaTeX2e} + \ProvidesClass{smplnews}[1995/04/01 The Simple News newsletter class] + + \newcommand{\headlinecolor}{\normalcolor} +\end{verbatim} +It passes most specified options on to the |article| class: apart from +the |onecolumn| option, which is switched off, and the |green| option, +which sets the headline in green. +\begin{verbatim} + \DeclareOption{onecolumn}{\OptionNotUsed} + \DeclareOption{green}{\renewcommand{\headlinecolor}{\color{green}}} + + \DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}} + + \ProcessOptions\relax +\end{verbatim} +It then loads the class |article| with the option |twocolumn|. +\begin{verbatim} + \LoadClass[twocolumn]{article} +\end{verbatim} +Since the newsletter is to be printed in colour, it now loads the +|color| package. The class does not specify a device driver option +since this should be specified by the user of the |smplnews| class. +\begin{verbatim} + \RequirePackage{color} +\end{verbatim} +The class then redefines |\maketitle| to produce the title in 72pt +Helvetica bold oblique, in the appropriate colour. +\begin{verbatim} + \renewcommand{\maketitle}{% + \twocolumn[% + \fontsize{72}{80}\fontfamily{phv}\fontseries{b}% + \fontshape{sl}\selectfont\headlinecolor + \@title + ]% + } +\end{verbatim} +It redefines |\section| and switches off section numbering. +\begin{verbatim} + \renewcommand{\section}{% + \@startsection + {section}{1}{0pt}{-1.5ex plus -1ex minus -.2ex}% + {1ex plus .2ex}{\large\sffamily\slshape\headlinecolor}% + } + + \setcounter{secnumdepth}{0} +\end{verbatim} +It also sets the three essential things. +\begin{verbatim} + \renewcommand{\normalsize}{\fontsize{9}{10}\selectfont} + \setlength{\textwidth}{17.5cm} + \setlength{\textheight}{25cm} +\end{verbatim} +In practice, a class would need more than this: it would provide +commands for issue numbers, authors of articles, page styles and so +on; but this skeleton gives a start. The |ltnews| class file is not +much more complex than this one. + +\section{Commands for class and package writers} +\label{Sec:commands} + +This section describes briefly each of the new commands for class and +package writers. To find out about other aspects of the new system, +you should also read \emph{\LaTeXbook}, \emph{\LaTeXcomp} and +\emph{\usrguide}. + +\subsection{Identification} + +The first group of commands discussed here are those used +to identify your class or package file. + +\begin{decl} +|\NeedsTeXFormat| \arg{format-name} \oarg{release-date} +\end{decl} +This command tells \TeX{} that this file should be processed using a +format with name \m{format-name}. You can use the optional argument +\m{release-date} to further specify the earliest release date of the +format that is needed. When the release date of the format is older +than the one specified a warning will be generated. The standard +\m{format-name} is \texttt{LaTeX2e}. The date, if present, must be in +the form \textsc{yyyy/mm/dd}. + +Example: +\begin{verbatim} + \NeedsTeXFormat{LaTeX2e}[1994/06/01] +\end{verbatim} + +\begin{decl} +|\ProvidesClass| \arg{class-name} \oarg{release-info} \\ +|\ProvidesPackage| \arg{package-name} \oarg{release-info} +\end{decl} +This declares that the current file contains the definitions for the +document class \m{class-name} or package \m{package-name}. + +The optional \m{release-info}, if used, must contain: +\begin{itemize} + \item the release date of + this version of the file, in the form \textsc{yyyy/mm/dd}; +\item optionally followed by a space and a short description, possibly + including a version number. +\end{itemize} +The above syntax must be followed exactly so that this information +can be used by |\LoadClass| or |\documentclass| (for classes) or +|\RequirePackage| or |\usepackage| (for packages) to test that the +release is not too old. + +The whole of this \m{release-info} information is displayed by +|\listfiles| and should therefore not be too long. + +Example: +\begin{verbatim} + \ProvidesClass{article}[1994/06/01 v1.0 Standard LaTeX class] + \ProvidesPackage{ifthen}[1994/06/01 v1.0 Standard LaTeX package] +\end{verbatim} + +\begin{decl} + |\ProvidesFile| \arg{file-name} \oarg{release-info} +\end{decl} +This is similar to the two previous commands except that here the full +filename, including the extension, must be given. It is used for +declaring any files other than main class and package files. + +Example: +\begin{verbatim} + \ProvidesFile{T1enc.def}[1994/06/01 v1.0 Standard LaTeX file] +\end{verbatim} + +Note that the phrase \texttt{Standard LaTeX} \textbf{must not} be used +in the identification banner of any file other than those in the +standard \LaTeX{} distribution. + +\subsection{Loading files} +\label{Sec:loadf} + +\NEWfeature{1995/12/01} +This group of commands can be used to create your own document class or +package by building on existing classes or packages. +\begin{decl} + |\RequirePackage| \oarg{options-list} \arg{package-name} + \oarg{release-info}\\ + |\RequirePackageWithOptions| \arg{package-name} + \oarg{release-info} +\end{decl} +Packages and classes should use these commands to load other packages. + +The use of |\RequirePackage| is the same as the author command +|\usepackage|. + +Examples: +\begin{verbatim} + \RequirePackage{ifthen}[1994/06/01] + \RequirePackageWithOptions{graphics}[1995/12/01] +\end{verbatim} + +\begin{decl} + |\LoadClass| \oarg{options-list} \arg{class-name} + \oarg{release-info}\\ + |\LoadClassWithOptions| \arg{class-name} + \oarg{release-info} +\end{decl} +\NEWfeature{1995/12/01} +These commands are for use \emph{only} in class files, they cannot be +used in packages files; +they can be used at most once within a class file. + +The use of |\LoadClass| is the same as +the use of |\documentclass| to load a class file. + +Examples: +\begin{verbatim} + \LoadClass{article}[1994/06/01] + \LoadClassWithOptions{article}[1995/12/01] +\end{verbatim} + +\NEWfeature{1995/12/01} +The two |WithOptions| versions simply load the class (or package) file +with exactly those options that are being used by the current file +(class or package). See below, in \ref{Sec:opmove}, for further +discussion of their use. + + +\subsection{Option declaration} +\label{Sec:commands.options.dec} + +\NEWdescription{1998/12/01} +The following commands deal with the declaration and handling of +options to document classes and packages. Every option name must be a +`\LaTeX{} name'. + +There are some commands designed especially for use within the +\m{code} argument of these commands (see below). + +\begin{decl} + |\DeclareOption| \arg{option-name} \arg{code} +\end{decl} +This makes \m{option-name} a `declared option' of the class or package +in which it is put. + +The \m{code} argument contains the code to be executed if that option +is specified for the class or package; it can contain any valid +\LaTeXe{} construct. + +Example: +\begin{verbatim} + \DeclareOption{twoside}{\@twosidetrue} +\end{verbatim} + +\begin{decl} + |\DeclareOption*| \arg{code} +\end{decl} +This declares the \m{code} to be executed for every option which is +specified for, but otherwise not explicitly declared by, the class or +package; this code is called the `default option code' and it can +contain any valid \LaTeXe{} construct. + +If a class file contains no |\DeclareOption*| then, by default, all +specified but undeclared options for that class will be silently +passed to all packages (as will the specified and declared options for +that class). + +If a package file contains no |\DeclareOption*| then, by default, each +specified but undeclared option for that package will produce an error. + + +\subsection{Commands within option code} +\label{Sec:within.code} + +These two commands can be used only within the \m{code} argument of +either |\DeclareOption| or |\DeclareOption*|. Other commands commonly +used within these arguments can be found in the next few subsections. + +\begin{decl} + |\CurrentOption| +\end{decl} +This expands to the name of the current option. + +\begin{decl} + |\OptionNotUsed| +\end{decl} +This causes the current option to +be added to the list of `unused options'. + +\NEWfeature{1995/06/01} + You can now include hash marks (\texttt{\#}) within these \m{code} + arguments without special treatment (formerly, it had been + necessary to double them). + +\subsection{Moving options around} +\label{Sec:opmove} + +These two commands are also very useful within the \m{code} argument +of |\DeclareOption| or |\DeclareOption*|: +\begin{decl} + |\PassOptionsToPackage| \arg{options-list} \arg{package-name}\\ + |\PassOptionsToClass| \arg{options-list} \arg{class-name} +\end{decl} +The command |\PassOptionsToPackage| passes the option names in +\m{options-list} to package \m{package-name}. +This means that it adds the \m{option-list} to the +list of options used by any future |\RequirePackage| or |\usepackage| +command for package \m{package-name}. + +Example: +\begin{verbatim} + \PassOptionsToPackage{foo,bar}{fred} + \RequirePackage[baz]{fred} +\end{verbatim} +is the same as: +\begin{verbatim} + \RequirePackage[foo,bar,baz]{fred} +\end{verbatim} + +Similarly, |\PassOptionsToClass| may be used in a class file to pass +options to another class to be loaded with |\LoadClass|. + +\NEWdescription{1995/12/01} +The effects and use of these two commands should be contrasted with +those of the following two (documented above, in \ref{Sec:loadf}): +\begin{verbatim} + \LoadClassWithOptions + \RequirePackageWithOptions +\end{verbatim} +The command |\RequirePackageWithOptions| is similar to +|\RequirePackage|, but it always loads the required package with +exactly the same option list as that being used by the current class +or package, rather than with any option explicitly supplied or passed +on by |\PassOptionsToPackage|. + +The main purpose of |\LoadClassWithOptions| is to allow one class to +simply build on another, for example: +\begin{verbatim} + \LoadClassWithOptions{article} +\end{verbatim} +This should be compared with the slightly different construction +\begin{verbatim} + \DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}} + \ProcessOptions\relax + \LoadClass{article} +\end{verbatim} +As used above, the effects are more or less the same, but the first is +a lot less to type; also the |\LoadClassWithOptions| method runs +slightly quicker. + +If, however, the class declares options of its own then +the two constructions are different. Compare, for example: +\begin{verbatim} + \DeclareOption{landscape}{\@landscapetrue} + \ProcessOptions\relax + \LoadClassWithOptions{article} +\end{verbatim} +with: +\begin{verbatim} + \DeclareOption{landscape}{\@landscapetrue} + \DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}} + \ProcessOptions\relax + \LoadClass{article} +\end{verbatim} +In the first example, the \textsf{article} class will be loaded with +option |landscape| precisely when the current class is called with +this option. By contrast, in the second example it will never be +called with option \texttt{landscape} as in that case \textsf{article} +is passed options only by the default option handler, but this handler +is not used for |landscape| because that option is explicitly +declared. + +\subsection{Delaying code} +\label{Sec:delays} + +These first two commands are also intended primarily for use within +the \m{code} argument of |\DeclareOption| or |\DeclareOption*|. + +\begin{decl} + |\AtEndOfClass| \arg{code}\\ + |\AtEndOfPackage| \arg{code} +\end{decl} +These commands declare \m{code} that is saved away internally and then +executed after processing the whole of the current class or package +file. + +Repeated use of these commands is permitted: the code in the +arguments is stored (and later executed) in the order of their +declarations. + +\begin{decl} + |\AtBeginDocument| \arg{code}\\ + |\AtEndDocument| \arg{code} +\end{decl} +These commands declare \m{code} to be saved internally and executed +while \LaTeX{} is executing |\begin{document}| or |\end{document}|. + +The \m{code} specified in the argument to |\AtBeginDocument| is +executed near the end of the |\begin{document}| code, \emph{after} the +font selection tables have been set up. It is therefore a useful +place to put code which needs to be executed after everything has been +prepared for typesetting and when the normal font for the document is +the current font. + +\NEWdescription{1995/12/01} +The |\AtBeginDocument| hook should not be used for code that does any +typesetting since the typeset result would be unpredictable. + +The \m{code} specified in the argument to |\AtEndDocument| is +executed at the beginning of the |\end{document}| code, +\emph{before} the final page is finished and before any leftover +floating environments are processed. If some of the \m{code} is to be +executed after these two processes, you should include a |\clearpage| +at the appropriate point in \m{code}. + +Repeated use of these commands is permitted: the code in the +arguments is stored (and later executed) in the order of their +declarations. + +\begin{decl}[1994/12/01] + |\AtBeginDvi| \arg{specials} +\end{decl} +These commands save in a box register things which are written to the +|.dvi| file at the beginning of the `shipout' of the first page of the +document. + +This should not be used for anything that will add any typeset +material to the |.dvi| file. + +Repeated use of this command is permitted. + + +\subsection{Option processing} +\label{Sec:commands.options} + +\begin{decl} + |\ProcessOptions| +\end{decl} +This command executes the \m{code} for each selected option. + +We shall first describe how |\ProcessOptions| works in a package file, +and then how this differs in a class file. + +To understand in detail what |\ProcessOptions| does in a package file, +you have to know the difference between \emph{local} and \emph{global} +options. +\begin{itemize} +\item \textbf{Local options} are those which have been explicitly + specified for this particular package in the \m{options} argument of + any of these: +\begin{quote} + |\PassOptionsToPackage{<options>}| \ |\usepackage[<options>]|\\ + |\RequirePackage[<options>]| +\end{quote} +\item \textbf{Global options} are any other options that are specified + by the author in the \m{options} argument of + |\documentclass[<options>]|. +\end{itemize} +For example, suppose that a document begins: +\begin{verbatim} + \documentclass[german,twocolumn]{article} + \usepackage{gerhardt} +\end{verbatim} +whilst package |gerhardt| calls package |fred| with: +\begin{verbatim} + \PassOptionsToPackage{german,dvips,a4paper}{fred} + \RequirePackage[errorshow]{fred} +\end{verbatim} +then: +\begin{itemize} +\item |fred|'s local options are |german|, |dvips|, |a4paper| + and |errorshow|; +\item |fred|'s only global option is |twocolumn|. +\end{itemize} + +When |\ProcessOptions| is called, the following happen. +\begin{itemize} +\item \emph{First}, for each option so far declared in |fred.sty| + by |\DeclareOption|, it looks to see if that option is either a + global or a local option for |fred|: if it is then the corresponding + code is executed. + + This is done in the order in which these options + were declared in |fred.sty|. +\item \emph{Then}, for each remaining \emph{local} option, the command + |\ds@<option>| is executed if it has been defined somewhere (other + than by a |\DeclareOption|); otherwise, the `default option code' is + executed. If no default option code has been declared then an error + message is produced. + + This is done in the order in which these + options were specified. +\end{itemize} +Throughout this process, the system ensures that the code declared for +an option is executed at most once. + +Returning to the example, if |fred.sty| contains: +\begin{verbatim} + \DeclareOption{dvips}{\typeout{DVIPS}} + \DeclareOption{german}{\typeout{GERMAN}} + \DeclareOption{french}{\typeout{FRENCH}} + \DeclareOption*{\PackageWarning{fred}{Unknown `\CurrentOption'}} + \ProcessOptions\relax +\end{verbatim} +then the result of processing this document will be: +\begin{verbatim} + DVIPS + GERMAN + Package fred Warning: Unknown `a4paper'. + Package fred Warning: Unknown `errorshow'. +\end{verbatim} +Note the following: + +\begin{itemize} +\item the code for the |dvips| option is executed before that for the + |german| option, because that is the order in which they are declared + in |fred.sty|; +\item the code for the |german| option is executed only once, when the + declared options are being processed; +\item the |a4paper| and |errorshow| options produce the warning from + the code declared by |\DeclareOption*| (in the order in which they + were specified), whilst the |twocolumn| option does not: this is + because |twocolumn| is a global option. +\end{itemize} + +In a class file, |\ProcessOptions| works in the same way, except +that: \emph{all} options are local; and the default value for +|\DeclareOption*| is |\OptionNotUsed| rather than an error. + +\NEWdescription{1995/12/01} +Note that, because |\ProcessOptions| has a |*|-form, it is wise to +follow the non-star form with |\relax|, as in the previous examples, +since this prevents unnecessary look ahead and possibly misleading +error messages being issued. + +\begin{decl} + |\ProcessOptions*| \\ + |\@options| +\end{decl} +This is like |\ProcessOptions| but it executes the options in the +order specified in the calling commands, rather than in the order of +declaration in the class or package. For a package this means that the +global options are processed first. + +The |\@options| command from \LaTeX~2.09 has been made equivalent to +this in order to ease the task of updating old document styles to +\LaTeXe{} class files. + +\begin{decl} + |\ExecuteOptions| \arg{options-list} +\end{decl} + +For each option in the \m{options-list}, in order, +this command simply executes the command +|\ds@<option>| (if this command is not defined, then that option is +silently ignored). + +It can be used to provide a `default option list' just before +|\ProcessOptions|. For example, suppose that in a class file you want +to set up the default design to be: two-sided printing; 11pt fonts; +in two columns. Then it could specify: +\begin{verbatim} + \ExecuteOptions{11pt,twoside,twocolumn} +\end{verbatim} + + +\subsection{Safe file commands} + +These commands deal with file input; they ensure that the non-existence +of a requested file can be handled in a user-friendly way. + +\begin{decl} +|\IfFileExists| \arg{file-name} \arg{true} \arg{false} +\end{decl} +If the file exists then the code specified in \m{true} is +executed. + +If the file does not exist then the code specified in \m{false} is +executed. + +This command does \emph{not} input the file. + +\begin{decl} + |\InputIfFileExists| \arg{file-name} \arg{true} \arg{false} +\end{decl} +This inputs the file \m{file-name} if it exists and, immediately +before the input, the code specified in \m{true} is executed. + +If the file does not exist then the code specified in \m{false} is +executed. + +It is implemented using |\IfFileExists|. + + +\subsection{Reporting errors, etc} + +These commands should be used by third party classes and packages to +report errors, or to provide information to authors. + +\begin{decl} + |\ClassError| \arg{class-name} \arg{error-text} \arg{help-text}\\ + |\PackageError| \arg{package-name} \arg{error-text} \arg{help-text} +\end{decl} +These produce an error message. The \m{error-text} is displayed and the +|?| error prompt is shown. If the user types |h|, they will be shown +the \m{help-text}. + +Within the \m{error-text} and \m{help-text}: |\protect| can be used to +stop a command from expanding; |\MessageBreak| causes a line-break; +and |\space| prints a space. + +Note that the \m{error-text} will have a full stop added to it, so do +not put one into the argument. + +For example: +\begin{verbatim} + \newcommand{\foo}{FOO} + \PackageError{ethel}{% + Your hovercraft is full of eels,\MessageBreak + and \protect\foo\space is \foo + }{% + Oh dear! Something's gone wrong.\MessageBreak + \space \space Try typing \space <<return>> + \space to proceed, ignoring \protect\foo. + } +\end{verbatim} +produces this display: +\begin{verbatim} + ! Package ethel Error: Your hovercraft is full of eels, + (ethel) and \foo is FOO. + + See the ethel package documentation for explanation. +\end{verbatim} +If the user types |h|, this will be shown: +\begin{verbatim} + Oh dear! Something's gone wrong. + Try typing <<return>> to proceed, ignoring \foo. +\end{verbatim} + +\begin{decl} + |\ClassWarning| \arg{class-name} \arg{warning-text}\\ + |\PackageWarning| \arg{package-name} \arg{warning-text}\\ + |\ClassWarningNoLine| \arg{class-name} \arg{warning-text}\\ + |\PackageWarningNoLine| \arg{package-name} \arg{warning-text}\\ + |\ClassInfo| \arg{class-name} \arg{info-text}\\ + |\PackageInfo| \arg{package-name} \arg{info-text} +\end{decl} +The four |Warning| commands are similar to the error commands, except +that they produce only a warning on the screen, with no error prompt. + +The first two, |Warning| versions, also show the line number where the +warning occurred, whilst the second two, |WarningNoLine| versions, do +not. + +The two |Info| commands are similar except that they log the +information only in the transcript file, including the line number. +There are no |NoLine| versions of these two. + +Within the \m{warning-text} and \m{info-text}: |\protect| can be used to +stop a command from expanding; |\MessageBreak| causes a line-break; +and |\space| prints a space. +Also, these should not end with a full stop as one is +automatically added. + + +\subsection{Defining commands} +\label{Sec:commands.define} + +\LaTeXe{} provides some extra methods of (re)defining commands that are +intended for use in class and package files. + +\NEWfeature{1994/12/01} +The \texttt{*}-forms of these commands should be used to define +commands that are not, in \TeX{} terms, long. This can be useful for +error-trapping with commands whose arguments are not intended to +contain whole paragraphs of text. + +\begin{decl} + |\DeclareRobustCommand| \arg{cmd} \oarg{num} \oarg{default} + \arg{definition}\\ + |\DeclareRobustCommand*| \arg{cmd} \oarg{num} \oarg{default} + \arg{definition} +\end{decl} +This command takes the same arguments as |\newcommand| but it declares +a robust command, even if some code within the \m{definition} is +fragile. You can use this command to define new robust commands, or +to redefine existing commands and make them robust. A log is put into +the transcript file if a command is redefined. + +For example, if |\seq| is defined as follows: +\begin{verbatim} + \DeclareRobustCommand{\seq}[2][n]{% + \ifmmode + #1_{1}\ldots#1_{#2}% + \else + \PackageWarning{fred}{You can't use \protect\seq\space in text}% + \fi + } +\end{verbatim} +Then the command |\seq| can be used in moving arguments, even though +|\ifmmode| cannot, for example: +\begin{verbatim} + \section{Stuff about sequences $\seq{x}$} +\end{verbatim} + +Note also that there is no need to put a |\relax| before the +|\ifmmode| at the beginning of the definition; this is because the +protection given by this |\relax| against expansion at the wrong time +will be provided internally. + +\begin{decl} + |\CheckCommand| \arg{cmd} \oarg{num} \oarg{default} + \arg{definition}\\ + |\CheckCommand*| \arg{cmd} \oarg{num} \oarg{default} + \arg{definition} +\end{decl} +This takes the same arguments as |\newcommand| but, rather than define +\m{cmd}, it just checks that the current definition of \m{cmd} is +exactly as given by \m{definition}. An error is raised if these +definitions differ. + +This command is useful for checking the state of the system before +your package starts altering the definitions of commands. It allows +you to check, in particular, that no other package has redefined the +same command. + +\subsection{Moving arguments} + +\NEWdescription{1994/12/01} +The setting of protect whilst processing (i.e.~moving) moving arguments +has been reimplemented, as has the method of writing information from +the |.aux| file to other files such as the |.toc| file. Details can +be found in the file |ltdefns.dtx|. + +We hope that these changes will not affect many packages. + +\section{Miscellaneous commands, etc} +\label{Sec:commands.misc} + +\subsection{Layout parameters} + +\begin{decl} +|\paperheight|\\ +|\paperwidth| +\end{decl} +These two parameters are usually set by the class to be the size of +the paper being used. This should be actual paper size, unlike +|\textwidth| and |\textheight| which are the size of the main text +body within the margins. + + +\subsection{Case changing} +\label{sec:case} + +\begin{decl} + |\MakeUppercase| \arg{text} \\ + |\MakeLowercase| \arg{text} +\end{decl} + +\NEWfeature{1995/06/01} +\TeX{} provides two primitives |\uppercase| and |\lowercase| for +changing the case of text. These are sometimes used in document +classes, for example to set information in running heads in all +capitals. + +Unfortunately, these \TeX{} primitives do not change the case of +characters accessed by commands like |\ae| or |\aa|. To overcome this +problem, \LaTeX{} provides two new commands |\MakeUppercase| and +|\MakeLowercase| to do this. + +For example: +\begin{quotation} +\begin{tabular}{rl} + |\uppercase{aBcD\ae\AA\ss\OE}| & \uppercase{aBcD\ae\AA\ss\OE}\\ + |\lowercase{aBcD\ae\AA\ss\OE}| & \lowercase{aBcD\ae\AA\ss\OE}\\ + |\MakeUppercase{aBcD\ae\AA\ss\OE}| & + \MakeUppercase{aBcD\ae\AA\ss\OE}\\ + |\MakeLowercase{aBcD\ae\AA\ss\OE}| & \MakeLowercase{aBcD\ae\AA\ss\OE} +\end{tabular} +\end{quotation} + +The commands |\MakeUppercase| and |\MakeLowercase| themselves are +robust, but they have moving arguments. + +The commands use the \TeX{} primitives |\uppercase| and |\lowercase|, +and so have a number of unexpected `features'. In particular, they +change the case of everything (except characters in the names of +control-sequences) in their text argument: this includes mathematics, +environment names, and label names. + +For example: +\begin{verbatim} + \MakeUppercase{$x+y$ in \ref{foo}} +\end{verbatim} +produces $X+Y$ and the warning: +\begin{verbatim} + LaTeX Warning: Reference `FOO' on page ... undefined on ... +\end{verbatim} +In the long run, we would like to use all-caps fonts rather than any +command like |\MakeUppercase| but this is not possible at the moment +because such fonts do not exist. + +\NEWdescription{1995/12/01} +In order that upper/lower-casing will work reasonably well, and in +order to provide any correct hyphenation, \LaTeXe{} \emph{must} use, +throughout a document, the same fixed table for changing case. +The table used is designed for the font encoding |T1|; this works well +with the standard \TeX{} fonts for all Latin alphabets but will cause +problems when using other alphabets. + +\subsection{The `openany' option in the `book' class} + +\NEWdescription{1996/06/01} +The |openany| option allows chapter and similar openings to +occur on left hand pages. Previously this option affected only +|\chapter| and |\backmatter|. It now also affects +|\part|, |\frontmatter| and |\mainmatter|. + +\subsection{Better user-defined math display environments} + +\begin{decl} + |\ignorespacesafterend| +\end{decl} + +\NEWfeature{1996/12/01} +\NEWdescription{2003/12/01} +Suppose that you want to define an environment for displaying text +that is numbered as an equation. A straightforward way to do this is +as follows: +\begin{verbatim} + \newenvironment{texteqn} + {\begin{equation} + \begin{minipage}{0.9\linewidth}} + {\end{minipage} + \end{equation}} +\end{verbatim} +However, if you have tried this then you will probably have noticed +that it does not work perfectly when used in the middle of a paragraph +because an inter-word space appears at the beginning of the first +line after the environment. + +There is now an extra command (with a very long name) available that +you can use to avoid this problem; it should be inserted as shown here: +\begin{verbatim} + \newenvironment{texteqn} + {\begin{equation} + \begin{minipage}{0.9\linewidth}} + {\end{minipage} + \end{equation} + \ignorespacesafterend} +\end{verbatim} + +This command may also have other uses. + +\subsection{Normalising spacing} + +\begin{decl} + |\normalsfcodes| +\end{decl} + +\NEWfeature{1997/06/01} +This command should be used to restore the normal settings of the +parameters that affect spacing between words, sentences, etc. + +An important use of this feature is to correct a problem, reported by +Donald Arseneau, that punctuation in page headers has always (in all +known \TeX{} formats) been potentially wrong whenever a page break +happens while a local setting of the space codes is in effect. These +space codes are changed by, for example, the command +\verb|\frenchspacing|) and the \textsf{verbatim} environment. + +It is normally given the correct definition automatically in +|\begin{document}| and so need not be explicitly set; however, if it +is explicitly made nonempty in a class file then automatic +default setting will be over-ridden. + + +\section{Upgrading \LaTeX~2.09 classes and packages} +\label{Sec:upgrade} + +This section describes the changes you may need to make when you +upgrade an existing \LaTeX{} style to a package or class but we shall +start in optimistic mode. + +Many existing style files will run with \LaTeXe{} without any +modification to the file itself. When everything is running OK, +please put a note in the newly created package or class file to record +that it runs with the new standard \LaTeX{}; then distribute it to +your users. + +\subsection{Try it first!} +\label{Sec:try-it} + +The first thing you should do is to test your style in `compatibility +mode'. The only change you need to make in order to do this is, +possibly, to change the extension of the file to |.cls|: you should +make this change only if your file was used as a main document style. +Now, without any other modifications, run \LaTeXe{} on a document that +uses your file. This assumes that you have a suitable collection of +files that tests all the functionality provided by your style file. +(If you haven't, now is the time to make one!) + +You now need to change the test document files so that they are +\LaTeXe{} documents: see \emph{\usrguide} for details of how to do +this and then try them again. You have now tried the test documents +in both \LaTeXe{} native mode and \LaTeX~2.09 compatibility mode. + +\subsection{Troubleshooting} +\label{Sec:trouble} + +If your file does not work with \LaTeXe{}, there are two likely +reasons. +\begin{itemize} +\item \LaTeX{} now has a robust, well-defined designer's interface for + selecting fonts, which is very different from the \LaTeX~2.09 + internals. +\item Your style file may have used some \LaTeX~2.09 internal commands + which have changed, or which have been removed. +\end{itemize} + +When you are debugging your file, you will probably need more +information than is normally displayed by \LaTeXe. This is achieved +by resetting the counter |errorcontextlines| from its default value of +$-1$ to a much higher value, e.g.~999. + +\subsection{Accommodating compatibility mode} + +Sometimes an existing collection of \LaTeX~2.09 documents makes it +inconvenient or impossible to abandon the old commands entirely. +If this is the case, then it is possible to accommodate both conventions +by making special provision for documents processed in compatibility +mode. + +\begin{decl} +|\if@compatibility| +\end{decl} +This switch is set when a document begins with |\documentstyle| rather +than |\documentclass|. Appropriate code can be supplied for either +condition, as follows: +\begin{verbatim} + \if@compatibility + <code emulating LaTeX 2.09 behavior> + \else + <code suitable for LaTeX2e> + \fi +\end{verbatim} + + +\subsection{Font commands} + +Some font and size commands are now defined by the document class +rather than by the \LaTeX{} kernel. If you are upgrading a +\LaTeX~2.09 document style to a class that does not load one of the +standard classes, then you will probably need to add definitions for +these commands. + +\begin{decl} + |\rm| |\sf| |\tt| |\bf| |\it| |\sl| |\sc| +\end{decl} +None of these short-form font selection commands are defined in the +\LaTeXe{} kernel. They are defined by all the standard class files. + +If you want to define them in your class file, there are several +reasonable ways to do this. + +One possible definition is: +\begin{verbatim} + \newcommand{\rm}{\rmfamily} + ... + \newcommand{\sc}{\scshape} +\end{verbatim} +This would make the font commands orthogonal; for example +|{\bf\it text}| would produce bold italic, thus: \textbf{\textit{text}}. +It will also make them produce an error if used in math mode. + +Another possible definition is: +\begin{verbatim} + \DeclareOldFontCommand{\rm}{\rmfamily}{\mathrm} + ... + \DeclareOldFontCommand{\sc}{\scshape}{\mathsc} +\end{verbatim} +This will make |\rm| act like |\rmfamily| in text mode (see above) and +it will make |\rm| select the |\mathrm| math alphabet in math mode. + +Thus |${\rm math} = X + 1$| will produce `${\rm math} = X + 1$'. + +If you do not want font selection to be orthogonal then you can +follow the standard classes and define: +\begin{verbatim} + \DeclareOldFontCommand{\rm}{\normalfont\rmfamily}{\mathrm} + ... + \DeclareOldFontCommand{\sc}{\normalfont\scshape}{\mathsc} +\end{verbatim} +This means, for example, that |{\bf\it text}| will produce medium +weight (rather than bold) italic, thus: \textit{text}. + +\begin{decl} + |\normalsize| \\ + |\@normalsize| +\end{decl} +The command |\@normalsize| is retained for compatibility with +\LaTeX~2.09 packages which may have used its value; but redefining it +in a class file will have no effect since it is always reset to have +the same meaning as |\normalsize|. + +This means that classes \emph{must} now redefine |\normalsize| rather +than redefining |\@normalsize|; for example (a rather incomplete one): +\begin{verbatim} + \renewcommand{\normalsize}{\fontsize{10}{12}\selectfont} +\end{verbatim} +Note that |\normalsize| is defined by the \LaTeX{} kernel to be an +error message. + +\begin{decl} + |\tiny| |\footnotesize| |\small| |\large|\\ + |\Large| |\LARGE| |\huge| |\Huge| +\end{decl} +None of these other `standard' size-changing commands are defined in +the kernel: each needs to be defined in a class file if you need it. +They are all defined by the standard classes. + +This means you should use |\renewcommand| for |\normalsize| and +|\newcommand| for the other size-changing commands. + + +\subsection{Obsolete commands} + +Some packages will not work with \LaTeXe{}, normally because they relied +on an internal \LaTeX{} command which was never supported and has now +changed, or been removed. + +In many cases there will now be a robust, high-level means of +achieving what previously required low-level commands. Please consult +Section~\ref{Sec:commands} to see if you can now use the \LaTeXe{} +class and package writers commands. + +Also, of course, if your package or class redefined any of the kernel +commands (i.e.~those defined in the files |latex.tex|, |slitex.tex|, +|lfonts.tex|, |sfonts.tex|) then you will need to check it very +carefully against the new kernel in case the implementation has +changed or the command no longer exists in the \LaTeX2e{} kernel. + +Too many of the internal commands of \LaTeX~2.09 have been +re-implemented or removed to be able to list them all here. You must +check any that you have used or changed. + +We shall, however, list some of the more important commands which are +no longer supported. + +\begin{decl} + |\tenrm| |\elvrm| |\twlrm| \dots\\ + |\tenbf| |\elvbf| |\twlbf| \dots\\ + |\tensf| |\elvsf| |\twlsf| \dots\\ + \qquad$\vdots$ +\end{decl} +The (approximately) seventy internal commands of this form are no longer +defined. If your class or package uses them then \emph{please} +replace them with new font commands described in \emph{\fntguide}. + +For example, the command |\twlsf| should be replaced by: +\begin{verbatim} + \fontsize{12}{14}\normalfont\sffamily\selectfont +\end{verbatim} + +Another possibility is to use the |rawfonts| package, described in +\emph{\usrguide}. + +Also, remember that many of the fonts preloaded by \LaTeX~2.09 +are no longer preloaded. + +\begin{decl} + |\vpt| |\vipt| |\viipt| \dots +\end{decl} +These were the internal size-selecting commands in \LaTeX~2.09. +(They can still be used in \LaTeX~2.09 compatibility mode.) +Please use the command |\fontsize| instead: see \emph{\fntguide} for +details. + +For example, |\vpt| should be replaced by: +\begin{verbatim} + \fontsize{5}{6}\normalfont\selectfont +\end{verbatim} + +\begin{decl} + |\prm|, |\pbf|, |\ppounds|, |\pLaTeX| \dots +\end{decl} +\LaTeX~2.09 used several commands beginning with |\p| in order to +provide `protected' commands. For example, |\LaTeX| was defined to be +|\protect\pLaTeX|, and |\pLaTeX| was defined to produce the \LaTeX{} +logo. This made |\LaTeX| robust, even though |\pLaTeX| was not. + +These commands have now been reimplemented using +|\DeclareRobustCommand| +(described in Section~\ref{Sec:commands.define}). +If your package redefined one of the |\p|-commands then you must +remove the redefinition and use |\DeclareRobustCommand| to redefine the +non-|\p| command. + +\begin{decl} +|\footheight|\\ +|\@maxsep|\\ +|\@dblmaxsep| +\end{decl} +These parameters are not used by \LaTeXe{} so they have been removed, +except in \LaTeX~2.09 compatibility mode. Classes should no longer +set them. + +\begin{thebibliography}{1} + +\bibitem{A-W:DEK91} +Donald~E. Knuth. +\newblock {\em The \TeX book}. +\newblock Addison-Wesley, Reading, Massachusetts, 1986. +\newblock Revised to cover \TeX3, 1991. + +\bibitem{A-W:LLa94} +Leslie Lamport. +\newblock {\em {\LaTeX:} A Document Preparation System}. +\newblock Addison-Wesley, Reading, Massachusetts, second edition, 1994. + +\bibitem{A-W:MG2004} +Frank Mittelbach and Michel Goossens. +\newblock {\em The {\LaTeX} Companion second edition}. +\newblock With Johannes Braams, David Carlisle, and Chris Rowley. +\newblock Addison-Wesley, Reading, Massachusetts, 2004. + +\end{thebibliography} + +\newpage +\thispagestyle{empty} + +\section*{\LaTeXe{} Summary sheet: updating old styles} + +Section references below are to \emph{\clsguide}. + +\begin{enumerate} + +\item Should it become a class or a package? + See Section~\ref{Sec:classorpkg} for how to answer this question. + +\item If it uses another style file, then you will need to obtain an + updated version of this other file. Look at Section~\ref{Sec:loading} + for information on how to load other class and package files. + +\item Try it: see Section~\ref{Sec:try-it}. + +\item It worked? Excellent, but there are probably still some things + you should change in order to make your file into a well-structured + \LaTeXe{} file that is both robust and portable. So you should now + read Section~\ref{Sec:writing}, especially~\ref{Sec:general}. You + will also find some useful examples in Section~\ref{Sec:structure}. + + If your file sets up new fonts, font-changing commands or symbols, + you should also read \emph{\fntguide}. + +\item It did not work? There are three possibilities here: + \begin{itemize} + \item error messages are produced whilst reading your file; + \item error messages are produced whilst processing test documents; + \item there are no errors but the output is not as it should be. + \end{itemize} + Don't forget to check carefully for this last possibility. + + If you have got to this stage then you will need to read + Section~\ref{Sec:upgrade} to find the solutions that will make your + file work. +\end{enumerate} + +\end{document} + diff --git a/macros/latex-dev/doc/cyrguide.pdf b/macros/latex-dev/doc/cyrguide.pdf new file mode 100644 index 0000000000..62d6037839 Binary files /dev/null and b/macros/latex-dev/doc/cyrguide.pdf differ diff --git a/macros/latex-dev/doc/cyrguide.tex b/macros/latex-dev/doc/cyrguide.tex new file mode 100644 index 0000000000..4080fcb617 --- /dev/null +++ b/macros/latex-dev/doc/cyrguide.tex @@ -0,0 +1,398 @@ +% \iffalse meta-comment +% +% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 +% The LaTeX3 Project and any individual authors listed elsewhere +% in this file. +% +% This file is part of the LaTeX base system. +% ------------------------------------------- +% +% 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 +% 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 file has the LPPL maintenance status "maintained". +% +% The list of all files belonging to the LaTeX base distribution is +% given in the file `manifest.txt'. See also `legal.txt' for additional +% information. +% +% The list of derived (unpacked) files belonging to the distribution +% and covered by LPPL is defined by the unpacking scripts (with +% extension .ins) which are part of the distribution. +% +% \fi +\NeedsTeXFormat{LaTeX2e}[1995/12/01] + +\documentclass{ltxguide}[1999/02/28] + +\title{Cyrillic languages support in \LaTeX} + +\author{\copyright~Copyright 1998--1999,\\ Vladimir Volovich, + Werner Lemberg and \LaTeX3 Project Team.\\ All rights reserved.} + +\date{12 March 1999} + +\begin{document} + +\maketitle +\tableofcontents + +\begin{abstract} + This document contains basic information on the Cyrillic setup for + \LaTeX{}: how to get the fonts, how to set them up, how to use + the interface, its interaction with \babel{}, etc. This is only a first + draft of the document and it will probably be modified in future; so + please send in comments on it via the \texttt{latexbug} system + (see below). +\end{abstract} + + +\section{Introduction} + +Most Latin-based European languages were supported in \LaTeX{} by +introducing the~|T1|~font encoding and by using the \textsf{fontenc} +and \textsf{inputenc} packages; these use only standard \TeX{} means +to support any \mbox{8-bit} input encoding and this one standard font +encoding. The restriction to a single font encoding guarantees that +multiple languages can happily coexist in one document (\eg +hyphenation will be correct for all languages). + +Starting with the December~1998 Release, \LaTeX{} finally supports +Cyrillic languages. This support is based on the new standard +Cyrillic \TeX{} font encodings---|T2A|, |T2B|, |T2C|, and~|X2|. The +first three of these satisfy some basic requirements for +\LaTeX{}~|T*|~encodings, and thus can be used in multi-lingual documents +with other languages based on standard font encodings. + +The reason why we need four different Cyrillic font encodings is that +these font encodings support \emph{all} the Cyrillic languages that +have been used during the twentieth century (see +Section~\ref{fontencs})! The number of Cyrillic glyphs is large, so +they cannot be represented with 128~character slots; the other (lower) +128~slots are reserved for Latin letters and other invariant symbols +that are needed for the encoding to be a conformant +\LaTeX{}~\texttt{T}~encoding. + +There are some glyphs in the |T2*|~encodings which do not yet have +associated characters in \emph{Unicode}, the world-wide character +standard. Also, one more font encoding, |T2D|,~is planned for a +forthcoming release of \LaTeX{}. A lot of Cyrillic input encodings +are already supported (see Section~\ref{inputencs}), and additional +encodings could be added easily. + + +\subsection{Acknowledgments} +\label{sec:acks} + +The work on |T2*|~encodings was carried out by the T2~Team, led by +Alexander Berdnikov (other members are Mikhail Kolodin and Andrew +Janishewskii). The LH~fonts were produced by Olga Lapko (with +A.~Khodulev). The \textsf{T2} bundle and \textsf{ruhyphen} package +were written by Werner Lemberg and Vladimir Volovich (except that the +concrete hyphenation patterns which are part of \textsf{ruhyphen} came +from individual authors). The support for the Ukrainian language was +prepared by Andrij Shvaika. + + +\section{Installation} + +The \textsf{fontenc} and \textsf{inputenc} packages are installed +automatically in every base \LaTeX{} distribution. + +All the necessary extra files to use with these packages for Cyrillic +are in the \textsf{cyrillic} bundle, which at present contains the +following: four font encoding definition files (|t2aenc.def|, +|t2benc.def|, |t2cenc.def|, |x2enc.def|); several input encoding +definition files (all the other |*.def| files), and font definition +files (|*.fd|). +The installation of these is described here. + +\subsection{Fonts} + +The default font families in \LaTeX{} are the Computer Modern +families, namely the CM~fonts (|OT1|~encoded) and the EC~fonts +(|T1|~encoded). The LH~fonts, which are now available, provide +Computer Modern fonts for all Cyrillic font encodings. They are +designed to be compatible with the EC~fonts, and they provide the same +font shapes and sizes; they are available at |CTAN:fonts/cyrillic/lh| +(the latest version is 3.20). The installation instructions for the +fonts are in the file |INSTALL| in the font distribution. + +Other fonts, including Type~1 fonts, can also be used, provided that +their encoding (for \TeX{}) is \mbox{|T2|-compatible}. Some +ready-to-use packages supporting such fonts are also available, \eg at +\URL{ftp://ftp.vsu.ru/pub/tex} (they should soon be on \ctan). Currently, +you will find two packages there: \textsf{PsCyr}, which contains some +freely distributable Cyrillic Type~1 fonts with support for \LaTeX{}; +and \textsf{c1fonts}, which contains virtual fonts similar to the +\textsf{AE}~fonts package using the BlueSky and BaKoMa fonts +available from \ctan{} (see the |README| file in that package for +detailed information). Further font packages are expected soon. + +\subsection{Hyphenation patterns} + +You can find a collection of hyphenation patterns for the Russian +language in the \textsf{ruhyphen} package at +|CTAN:language/hyphenation/ruhyphen|. These patterns support the +|T2*|~encodings, as well as other popular font encodings used for +Russian typesetting (including the Omega internal encoding). +Patterns for other Cyrillic languages should be adapted to work with +the |T2*|~encodings. + +\subsection{\babel{} support for Russian and Ukrainian} +\label{bblrus} + +Version~3.6k of \babel{} includes support for the |T2*|~encodings and +for typesetting both Russian and Ukrainian texts using the Cyrillic +letters. The temporary fontencoding |LWN|, which was used in earlier +releases of \babel{}, will be withdrawn in the near future and replaced +by the |OT2| encoding. + +\subsection{Getting pre-built packages} + +Many of the major \TeX{} distributions, such as te\TeX{}, fp\TeX{} and +\TeX{}live, contain (or soon will) everything that is needed, +including the LH~fonts, \textsf{ruhyphen} and the latest version of +\babel{}. We hope that all \TeX{} distributions will soon include all +of these, so that the chances are that you will not need to install +this by yourself (but it is not difficult). + +If you are using em\TeX, Mik\TeX, or fp\TeX, you +can download the \textsf{ruemtex} package from +\URL{ftp://ftp.vsu.ru/pub/tex}. + +\section{Usage} + +Support for Cyrillic is based on these standard \LaTeX{} mechanisms: +the \textsf{fontenc} and \textsf{inputenc} packages (and on \babel{}). +Thus the basic principles for its use are similar to those for other +European languages: you simply add, to your document preamble, lines +like the following. + +\begin{verbatim} +\usepackage[T2A]{fontenc} +\usepackage[koi8-r]{inputenc} +\end{verbatim} + +Here you can put any desired input encoding instead of +\mbox{\texttt{koi8-r}}: for example, it would be \texttt{cp866} if you are +using a MS-DOS text editor with this Cyrillic code page to prepare your +documents, or \texttt{cp1251} if you are a MS~Windows user with Cyrillic +support. A full list of the available Cyrillic encodings can be found in +Section~\ref{inputencs} and in the file |cyinpenc.dtx|. + +Documents are, naturally, not restricted to a single font encoding; +this is essential for multi-lingual journals or documents. Such +changes can be made by using the |\fontencoding| command as part of a +font-change. However, it is best to access these font encodings via a +higher-level interface. + +Since such changes are often closely related to other +language-dependent settings, it is often sensible to use the \babel{} +system, which provides further useful `localisation' and standardised +multi-lingual interfaces (for further details, see +Section~\ref{bblrus}). Then you can use lines like the following in +your document: + +\begin{verbatim} +\usepackage[koi8-r]{inputenc} +\usepackage[russian]{babel} +\end{verbatim} + +This will automatically choose the default font encoding for Russian, +which is |T2A|, if available. Documentation of the complete set of +font-encoding selection rules can be found in |cyrillic.dtx| which is +part of |rusbabel|. + +These \LaTeX{} interfaces are very convenient because they make your +documents completely portable, being based solely on standard \TeX{} +features. This will mean that your documents can be processed on any +\TeX{} system without any need for re-encoding to the `native' +encoding used on each platform; this is because the encoding of the +document is specified in the document itself. + +Moreover, if necessary, more than one input encoding can be used +within a document; this could be useful if, for example, you need to +combine articles prepared by authors on different machines. Each part +of the document is then identified by a |\inputencoding| command, +which can therefore only be used between paragraphs. + +Please note that you must always use the two standard \LaTeX{} +commands, |\MakeUppercase| and |\MakeLowercase| to produce uppercase +or lowercase text in your documents. This is because |\uppercase| and +|\lowercase| will not work at all for Cyrillic (note that these latter +two commands are not, and never have been, available for use directly +in \LaTeX{} documents). + + +\section{Font encodings for Cyrillic languages} +\label{fontencs} + +The Cyrillic font encodings support the following languages. Note +that some languages can be properly typeset with more than one +encoding. + +\begin{itemize} +\raggedright +\item[|T2A|:] + Abaza, Avar, Agul, Adyghei, Azerbaijani, Altai, Balkar, Bashkir, + Bulgarian, Buryat, Byelorussian, Gagauz, Dargin, Dungan, Ingush, + Kabardino-Cherkess, Kazakh, Kalmyk, Karakalpak, Karachaevskii, + Karelian, Kirghiz, Komi-Zyrian, Komi-Permyak, Kumyk, Lak, Lezghin, + Macedonian, Mari-Mountain, Mari-Valley, Moldavian, Mongolian, + Mordvin-Moksha, Mordvin-Erzya, Nogai, Oroch, Osetin, Russian, Rutul, + Serbian, Tabasaran, Tadzhik, Tatar, Tati, Teleut, Tofalar, Tuva, + Turkmen, Udmurt, Uzbek, Ukrainian, Hanty-Obskii, Hanty-Surgut, + Gipsi, Chechen, Chuvash, Crimean-Tatar. +\item[|T2B|:] + Abaza, Avar, Agul, Adyghei, Aleut, Altai, Balkar, Byelorussian, + Bulgarian, Buryat, Gagauz, Dargin, Dolgan, Dungan, Ingush, Itelmen, + Kabardino-Cherkess, Kalmyk, Karakalpak, Karachaevskii, Karelian, + Ketskii, Kirghiz, Komi-Zyrian, Komi-Permyak, Koryak, Kumyk, Kurdian, + Lak, Lezghin, Mansi, Mari-Valley, Moldavian, Mongolian, + Mordvin-Moksha, Mordvin-Erzya, Nanai, Nganasan, Negidal, Nenets, + Nivh, Nogai, Oroch, Russian, Rutul, Selkup, Tabasaran, Tadzhik, + Tatar, Tati, Teleut, Tofalar, Tuva, Turkmen, Udyghei, Uigur, Ulch, + Khakass, Hanty-Vahovskii, Hanty-Kazymskii, Hanty-Obskii, + Hanty-Surgut, Hanty-Shurysharskii, Gipsi, Chechen, Chukcha, Shor, + Evenk, Even, Enets, Eskimo, Yukagir, Crimean Tatar, Yakut. +\item[|T2C|:] + Abkhazian, Bulgarian, Gagauz, Karelian, Komi-Zyrian, Komi-Permyak, + Kumyk, Mansi, Moldavian, Mordvin-Moksha, Mordvin-Erzya, Nanai, + Orok (Uilta), Negidal, Nogai, Oroch, Russian, Saam, Old-Bulgarian, + Old-Russian, Tati, Teleut, Hanty-Obskii, Hanty-Surgut, Evenk, + Crimean Tatar. +\end{itemize} + +The |X2|~encoding was designed to support all the above languages. +Its name does not start with |T| because, for example, it contains no +Latin letters (it is purely a Cyrillic glyph container); it therefore +cannot be used in mixed-script documents along with the other |T*| +encodings. Please consult Section~6.4 \textit{Naming conventions} of +the file |fntguide.tex| in the base \LaTeX{} distribution for details +of the differences between \LaTeX{} font encodings and how they are +named. + +There are two other \LaTeX{} Cyrillic font encodings, |OT2| and |LCY|, +that are not included in the base \LaTeX{} distribution. The first is +a \mbox{7-bit} encoding (hence the |O|) developed by the AMS; it is +useful for typesetting relatively small fragments of text in Cyrillic, +using a Latin transliteration scheme. The other, |LCY|, is an +\mbox{8-bit} Cyrillic encoding which is not compatible with the +requirements for \LaTeX{} |T*|~encodings (hence the |L|); thus it is not +suitable for typesetting multi-lingual documents, but it can be used in +Plain \TeX{}-based macro packages because it is an extension of |OT1|. +These two encodings are supported by \babel{} and by \textsf{ot2cyr}. + + +\section{Input encodings} +\label{inputencs} + +Several Cyrillic code-pages are widely used. Currently, \LaTeX{} +contains support for 20~Cyrillic input encodings (some of which are +variants of each other). + +\begin{itemize} + +\item |cp855| --- the standard \mbox{MS-DOS} Cyrillic code-page. + +\item |cp866| --- the standard \mbox{MS-DOS} Russian code-page. + Several code-pages very similar to this are also supported + (the differences are all in the range 242--254). + \begin{itemize} + \item |cp866av| -- the `Cyrillic Alternative' code-page (an + alternative variant of cp866); + \item |cp866mav| -- the `Modified Alternative Variant'; + \item |cp866nav| -- the `New Alternative Variant'; + \item |cp866tat| -- an experimental Tatarian code-page. + \end{itemize} + +\item |cp1251| --- the standard MS Windows Cyrillic code-page. + +\item \mbox{\texttt{koi8-r}} --- a standard Cyrillic code-page widely + used in UNIX-like systems for Russian language support that is + specified in RFC~1489. The situation with \mbox{\texttt{koi8-r}} is + somewhat similar to that for |cp866|: there are several similar + code-pages which coincide for all Russian letters but add some other + Cyrillic letters. The following are supported: + \begin{itemize} + \item \mbox{\texttt{koi8-u}} -- for Ukrainian; + \item \mbox{\texttt{koi8-ru}} -- this is described in a draft RFC + document specifying a widely used character set for mail and news + exchange in the Ukrainian internet community, as well as for + presenting WWW information resources in the Ukrainian language; + \item |isoir111| -- the \mbox{ISO-IR-111 ECMA} Cyrillic Code Page. + \end{itemize} + +\item |iso88595| --- the \mbox{ISO 8859-5} Cyrillic code-page (also called + \mbox{ISO-IR-144}). + +\item |maccyr| --- the Apple Macintosh Cyrillic code-page (also known + as Microsoft cp10007) and |macukr|, the Apple Macintosh Ukrainian + code-page, very similar to the Cyrillic code-page. + +\item The Mongolian code-pages: |ctt| |dbk| |mnk| |mos| |ncc| |mls|. + These code-pages were taken from Oliver Corff's `Mon\TeX' package + (available at |CTAN:language/mongolian/montex|). Since the |T2*| + encodings support the Mongolian Cyrillic script, it is convenient to + have support for Mongolian input encodings as well. Pointers to + documentation for these code-pages will be much appreciated. + +\end{itemize} + + +\section{Reporting bugs} + +In case you find a bug and want to report it, please follow the +guidelines given in the file |bugs.txt| in the base \LaTeX{} +distributions. Note that there is a category specifically for +reporting any bugs that occur only when using Cyrillic fonts or +support packages. + + +\section{Miscellanea in the \textsf{T2} bundle} +\label{t2m} + +The \textsf{T2}~bundle at |CTAN:macros/latex/contrib/supported/t2| +contains some other useful files, including support for Plain +\TeX{}-based macro packages, support for Bib\TeX{} and MakeIndex (see +also the \textsf{xindy} program and package---highly recommended for +making indices with Cyrillic), support for the \textsf{fontinst} +package, mapping tables relating these Cyrillic font encodings (and +input encodings) to the Unicode character names and slots (these are +in the subdirectory |enc-maps|), and more! + +To produce documented source listings of the \textsf{T2}~package, run +\LaTeX{} on the |*.dtx| and |*.fdd| files therein. + +When typesetting Cyrillic texts, there is a tradition of using +Cyrillic letters (in some situations) within math formul\ae, in +exactly the same way as most of the world uses Latin letters. +By default this does not work, because symbols declared with +|\DeclareTextSymbol| may not be used in math. + +If you need within math to `transparently' typeset glyphs declared in +font encoding definition files, then you could try using the +experimental \textsf{mathtext} package, which is also in the +\textsf{T2}~bundle. Note that this package uses up at least one +additional math alphabet per font encoding. For this and other +reasons, The \LaTeX3 Project Team considers that this experimental +extension to \LaTeX{}'s glyph-handling mechanisms should be used with +caution; but please try it out and send us your opinions and ideas. +Note that it is not included in the core of \LaTeX{} because both the +coding and the interfaces are likely to change at some point in the +future. + +Finally, here are some pointers to further information: + +\begin{quote} + \URL{http://www.cemi.rssi.ru/cyrtug}\\ + \URL{http://xtalk.price.ru/tex} +\end{quote} + +\end{document} diff --git a/macros/latex-dev/doc/encguide.pdf b/macros/latex-dev/doc/encguide.pdf new file mode 100644 index 0000000000..dd13622c48 Binary files /dev/null and b/macros/latex-dev/doc/encguide.pdf differ diff --git a/macros/latex-dev/doc/encguide.tex b/macros/latex-dev/doc/encguide.tex new file mode 100644 index 0000000000..96ed7edf6f --- /dev/null +++ b/macros/latex-dev/doc/encguide.tex @@ -0,0 +1,1481 @@ +% \iffalse meta-comment +% +% Copyright 1993-2016 +% The LaTeX3 Project and any individual authors listed elsewhere +% in this file. +% +% This file is part of the LaTeX base system. +% ------------------------------------------- +% +% 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 +% 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 file has the LPPL maintenance status "maintained". +% +% The list of all files belonging to the LaTeX base distribution is +% given in the file `manifest.txt'. See also `legal.txt' for additional +% information. +% +% The list of derived (unpacked) files belonging to the distribution +% and covered by LPPL is defined by the unpacking scripts (with +% extension .ins) which are part of the distribution. +% +% \fi +% + + +\NeedsTeXFormat{LaTeX2e}[1995/12/01] + +\documentclass{ltxguide}[1994/11/20] + +\usepackage[T1]{fontenc} +\IfFileExists{lmodern.sty}{\usepackage{lmodern}}{} +\usepackage{textcomp} +\usepackage{url} +\usepackage{mflogo} + +\addtolength\textheight{6\baselineskip} +\addtolength\topmargin{-2\baselineskip} + + +\newcommand\ttverb[1]{\texttt{\string#1}} + + +% for encodings +\providecommand{\Enc}[1]{\texttt{#1}} + +% for packages +\providecommand{\Pkg}[1]{% + \textsf{#1}} + +% for files +\providecommand{\File}[1]{% + \texttt{#1}} + +% let's have meta values too +\providecommand{\meta}[1]{% + \ensuremath{\langle}\emph{#1}\ensuremath{\rangle}} + +\usepackage{tabularx} + +% eine Umgebung zur Darstellung von Kodierungen +% +% Argumente: +% #1: Name in LaTeX (z.B. OT1) +% #2: Name der Kodierung (z.B. TeX text) +% #3: Name des Autors (z.B. Don Knuth) +% #4: Bereich der benützten Glyphindizes +% #5: variable Positionen +% #6: Beispielzeichensatz +% #7: Referenz +% +% XXX add code to handle more than a single font example (e.g., larm1000, +% lbrm1000, and lcrm1000). +% +\newenvironment{encodinginfo}[7]% + {\noindent + \begin{tabularx}{\linewidth}{@{}l>{\raggedright\let\\\tabularnewline}X}% + \LaTeX{} name: & \texttt{#1}\\% + Public name: & #2\\% + Author: & #3\\% + Glyph slots used: & #4\\% + Variable slots: & #5\\% + Font example: & \def\@tempa{#6}\ifx\@tempa\@empty---% + \else\texttt{#6}\referenceftable{#6}\fi\\% + Further reference: & #7% + \end{tabularx}% + \par\nobreak + \vspace*{3pt}% + \quote + }% + {\endquote + \vspace{6pt}} + +\makeatletter +\def\referenceftable#1{ + \@ifundefined{r@fonttable:#1}% + \relax + {;\space encoding table on page~\pageref{fonttable:#1}}% +} + +% font table macros mainly lifted from manmac.tex +\def\oct#1{\hbox{\rm\'{}\kern-.2em\it#1\/\kern.05em}} +\def\hex#1{\hbox{\rm\H{}\tt#1}} + +\def\oddline#1{\cr\noalign{\nointerlineskip} + \multispan{19}\hrulefill& + \setbox0=\hbox{\lower 2.3pt\hbox{\hex{#1x}}}\smash{\box0}\cr + \noalign{\nointerlineskip}} +\def\evenline{\cr\noalign{\hrule}} +\def\chartstrut{\lower4.5pt\vbox to14pt{}} +\def\beginchart#1#2{$$\global\count@=0 #1 + \halign to\hsize\bgroup + \chartstrut##\tabskip0pt plus10pt& + &\hfil##\hfil&\vrule##\cr + \lower6.5pt\null + &&\oct0&&\oct1&&\oct2&&\oct3&&\oct4&&\oct5&&\oct6&&\oct7&\evenline} +\def\endchart{\raise11.5pt\null&&&\hex 8&&\hex 9&&\hex A&&\hex B& + &\hex C&&\hex D&&\hex E&&\hex F&\cr\egroup$$} +\def\:{\setbox0=\hbox{\noboundary\char\count@\noboundary}% + \ifdim\ht0>7.5pt\reposition + \else\ifdim\dp0>2.5pt\reposition\fi\fi + \box0\global\advance\count@ by1 } +\def\reposition{\setbox0=\hbox{$\vcenter{\kern2pt\box0\kern2pt}$}} +\def\normalchart{% + &\oct{00x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\oddline0 + &\oct{01x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&\evenline + &\oct{02x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\oddline1 + &\oct{03x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&\evenline + &\oct{04x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\oddline2 + &\oct{05x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&\evenline + &\oct{06x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\oddline3 + &\oct{07x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&\evenline + &\oct{10x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\oddline4 + &\oct{11x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&\evenline + &\oct{12x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\oddline5 + &\oct{13x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&\evenline + &\oct{14x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\oddline6 + &\oct{15x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&\evenline + &\oct{16x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\oddline7 + &\oct{17x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&\evenline + \top} + +\def\notophalf{} +\def\tophalf{% +%\noalign{\vskip 5pt\hrule} + &\oct{20x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\oddline8 + &\oct{21x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&\evenline + &\oct{22x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\oddline9 + &\oct{23x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&\evenline + &\oct{24x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\oddline A + &\oct{25x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&\evenline + &\oct{26x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\oddline B + &\oct{27x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&\evenline + &\oct{30x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\oddline C + &\oct{31x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&\evenline + &\oct{32x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\oddline D + &\oct{33x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&\evenline + &\oct{34x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\oddline E + &\oct{35x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&\evenline + &\oct{36x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\oddline F + &\oct{37x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&\evenline} + +\def\ftable#1#2{% + \batchmode + \font\X=#1% + \errorstopmode + \ifx\X\nullfont + \@warning{Font #1 not found, table omitted} + \else + \count@="80 + \setbox0=\hbox{\X + \loop\char\count@\advance\count@ by1 \ifnum\count@<"100 + \repeat}% + \ifdim\wd0>0pt \let\top\tophalf\else\let\top\notophalf\fi + \beginchart\X{\hfill\llap{\textbf{#1, \large#2}\label{fonttable:#1}}}\normalchart + \endchart\par\vfill + \fi} +\makeatother + + +\setcounter{tocdepth}{3} + +\title{\LaTeX{} font encodings} + +\author{Frank Mittelbach \and Robin + Fairbairns \and Werner Lemberg \and \LaTeX3 Project Team.} + +\date{\copyright~Copyright 1995--2016 \\[5pt] 18 February 2016} + +\begin{document} + +\maketitle + +\tableofcontents + +\section{Introduction} + +This document explains the ideas that underpin \LaTeX{} font +encodings and the constraints that apply when defining a new encoding; it +also lists the encodings that have already been defined. + +\subsection{Encodings in \TeX{}} + +\TeX{} (the program) implicitly recognises three sorts of encoding, +and all are (in a sense) discussed in the \TeX{}book~\cite{A-W:DKn86}: +\begin{itemize} +\item[1.] The input encoding, which specifies the meanings of characters + in files presented to \TeX{} for processing. The \TeX{}book + suggests that `your version of \TeX{} will recognise the characters + you type on your keyboard' (\TeX{} the program has provision for + static translations of input characters). +\end{itemize} +Such direct use of \TeX{}'s facilities is not the way modern +\LaTeX{} (or indeed any other \TeX{} macro package) is likely to deal +with input encodings. This document does not address the topic of +input encodings; the interested reader should examine the \LaTeX{} +base package \Pkg{inputenc} \cite[sec.~7.5.2, p.~357]{A-W:MG2004}. +\begin{itemize} +\item[2.] The token stream that \TeX{} processes internally. This stream + of \TeX{}'s consciousness is discussed in great detail in the + \TeX{}book. +\end{itemize} +Again, this document does not address the topic. \LaTeX's internal +character representation (\textsc{licr}) is well discussed in +\cite[sec.~7.11.2, p.~442]{A-W:MG2004}. +\begin{itemize} +\item[3.] The font encoding---i.e., the mapping of character codes to + glyphs in the fonts that are used to typeset \TeX{}'s output. + Again, a set of font encodings is enumerated in the \TeX{}book, but + that set has proved inadequate to the needs of modern multilingual + use of \LaTeX. +\end{itemize} +This document explains \emph{why} Knuth's original set of encodings is +inadequate to modern conditions, and discusses the issues that +surround the design and definition of new font encodings. + +Font encodings are important for more than their r\^{o}le in mapping the +glyphs of the fonts to be used for typesetting: their glyph tables are +also the context in which \TeX{}'s hyphenation algorithm operates. +There are constraints imposed by \TeX{} that affect the way in which +new font encodings, for use in a multi-lingual environment, may be +structured (see section~\ref{sec:restrictions} for details). + +\subsection{The history of \TeX{} font encodings} + +Little attention was paid to font encodings prior to the arrival of +\TeX{}\,3. Up to that time, one used Donald Knuth's fonts (the +Computer Modern family, using the encodings we now refer to as \Enc{OT1} and +the \Enc{OM} series), or one was on one's own. + +The Computer Modern text encoding raises problems in unmodified +\TeX{}, because hyphenation cannot break words containing +\verb"\accent" commands. Even in those Western European languages for +which the \Enc{OT1} encoding has symbols for the necessary +\verb"\accent"-based diacritics, this shortcoming ruins typesetting of +running text. + +With the advent of \TeX{}\,3, with its ability to switch between +hyphenation pattern sets, it was clear that the situation could not +continue. Thus a group at the TUG Annual General Meeting in Cork, +Ireland, specified a uniform encoding for 256-glyph fonts, that +contains accented letters and non-\textsc{ascii} letters necessary to +express most Western European languages (and some Eastern European ones) +without recourse to the \verb"\accent" command. + +This ``Cork'' encoding has since been realised in a series of fonts +designed with Metafont, in at least one font series that is available +both in Adobe Type 1 format and in OpenType format, % viz., Latin Modern +and in a number of virtual-font mappings of other font series. + +Since the time of the Cork meeting, much effort has been devoted to +the design of encodings for text fonts to use with \TeX{}, and the +Cork encoding influenced the design of many such encodings. + +Encodings for mathematical fonts have, in contrast, changed little +since Knuth's contributions. A TUG Technical Working Group was +established at the Cork meeting, whose aim was to define a set of +256-glyph encodings to regularise and extend Knuth's originals, using +ideas from several other fonts that had appeared since, and from the +known needs of researchers in mathematics and the mathematical sciences. + +Independently, a first proposal (the so-called \emph{Aston proposal}) was worked +out by Justin Ziegler together with Frank Mittelbach and other members of the +\LaTeX3 project team~\cite{ziegler}. A first implementation of +this propsal was realized by Matthias Clasen und Ulrik +Vieth~\cite{clasen,clasen-vieth}. + +However, the slow progress of these Mathematical encodings has been +overtaken by the addition (in the last decade or so) of a large number +of mathematical symbols to Unicode~\cite{beeton}; one can expect +further changes so that new public mathematical font encodings will +most likely be delayed still further. + + + +\subsection{Further information} + +For a general introduction to \LaTeX, including the new features of +\LaTeXe, you should read \emph{\LaTeXbook}, +Leslie Lamport, Addison Wesley, 2nd~ed, 1994. + +A more detailed description of the new features of \LaTeX, including an +overview of more than 200 packages and nearly 1000 ready to run examples, is +to be found in \emph{\LaTeXcomp{} second edition} by Frank Mittelbach and +Michel Goossens~\cite{A-W:MG2004}. + +The \LaTeX{} project sponsored a report on Mathematical % spelt out in full +font encodings, which +is worth reading for its insight into the problems of defining the way +in which math is used: see~\cite{ziegler,clasen,clasen-vieth}. + +The \LaTeX{} font selection scheme is based on \TeX, which is described +by its developer in \emph{The \TeX book}, Donald E.~Knuth, Addison +Wesley, 1986, revised in 1991 to include the features of \TeX~3. + +For more information about \TeX{} and \LaTeX, please contact your local +\TeX{} Users Group, or the international \TeX{} Users Group +(\url{http://www.tug.org}). + + + +\section{Existing font encodings} + +This section lists the encodings currently assigned; for each +encoding, we list the registered (\LaTeX{}) name, the assigned purpose +of the encoding, and the author. Further details may list the code +positions used in the encoding, the \emph{variable slots} (see below), +an example font (for which a listing will be provided later in the +document if the relevant fonts are present), and a source for further +reference. + +While the characteristic feature of an encoding is that each font +encoded according to the encoding should have the same glyph set, +there are some encodings (notably \Enc{OT1} and its descendants) in +which a few glyph code slots differ in their contents in different +fonts. + +\subsection{Naming conventions} + +Names for encoding schemes are strings of up to three letters (all +upper case) plus digits. + +The \LaTeX3 project reserves the use of encoding names starting with the +following letters: |T| (standard 256-long text encodings), |TS| +(symbols that are designed to extend a corresponding |T| encoding), +|X| (text encodings that do not conform to the strict requirements for +|T| encodings), |M| (standard 256-long mathematical encodings), |S| (other +symbol encodings), |A| (other special applications), |OT| (standard +128-long text encodings), and |OM| (standard 128-long mathematical encodings). + +Please do not use the above starting letters for non-portable +encodings. If new standard encodings emerge then we shall add them in +a later release of \LaTeX. + +Encoding schemes which are local to a site or a system should start +with |L|, experimental encodings intended for wide distribution will +start with |E|, whilst |U| is for Unknown or Unclassified encodings. + +\begin{quote} + \itshape We recommend that new encoding names should not be + introduced unless careful consideration and discussion in the user + community has confirmed the need for the encoding. If encodings have to + change from font to font, a number of problems arise, so it is best to + develop encodings that can be used with a large number of fonts in parallel. + This allows documents to be typeset using different fonts without problems. + + The \Enc{TS1} encoding is a good example of a \emph{bad} encoding (even + though it was developed with the best intentions) as a huge number of fonts + can only implement parts of it. Similarly, the fact that the few sets of + available mathematical fonts (beside Computer Modern Math) nearly + all implement slightly different encodings is a huge source of + problems. Don't add to this if possible! +\end{quote} + + +\subsection{128$^+$ glyph encodings (text)} + +The `OT' series of font encodings start with Donald Knuth's original +text encoding, that used for the text fonts in the earliest releases +of \TeX{} itself. The `O' of the encoding designator may be taken as +signifying `original', or just `old'. + +\begin{encodinginfo}{OT1} + {\TeX{} text} + {Donald Ervin Knuth} + {0x00--0x7F} + {0x0B--0x0F, 0x24, 0x3C, 0x3E, 0x5C, 0x7B--0x7D} +% {0X--'177} +% {'13--'17, '44, '74, '76, '134, '173--'175} + {cmr10} + {\cite[p.427]{A-W:DKn86}} + + Donald Knuth designed his font encoding (and hence his fonts) in a + very different environment from that which now pervades the \TeX{} + world: his (mainframe) computer had very little memory, there was + little experience in (or demand for) for multilingual technical + typesetting, and as a result it was appropriate to sacrifice + uniformity for efficiency. + + Thus Knuth's original fonts differ slightly in some encoded slots: + for example, the glyphs \texttt{\string<}, \texttt{\string>}, + \verb=\=, \verb={=, and \verb=}= are only available in the + typewriter fonts and the \textdollar{} and \textsterling{} signs + share the same position (in different font shapes). + + This means that direct selection of these slots can produce + unpredictable results, e.g., typing \texttt{\string<} or + \verb=\symbol{'74}= in a document can yield `\textquestiondown'. +\end{encodinginfo} + + +\begin{encodinginfo}{OT2} + {UW cyrillic encoding} + {University of Washington} + {0x00--0x7F} + {---} + {wnr10} + {\cite{Beeton:TB6-3-124}} + Support for this encoding is available in the Cyrillic bundle although for + all practical purposes it is better to use one of the \Enc{T2} encodings. +\end{encodinginfo} + + +\begin{encodinginfo}{OT3} + {UW IPA encoding} + {University of Washington} + {0x00--0x7f} + {---} + {wsuipa10} + {\cite[p.149]{CorkGW:91}} + The \Enc{OT3} encoding was never really used with \LaTeXe{} + following the introduction of the TIPA system which offers much + better support for IPA. In particular, no \File{ot3enc.def} + file was ever produced. +\end{encodinginfo} + + +\begin{encodinginfo}{OT4} + {Polish text encoding} + {B.~Jackowski and M.~Ry\'cko} %% ? Marcin Woli\'nski + {0x00--0x7F, 0x81, 0x82, 0x86, 0x8A, 0x8B, 0x91, 0x99, 0x9B, 0xA1, + 0xA2, 0xA6, 0xAA, 0xAB, 0xAE, 0xAF, 0xB1, 0xB9, 0xBB, 0xD3, 0xF3, + 0xFF} + {0x0B--0x0F, 0x24, 0x3C, 0x3E, 0x5C, 0x7B--0x7D} + {plr10} + {---} + + While Knuth included the means of typesetting the `lost L' (\L) in + his \Enc{OT1} encoding, he omitted the ogonek (\,\,\k{}), a diacritic + mark that is also needed in Polish text; hence the appearance, well + before the \Enc{T1} encoding, of fonts using this encoding. +\end{encodinginfo} + +\begin{encodinginfo}{OT5} + {Not currently allocated} + {---} + {---} + {---} + {} + {---} + +\end{encodinginfo} + + + +\begin{encodinginfo}{OT6} + {Armenian text encoding} + {Serguei Dachian} + {0x03--0x0F, 0x13--0x7F} + {---} + {artmr10} + {---} + + This encoding was allocated to permit use of Dachian's + Armenian fonts in a standard \LaTeX{} environment. + + Because of license issues the \texttt{artmr} fonts are not necessarily + included in distributed \TeX{} installations (and for this reason the + corresponding encoding table is not shown below). However, the fonts + and the support macros can be found on the CTAN archives (look for + \texttt{armtex}). + +\end{encodinginfo} + + + +\subsection{256 glyph encodings (text)} + +\begin{encodinginfo}{T1} + {Cork encoding} + {Euro \TeX{} conference at Cork} + {0x00--0xFF} + {---} + {ecrm1000} + {\cite[p.514]{tub:MFe90}, \cite[p.99]{Knappen:TB17-2-96}} + + The Cork encoding was developed so that advantage could be taken of + the (then) new facilities of \TeX{}\,3, allowing hyphenation of + most Western European (and some Eastern European) languages in an + unmodified version of \TeX{}. + + The encoding was developed in the absence of any extant effort at + font design, but instances written in Metafont (the `EC' fonts), and + more recently Adobe Type 1 instances of the same fonts have become + available. + + Substantial (but incomplete) instances have also been developed, + which use virtual fonts. These latter instances map either Knuth's + original (OT1-encoded) fonts, or commercial fonts that contain the + Adobe `standard' set of 224 glyphs. +\end{encodinginfo} + +\begin{encodinginfo} + {T2A, T2B, T2C} + {Cyrillic encodings} + {The CyrTUG font team} + {0x00--0xFF} + {--- (within each encoding)} + {larm1000} + {\cite{Berdnikov:eurotex-98}} + + There are too many glyphs in the full Cyrillic complement of + languages for all of them to be covered by a single + \LaTeX{}-compliant encoding (the lower half of each + \Enc{T2}~encoding is identical to that of \Enc{T1}, in order that + each should be a conforming \LaTeX{} encoding~--- see + section~\ref{sec:restrictions}). The approach taken is + therefore to develop a single encoding, \Enc{X2} (see \ref{sec:extendedenc}) + which contains all the glyphs needed for the full set of + languages, and then to derive the three \LaTeX{}-complaint + \Enc{T2}-family encodings using the \Enc{X2} set together with that of + \Enc{T1}. + +\end{encodinginfo} + + + +\begin{encodinginfo}{T3} + {IPA encoding} + {FUKUI Rei, University of Tokyo} + {0x00--0xFF} + {---} + {tipa10} + {\cite[p.102]{Rei:TB17-2-102}} + + + The \Enc{T3} encoding (and associated macros) provides the glyphs required + in phonetic description according to current International Phonetic + Association recommendations \cite{ipa}. + + The \Enc{T3} encoding does \emph{not fulfil} the requirements for \Enc{T} + encodings---the name is a historical accident. The correct name would be + \Enc{X3}, but due to the fact that this font family has been used under its + current encoding name for a long time, the name will not change for + compatibility reasons. + +\end{encodinginfo} + + + +\begin{encodinginfo}{T4} + {African Latin (fc)} % public name + {J\"org Knappen} % author name + {0x00--0xFF} % range(s) of slots used for glyphs + {0x24} % range(s) of slots with variable glyphs if any + {fcr10} % name of an example font + {\cite{tub:JKn93}} + +The African Latin fonts contain in their lower half (0--127) the same +characters as the European Latin (T1-encoded) Fonts, while in their +upper half (128--255) they +contain letters and symbols for African languages that use extended +Latin alphabets. +Due to lack of space, J\"org had to play the unfortunate trick of +assigning \verb=\textdollar= and \verb=\textsterling= +the same position; users should take these characters +from the text companion font, if they are needed. Instead of defining +a lot of new control sequences for the single letters, there are three +accent-like control sequences with general purpose: +\verb=\m= (Modified-1), +\verb=\M= (Modified-2) and +\verb=\B= (Barred). +Most standard \LaTeX{} encoding-dependent commands +work. However, the Icelandic special letters are not available and `best +replacements' for \verb=\Th=, \verb=\th=, and \verb=\dh= +are used (barred T and d resp.). +\end{encodinginfo} + + +\begin{encodinginfo}{T5} + {Vietnamese encoding} + {Werner Lemberg and + Vladimir Volovich} + {0x00--0xFF} + {---} + {vnr10} + {\cite{vnr}} + + The \Enc{T5} encoding was developed for Vietnamese. Again, this encoding + \emph{does not} conform to the requirements for a \Enc{T}-encoding + because its large number of accented letters prevent the \verb=\lccode= and + \verb=\uccode= mapping requirements for \Enc{T} encodings from being + fulfilled. However, since the Vietnamese language does not + use word division in typesetting so that this requirement is + actually not important for this particular language. + Since every glyph used in Vietnamese text is internally + represented as \textsc{licr} macros, the commands \verb=\MakeUppercase= and + \verb=\MakeLowercase= still work as expected (as they change the case of the + \textsc{ascii} characters in \textsc{licr} definitions). + +\end{encodinginfo} + +\begin{encodinginfo} + {T6} + {Armenian} + {---} + {---} + {---} + {} + {---} + + This encoding is reserved to permit future expansion of Armenian + \TeX{} to use 256-character (hyphenatable) fonts. +\end{encodinginfo} + +\begin{encodinginfo}{T7} + {Greek encoding} + {---} + {---} + {---} + {} + {---} + +The name is already reserved for a 256 glyph greek encoding. The encoding +itself hasn't been defined so far. + +\end{encodinginfo} + + + +\subsection{256$^-$ glyph encodings (text symbols)} + +\begin{encodinginfo}{TS1} + {Text Companion encoding (Cork)} + {J\"org Knappen} + {0x00--0x0D, 0x12, 0x15, 0x16, 0x18--0x1D, 0x20, 0x24, 0x27, 0x2A, + 0x2C--0x3A, 0x3C--0x3E, 0x4D, 0x4F, 0x57, 0x5B, 0x5D--0x60, + 0x62--0x64, 0x6C--0x6E, 0x7E--0xBF, 0xD6, 0xF6} + {---} + {tcrm1000} + {\cite{Knappen:TB17-2-96}} + + The text symbol encoding offers access to symbolic glyphs that are + commonly used in text (for a variety of reasons), and whose style + should vary with the text that surrounds them. + + Unfortunately, the \Enc{TS1} encoding was developed without + reference to the glyphs available in existing commercial fonts. + As a result, only font families + explicitly developed for \TeX{} (i.e., typically originating with + \MF{}) actually contain all glyphs required by the \Enc{TS1} + encoding. Most other font families (whether free or commercial) + often only provide half of the set% +%% +%% don't show the comment if the tables are not generated +%% +\expandafter\ifx\csname r@fonttable:tcrm1000\endcsname\relax +\else + \expandafter\ifx\csname r@fonttable:ptmr8c\endcsname\relax + \else + \space (compare the two tables for \Enc{TS1} on + pages~\pageref{fonttable:tcrm1000} + and~\pageref{fonttable:ptmr8c})% + \fi +\fi. + To improve this situation somewhat, NFSS provides a way to define encoding + subsets on a per family basis in the \Pkg{textcomp} package (which + package offers support for the \Enc{TS1} encoding). +\end{encodinginfo} + + +\begin{encodinginfo}{TS3} + {IPA symbol encoding} + {FUKUI Rei, University of Tokyo} + {0x00--0x0A, 0x20--0x49, 0x50--0x56, 0x70--0x7B} + {---} + {tipx10} + {\cite{Rei:TB17-2-102}} + + The \Enc{TS3} encoding (together with the \Enc{T3} encoding) provides the + glyphs for typesetting phonetic transcriptions following the + guidelines of the International Phonetic Association \cite{ipa}. Support + is offered through the \Pkg{tipa} package. +\end{encodinginfo} + + + + +\subsection{256 glyph encodings (text extended)} +\label{sec:extendedenc} + +\begin{encodinginfo} + {X2} + {Cyrillic glyph container} + {The CyrTUG font team} + {0x00--0xFF} + {---} + {rxrm1000} + {\cite{Berdnikov:eurotex-98}} + + This encoding specifies the glyph container for Cyrillic characters, + which is used in specifying the \Enc{T2A}, \Enc{T2B} and \Enc{T2C} encodings. +\end{encodinginfo} + + + + +\subsection{128$^+$ glyph encodings (mathematics)} + + +\begin{encodinginfo}{OML} + {\TeX{} math italic} + {Donald Ervin Knuth} + {0x00--0x7F} + {---} + {cmmi10} + {\cite[p.430]{A-W:DKn86}} + + The \Enc{OML} encoding contains italic Latin and Greek letters for + use in mathematical formulas (typically used for variables) together + with some symbols. + +\end{encodinginfo} + +\begin{encodinginfo}{OMS} + {\TeX{} math symbol} + {Donald Ervin Knuth} + {0x00--0x7F} + {---} + {cmsy10} + {\cite[p.431]{A-W:DKn86}} + + The \Enc{OMS} encoding contains basic mathematical symbols, + together with an uppercase ``calligraphic'' Latin alphabet. +\end{encodinginfo} + + +\begin{encodinginfo}{OMX} + {\TeX{} math extension} + {Donald Ervin Knuth} + {0x00--0x7F} + {---} + {cmex10} + {\cite[p.432]{A-W:DKn86}} + + \Enc{OMS} encodes mathematical symbols with variable sizes, such as + the $\sum$ sign, which changes its size if used in displayed + formulas, and the construction parts for + brackets, braces and radicals, etc., which can stretch to accommodate + the thing they're enclosing. + +\end{encodinginfo} + + + + +\subsection{256 glyph encodings (mathematics)} + +So far there are no 256 glyph mathematical encodings. A proposal is +given in \cite{ziegler}. + + +\subsection{Other encodings} + +\begin{encodinginfo} + {C..} + {CJK encodings} + {Werner Lemberg} + {0x00--0xFF} + {---} + {} % no font, of course + {\cite{CJK}} + + The \Pkg{CJK} package defines a number of encodings which access Chinese, + Japanese and Korean fonts. + +\end{encodinginfo} + +\begin{encodinginfo} + {E..} + {Experimental encodings} + {---} + {0x00--0xFF} + {all} + {} + {\cite[p.416]{A-W:MG2004}} + + As the name indicates, encodings starting with the letter \Enc{E} are + intended for experimental encodings, that are still likely to change. +\end{encodinginfo} + +\begin{encodinginfo}{L..} + {Local encoding (site dependent)} + {---} + {0x00--0xFF} + {all} + {} + {\cite[p.416]{A-W:MG2004}} + + `Local' encodings provide the means to develop representation + techniques that are suited to a particular \TeX{} environment. While + the developer has freedom to specify their encoding as he or she + pleases, there is a strong incentive to obey the \LaTeX{} rules for + encodings, since it will otherwise be difficult to compose text using + the encoding. + + At least it was the intention that \Enc{L..} encodings are local and + site dependent. However, a number of such encodings became generally + used without ever getting a different name allocated. + +\end{encodinginfo} + + + +\begin{encodinginfo}{LY1} + {Y\&Y 256 glyph encoding} + {Berthold Horn} + {0x00--0x08, 0x0C, 0x10, 0x12--0xFF} + {\emph{believed none}} + {ptmr8y} + {\cite[p.416]{A-W:MG2004}} + + This is an alternative to the \Enc{T1} encoding developed by Y\&Y and + used in their commercial \TeX{} implementation. + +\end{encodinginfo} + + +\begin{encodinginfo}{LV1} + {MicroPress encoding} + {Michael Vulis} + {\emph{unknown}} + {\emph{unknown}} + {} + {\cite[p.416]{A-W:MG2004}} + + This is an encoding developed by MicroPress and used for some of their + fonts. + +\end{encodinginfo} + + +\begin{encodinginfo}{LGR} + {Greek 256 glyph encoding} + {\emph{unknown}} + {0x00--0xFF} + {\emph{believed none}} + {grmn1000} + {\cite[p.575]{A-W:MG2004}} + + Currently the main encoding in use for the Greek language. + + This encoding doesn't conform to the restrictions for + \Enc{T}-encodings described in section~\ref{sec:restrictions} on + page~\pageref{sec:restrictions} as it doesn't have \textsc{ascii} + glyphs at all. + +\end{encodinginfo} + + +\begin{encodinginfo} + {PD1} + {PDF DocEncoding} + {Adobe} + {0x08--0x0A, 0x0C, 0x0D, 0x18--0x7E, 0x80--0x9E, 0xA0--0xAE, 0xB0--0xFF} + {---} + {} + {\cite{Adobe:PDF-1.6}, \cite{hyperref}} + + The \Enc{PD1} encoding is a virtual encoding with 256 glyphs needed to + produce bookmarks and similar text in PDF document generated with pdf\LaTeX. + The encoding is ``virtual'' because by design there are no \TeX{} + fonts that cover \Enc{PD1}. Details can be found in appendix D.1 + of~\cite{Adobe:PDF-1.6}. +\end{encodinginfo} + +\begin{encodinginfo} + {PU} + {PDF Unicode Encoding} + {Adobe} + {---} + {---} + {} + {\cite{Adobe:PDF-1.6}, \cite{hyperref}} + + Another virtual encoding (with more than 600 characters) for + Unicode-encoded bookmarks in PDF documents. +\end{encodinginfo} + +\begin{encodinginfo}{U} + {Unknown encoding} + {---} + {potentially 0x00-0xFF} + {all} + {wasy10} + {\cite[p.416]{A-W:MG2004}} + + This encoding should be used for fonts that resist classification, + e.g., when it is clear that there will never be more than one font + using the same encoding. + +\end{encodinginfo} + + + +\section{Restrictions} +\label{sec:restrictions} + + +\subsection{Required glyphs for general text encodings} + +Encodings that are supposed to be used with \LaTeX{} for `general +purpose text fonts' need to have certain fixed glyphs in certain +encoding slots. A `general purpose text font' is one intended for +arbitrary natural language text and not just within special +environments (such as the phonetic alphabet) or just for typesetting +individual symbols (e.g., the text companion font with encoding +\Enc{TS1}). + +This is the case for the following glyphs that have to be in their +\textsc{ascii} positions for general purpose text encodings: +\begin{center} +\begin{tabular}[t]{cc} + Glyph & Position \\ \hline + ! & \number`\! \\ + ' & \number`\' \\ + ( & \number`\( \\ + ) & \number`\) \\ + \relax* & \number`\* \\ + + & \number`\+ \\ + , & \number`\, \\ + - & \number`\- \\ + . & \number`\. \\ + / & \number`\/ \\ + 0 \ldots\ 9 & \number`\0\ to \number`\9 \\ + \end{tabular} + \quad + \begin{tabular}[t]{cc} + Glyph & Position \\ \hline + : & \number`\: \\ + ; & \number`\; \\ + = & \number`\= \\ + ? & \number`\? \\ + @ & \number`\@ \\ + A \ldots\ Z & \number`\A\ to \number`\Z \\ + \relax[ & \number`\[ \\ + ] & \number`\] \\ + ` & \number`\` \\ + a \ldots\ z & \number`\a\ to \number`\z \\ +\end{tabular} +\quad +\begin{tabular}[t]{cc} +Glyph\footnotemark & Position \\ \hline +< & \number`\< \\ +> & \number`\> \\ +\string| & \number`\| \\ +\end{tabular}\footnotetext{The requirement for these three glyphs is + violated in the Latin alphabet \Enc{OT} encodings.} +\end{center} +In addition the following glyphs have to be present +somewhere\footnote{The position in this case is not important as they +are generated from ligature programs.} in the encoding together with +corresponding ligature programs to generate them: +\begin{center} +\begin{tabular}[t]{cc} +Glyph & Ligature program \\ \hline + `` & \texttt{`\/`} \\ + '' & \texttt{'\/'} \\ + -- & \texttt{-\/-} \\ + --- & \texttt{-\/-\/-} \\ +\end{tabular} +\end{center} + +This is $33 + 2 * 26 = 85$ positions ``required'', which leaves 171 +positions free. + +If there are free slots available then adding all or some of the +diacritics would be the best way to fill them. + +If there are insufficient slots for the characters needed, a possible +technique is to create a subsidiary encoding, and to move non-letter +characters to it. Since only ``letters'' take part in the hyphenation +algorithm, this technique doesn't affect the appearance of the typeset +result. + +\subsection{The constraints on upper/lower case tables} + +Due to some technical restrictions of \TeX{} related to hyphenation it +is not possible in \LaTeX{} to use more than one \verb=\lccode= or +\verb=\uccode= table. Therefore all encodings need to share these two +tables which are defined to be those of the \Enc{T1} encoding. + +The \Enc{T1} encoding has some nasty peculiarities which make certain slot +positions more or less unusable for other encodings if this +restriction is to be obeyed. This is unfortunate but since \Enc{T1} is well +established and the basis for a large number of languages it seemed +better to live with this situation instead of trying to replace \Enc{T1} with a +slightly better standard (with the result that for a long time +different \LaTeX{} installations would not be able to communicate with +each other because of incompatible font sets). + +The positions that are problematic are as follows. +\begin{center} +\begin{tabular}{lp{.8\linewidth}} +25 (\char 25) & uppercase maps strangely (same as for 105, \char 105)\\ +26 (\char 26) & uppercase maps strangely (same as for 106, \char 106)\\ +27 (\char 27) & lowercase maps to itself which makes this slot subject + to hyphenation (used to support \Enc{OT1} encoding) \\ +157 (\char 157) & lowercase maps strangely (same as for 73, \char 73) \\ +158 (\char 158) & uppercase maps strangely (same as for 240, \char 240) \\ +\end{tabular} +\end{center} +One way to use such slots is to fill them with ligature glyphs as +\TeX{} will not consult these tables for glyphs constructed through +ligatures programs but instead uses the entries for the individual +glyphs used to produce the ligature. + +A complete listing of the uppercase/lowercase mapping tables is to be +found in section~\ref{sec:uclc-tab} (page \pageref{sec:uclc-tab}). + +\newcount\temp \newcount\tempL \newcount\tempU + +\def\nextstep{\global\tempL=\lccode\temp + \global\tempU=\uccode\temp + \lctablenumbersize\the\temp & + \the\tempL& + \the\tempU&\printlowerupper{\the\temp}{\the\tempL}{\the\tempU}\\ + \global\advance\temp by 1 + \stepprint} + +\def\printlowerupper#1#2#3{\char#1\relax + (\ifnum#2=0\relax--\else\char#2\fi + /\ifnum#3=0\relax--\else\char#3\fi)} + +\def\stepprint{\relax\ifnum\temp<\endval + \let\next=\nextstep + \else + \let\next=\relax + \fi + \next} + +\def\dolctable#1#2{{\temp=#1\relax +\def\endval{#2}% +\setlength\tabcolsep{1.5pt}% +\begin{tabular}[t]{@{}cccc@{}} +pos&lc&uc&glyphs\\\hline +\stepprint +\end{tabular}}} + +\iffalse +\begin{center} +\tiny\let\lctablenumbersize\tiny +\mbox{\dolctable{0}{52}\vrule +\dolctable{52}{104}\vrule +\dolctable{104}{156}\vrule +\dolctable{156}{208}\vrule +\dolctable{208}{256}} +\end{center} +\fi + +\iffalse +\begin{center}\tiny +\mbox{\dolctable{0}{65}\vrule +\dolctable{65}{128}\vrule +\dolctable{128}{193}\vrule +\dolctable{193}{256}} +\end{center} +\fi + + + +\section{Encoding specific commands} + +An encoding specific command is one that generates a glyph (or +glyphs), to produce a graphic effect that may be implemented +differently in different encodings. The encoding specific command +automatically changes its implementation when the encoding changes in +the course of the document. Encoding specific commands figure in +\LaTeX's internal character representation (\textsc{licr}) and are also +discussed in \cite[sec.~7.11.2, p.~442]{A-W:MG2004}. + +The following table only covers the encoding specific commands from +the \Enc{OT1} and \Enc{T1} encodings. Other encodings may specify +additional encoding specific commands. In the table, the first 15 +commands are `accent-like' and need as an argument the character to be +accented. For example, |\v{c}| is the \textsc{licr} for `\v{c}'. + +\begin{tabbing} +\ttverb\textvisiblespace\quad\=bbbbbbbbbbbbbb\=b'b'\=ccccccccccc\kill +\ttverb\`{} \>OT1,T1\> \a`{}\> (grave) \\ +\ttverb\'{} \>OT1,T1\> \a'{}\> (acute) \\ +\ttverb\^{} \>OT1,T1\> \^{}\> (circumflex) \\ +\ttverb\~{} \>OT1,T1\> \~{}\> (tilde) \\ +\ttverb\"{} \>OT1,T1\> \"{}\> (umlaut) \\ +\ttverb\H{} \>OT1,T1\> \H{}\> (Hungarian umlaut) \\ +\ttverb\r{} \>OT1,T1\> \r{}\> (ring) \\ +\ttverb\v{} \>OT1,T1\> \v{}\> (ha\v{c}ek) \\ +\ttverb\u{} \>OT1,T1\> \u{}\> (breve) \\ +\ttverb\t{} \>OT1,T1\> \t{}\> (tie) \\ +\ttverb\={} \>OT1,T1\> \a={}\> (macron) \\ +\ttverb\.{} \>OT1,T1\> \.{}\> (dot) \\ +\ttverb\b{} \>OT1,T1\> \b{}\> (underbar) \\ +\ttverb\c{} \>OT1,T1\> \c{}\> (cedilla) \\ +\ttverb\d{} \>OT1,T1\> \d{}\> (dot under) \\ +\ttverb\k{} \>T1 \> \k{}\> (ogonek) \\ +% \ttverb\AA \>OT1,T1\> \AA \> \\ % no longer +\ttverb\AE \>OT1,T1\> \AE \> \\ +\ttverb\DH \>T1 \> \DH \> \\ +\ttverb\DJ \>T1 \> \DJ \> \\ +\ttverb\L \>OT1,T1\> \L \> \\ +\ttverb\NG \>T1 \> \NG \> \\ +\ttverb\OE \>OT1,T1\> \OE \> \\ +\ttverb\O \>OT1,T1\> \O \> \\ +\ttverb\SS \>OT1,T1\> \SS \> \\ +\ttverb\TH \>T1 \> \TH \> \\ +% \ttverb\aa \>OT1,T1\> \aa \> \\ no-longer +\ttverb\ae \>OT1,T1\> \ae \> \\ +\ttverb\dh \>T1 \> \dh \> \\ +\ttverb\dj \>T1 \> \dj \> \\ +\ttverb\guillemotleft \>T1 \> \guillemotleft \> (guillemet) \\ +\ttverb\guillemotright \>T1 \> \guillemotright \> (guillemet) \\ +\ttverb\guilsinglleft \>T1 \> \guilsinglleft \> (guillemet) \\ +\ttverb\guilsinglright \>T1 \> \guilsinglright \> (guillemet) \\ +\ttverb\i \>OT1,T1\> \i \> \\ +\ttverb\j \>OT1,T1\> \j \> \\ +\ttverb\l \>OT1,T1\> \l \> \\ +\ttverb\ng \>T1 \> \ng \> \\ +\ttverb\oe \>OT1,T1\> \oe \> \\ +\ttverb\o \>OT1,T1\> \o \> \\ +\ttverb\quotedblbase \>T1 \> \quotedblbase \> \\ +\ttverb\quotesinglbase \>T1 \> \quotesinglbase \> \\ +\ttverb\ss \>OT1,T1\> \ss \> \\ +\ttverb\textasciicircum \>OT1,T1\> \textasciicircum \> \\ +\ttverb\textasciitilde \>OT1,T1\> \textasciitilde \> \\ +\ttverb\textbackslash \>OT1,T1\> \textbackslash \> \\ +\ttverb\textbar \>OT1,T1\> \textbar \> \\ +\ttverb\textbraceleft \>OT1,T1\> \textbraceleft \> \\ +\ttverb\textbraceright \>OT1,T1\> \textbraceright \> \\ +\ttverb\textcompwordmark \>OT1,T1\> \textcompwordmark\> (invisible) \\ +\ttverb\textdollar \>OT1,T1\> \textdollar \> \\ +\ttverb\textemdash \>OT1,T1\> \textemdash \> \\ +\ttverb\textendash \>OT1,T1\> \textendash \> \\ +\ttverb\textexclamdown \>OT1,T1\> \textexclamdown \> \\ +\ttverb\textgreater \>OT1,T1\> \textgreater \> \\ +\ttverb\textless \>OT1,T1\> \textless \> \\ +\ttverb\textquestiondown \>OT1,T1\> \textquestiondown\> \\ +\ttverb\textquotedbl \>T1 \> \textquotedbl \> \\ +\ttverb\textquotedblleft \>OT1,T1\> \textquotedblleft\> \\ +\ttverb\textquotedblright \>OT1,T1\> \textquotedblright\> \\ +\ttverb\textquoteleft \>OT1,T1\> \textquoteleft \> \\ +\ttverb\textquoteright \>OT1,T1\> \textquoteright \> \\ +\ttverb\textregistered \>OT1,T1\> \textregistered \> \\ +\ttverb\textsection \>OT1,T1\> \textsection \> \\ +\ttverb\textsterling \>OT1,T1\> \textsterling \> \\ +\ttverb\texttrademark \>OT1,T1\> \texttrademark \> \\ +\ttverb\textunderscore \>OT1,T1\> \textunderscore \> \\ +\ttverb\textvisiblespace \>OT1,T1\> \textvisiblespace\> \\ +\ttverb\th \>T1 \> \th \> +\end{tabbing} + +\section{Encodings for Unicode based \TeX\ systems} +\label{sec:unicode} + +The preceding text has assumed a classic TeX system that is +restricted to the use of fonts with at most 256 characters. In order +to accommodate all the characters needed for different languages and +mathematics it is necessary to have multiple encodings as described +above, and \LaTeX\ needs to be aware of the encoding used for each +font. + +Unicode aims to provide a single encoding that removes most of the +need to switch encodings, apart from very specialist use for non-standard characters. Rather than assign codes in the range 0--256 (hex +FF) Unicode codes are in the range 0--1,114,111 (hex 10FFFF), although +not all slots are available for distinct characters for technical +reasons. Unicode offers the possibility to use a single input encoding +(usually UTF-8) for all documents and to use essentially the same +Unicode encoding for all fonts, so removing the need to switch +encodings in different contexts. + +Omega was perhaps the first widely used \TeX\ extension that +supported Unicode. Currently the two actively supported systems that are +present in most modern \TeX\ distributions are Xe\TeX\ and Lua\TeX. + +When used with these extended \TeX\ engines, \LaTeX's font system can +refer to Unicode fonts (typically OpenType fonts installed system-wide +on your operating system rather than fonts specifically encoded/installed for +\TeX). Currently the usual method of accessing these fonts is through +the contributed \Pkg{fontspec} package. This uses as encoding \Enc{TU}: +``\TeX{} Unicode'' (historically two experimental encodings \Enc{EU1} +and \Enc{EU2} +were used, depending on the engine, but these are deprecated). +The exact rules for \LaTeX\ encodings +for Unicode engines have not yet been finalised in terms of the (usual) +requirement that each slot should be defined. (This is not realistic for +a Unicode font, as almost all fonts address subsets of the full range.) +It is rare to need to specify the \Enc{TU} encoding a document as the +\Pkg{fontspec} package sets up the correct encoding when loaded. + +The restrictions described in section \ref{sec:restrictions} do not +apply, or need to be modified in a Unicode based engine. Clearly the +lowercase table (and hyphenation patterns) can not be restricted to +the values used for \Enc{T1} and do only refer to the first 256 +characters. + +When the \LaTeX\ format is made \LaTeX\ sets up the lowercase table +and classifies characters as letter- or non-letter-based on \Enc{T1} if +a classic \TeX\ or pdf\TeX\ is being used. If a Unicode based \TeX\ is +detected, the values are instead based on the classification and +lower-case mappings provided by the Unicode Character Database +\cite{ucd}. The \LaTeX{} team have written a generic loader bundle, +\Pkg{unicode-data}, which provides the mechanism to load this information +directly from the Unicode Character Database data files and which is read +when a Unicode-compliant engine is detected during format-building. + +Similarly in the default configuration files used by modern \TeX\ +distribution, the hyphenation files for each supported language are +written in UTF-8 encoding, using Unicode code points for all letters, +then if a classic \TeX\ system is detected, some additional macros are +loaded to convert these files to 256-character encodings where +possible, and assuming the \Enc{T1} lowercase table. For Unicode engines +no conversion takes place. (The hyphenation patterns for a small number of +languages require that some punctuation characters have non-zero +c values. This are set during pattern reading, and may at some +stage in the future use the e-\TeX{} \verb=\savinghyphcodes= mechanism to +avoid any need to manipulate \verb=\lccode= in the document.) + + + + +\begin{thebibliography}{99} +\addcontentsline{toc}{section}{\numberline{\relax}\refname} + + +\bibitem{Adobe:PDF-1.6} \emph{\textsc{PDF} reference}: + Adobe portable document format version~1.6. Adobe Systems + Incorporated, 2005. % why \textsuperscript{3}? + \url{http://partners.adobe.com/public/developer/en/pdf/PDFReference16.pdf}. + +\bibitem{Beeton:TB6-3-124} Barbara Beeton: + \emph{Mathematical symbols and cyrillic fonts ready for + distribution}. In: TUGBoat, 6\#3), 1985. + \url{http://tug.org/TUGboat/Articles/tb06-3/tb13beetcyr.pdf}. + +\bibitem{beeton} Barbara Beeton: \emph{Unicode + and math, a combination whose time has come -- Finally!}. In: + TUGBoat, 21\#3, 2000. + \url{http://www.tug.org/TUGboat/Articles/tb21-3/tb68beet.pdf}. + + +\bibitem{Berdnikov:eurotex-98} A.\@ Berdnikov, O.\@ + Lapko, M.\@ Kolodin, A.\@ Janishevsky and + A.\@ Burykin: \emph{The Encoding Paradigm in + \LaTeXe{} and the Projected X2 Encoding for Cyrillic Texts}. + Euro\TeX~98. + \url{http://www.gutenberg.eu.org/pub/GUTenberg/publicationsPDF/28-29-berdnikova.pdf}. + +\bibitem{CJK} \emph{The \Pkg{CJK} package}: + \url{http://cjk.ffii.org}. + +\bibitem{clasen} Matthias Clasen: \emph{A new + implementation of \LaTeX{} math}, 1997-98. + \url{http://www.tug.org/twg/mfg/papers/current/newmath.ps.gz}. + +\bibitem{clasen-vieth} Matthias Clasen and Ulrik + Vieth: \emph{Towards a new Math Font Encoding + for (La)\TeX}. March 1998, + \url{http://www.tug.org/twg/mfg/papers/current/mfg-euro-all.ps.gz}. + +\bibitem{CorkGW:91} +Dean Guenther and Janene Winter. +\newblock An international phonetic alphabet. +\newblock In Guenther \cite{proc:MGu91}, pages 149--156. +\newblock Published as {TUG}boat 12\#1. + +\bibitem{proc:MGu91} +Mary Guenther, editor. +\newblock {\em {\TeX} 90 Conference Proceedings}, March 1991. +\newblock Published as {TUG}boat 12\#1. + +\bibitem{tub:MFe90} +Michael~J. Ferguson. +\newblock Report on multilingual activities. +\newblock {\em {TUG}boat}, 11(4):514--516, 1990. + +\bibitem{fontinst} \emph{The \Pkg{fontinst} package}: + \textlangle CTAN\textrangle\url{/fonts/utilities/fontinst}. + +\bibitem{Rei:TB17-2-102} Fukui Rei: + \emph{\textsl{TIPA}: A system for processing phonetic + symbols in \LaTeX}. In: TUGBoat, 17\#, 1996. + \url{http://www.tug.org/TUGboat/Articles/tb17-2/tb51rei.pdf}. + +\bibitem{hyperref} \emph{The \Pkg{hyperref} package}: + \url{http://www.tug.org/applications/hyperref}. + +\bibitem{tub:JKn93} +J\"org Knappen. +\newblock Fonts for Africa: The fc Fonts. +\newblock {\em {TUG}boat}, 14(2):104, 1993. + +\bibitem{Knappen:TB17-2-96} J\"org Knappen: + \emph{The \Pkg{dc} fonts~1.3: Move towards stability + and completeness}. In: TUGBoat 17\#2, 1996. + \url{http://www.tug.org/TUGboat/Articles/tb17-2/tb51knap.pdf}. + +\bibitem{A-W:DKn86} +Donald~E. Knuth. +\newblock {\em The {\TeX}book}. +\newblock Volume~A of {\em Computers \& {T}ypesetting\/}, + May 1989. +\newblock Eight printing. + +\bibitem{vnr} \emph{The \Pkg{vnr} font family}, developed by + the author of pdf\TeX, {H\`an Th\^e\protect\llap{\raise 0.5ex\hbox{\'{\relax}}} Th\`anh}. + \url{http://vntex.org/download/vntex}. + + \bibitem{ipa} Home page of the International Phonetic Association. + \url{http://www.arts.gla.ac.uk/IPA/ipa.html} + +\bibitem{A-W:LLa94} +Leslie Lamport. +\newblock {\em {\LaTeX:} A Document Preparation System}. +\newblock Addison-Wesley, Reading, Massachusetts, second edition, 1994. + +\bibitem{LH-Fonts} \emph{The \Pkg{lh}-Fonts for Cyrillic}: + \textlangle CTAN\textrangle\url{/fonts/cyrillic/lh}. + +\bibitem{A-W:MG2004} +Frank Mittelbach and Michel Goossens. +\newblock {\em The {\LaTeX} Companion second edition}. +\newblock With Johannes Braams, David Carlisle, and Chris Rowley. +\newblock Addison-Wesley, Reading, Massachusetts, 2004. + +\bibitem{Unicode} \emph{The Unicode Standard}. + \url{http://unicode.org}. + +\bibitem{ucd} \emph{The Unicode Character Database}. + \url{http://unicode.org/ucd}. + +\bibitem{ziegler} Justin Ziegler, \emph{Technical + Report on Math Font Encodings}, June 1994, + \url{http://www.tug.org/twg/mfg/papers/ltx3pub/l3d007.ps.gz}. + +\end{thebibliography} + +\clearpage\appendix +\begin{center} + \Large\bfseries Appendices +\end{center} + +\section{Example code tables} + +This appendix contains a table of each font mentioned as an ``example'' +font above, providing that the font was available when the document +was processed with \LaTeX{}. (\LaTeX{} generates a warning message +for each font it fails to find.) + +\subsection{Text encodings} + +\ftable{cmr10}{OT1} + +\ftable{wnr10}{OT2} + +\ftable{wsuipa10}{OT3} + +\ftable{plr10}{OT4} + +%\ftable{artmr10}{OT6} + +\ftable{ecrm1000}{T1} + +\ftable{larm1000}{T2A} + +\ftable{lbrm1000}{T2B} + +\ftable{lcrm1000}{T2C} + +\ftable{tipa10}{T3} + +\ftable{fcr10}{T4} + +\ftable{vnr10}{T5} + + +\subsection{Text symbol encodings} + +The full table for \Enc{TS1} as provided by European Computer Modern family: +\ftable{tcrm1000}{TS1} + +\pagebreak + +In contrast typical PostScript fonts usually have incomplete implementations +of \Enc{TS1} sometimes missing more than half of the glyphs: + +\ftable{ptmr8c}{TS1} + +\ftable{tipx10}{TS3} + + + +\subsection{Extended text encodings} + +\ftable{rxrm1000}{X2} + + +\subsection{Mathematical encodings} + +\ftable{cmmi10}{OML} + +\ftable{cmsy10}{OMS} + +\ftable{cmex10}{OMX} + + +\subsection{Other encodings} + +\ftable{ptmr8y}{LY1} + +%%\ftable{????}{LV1} + +\ftable{grmn1000}{LGR} + +\ftable{wasy10}{U} +\ftable{logo10}{U} + +\clearpage +\section{Uppercase and lowercase tables} +\label{sec:uclc-tab} + +The following two sets of tables list the \verb"\uppercase" and +\verb"\lowercase" values for each position in the \LaTeX{} standard +256-character tables. + +Each row of each table lists: +\begin{quote} + \begin{tabular}{lp{0.7\textwidth}} + pos & The position in the table (0-255) \\ + lc & The value in the \verb"\lowercase" table at the position \\ + & (note that value 0 here means that \verb"\lowercase" is + ineffective for this character, and hyphenation does not apply + to it) \\ + uc & The value in the \verb"\uppercase" table at the position \\ + & (note that value 0 here means that \verb"\uppercase" is + ineffective for this character) \\ + glyphs & The glyphs specified for the T1 encoding for this + position, laid out as \meta{glyph}\textbf{(}\meta{lowercase + glyph}\textbf{/}\meta{uppercase glyph}\textbf{)} + \end{tabular} +\end{quote} + +\begin{center} + \let\lctablenumbersize\footnotesize + \makebox[\textwidth]{\hss + \dolctable{0}{32}\quad\dolctable{32}{64}\quad + \dolctable{64}{96}\quad\dolctable{96}{128}% + \hss} + + \makebox[\textwidth]{\hss + \dolctable{128}{160}\quad\dolctable{160}{192}\quad + \dolctable{192}{224}\quad\dolctable{224}{256}% + \hss} +\end{center} +\end{document} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% diff --git a/macros/latex-dev/doc/fntguide.pdf b/macros/latex-dev/doc/fntguide.pdf new file mode 100644 index 0000000000..99008de40b Binary files /dev/null and b/macros/latex-dev/doc/fntguide.pdf differ diff --git a/macros/latex-dev/doc/fntguide.tex b/macros/latex-dev/doc/fntguide.tex new file mode 100644 index 0000000000..92dd6d1a84 --- /dev/null +++ b/macros/latex-dev/doc/fntguide.tex @@ -0,0 +1,1907 @@ +% \iffalse meta-comment +% +% Copyright 1993-2019 +% +% The LaTeX3 Project and any individual authors listed elsewhere +% in this file. +% +% This file is part of the LaTeX base system. +% ------------------------------------------- +% +% 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 +% 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 file has the LPPL maintenance status "maintained". +% +% The list of all files belonging to the LaTeX base distribution is +% given in the file `manifest.txt'. See also `legal.txt' for additional +% information. +% +% The list of derived (unpacked) files belonging to the distribution +% and covered by LPPL is defined by the unpacking scripts (with +% extension .ins) which are part of the distribution. +% +% \fi +% Filename: fntguide.tex + +\NeedsTeXFormat{LaTeX2e}[1995/12/01] + +\documentclass{ltxguide}[1995/11/28] + +\title{\LaTeXe{} font selection} + +\author{\copyright~Copyright 1995--2019, \LaTeX3 Project Team.\\ + All rights reserved.} + +\date{July 2019} + +\begin{document} + +\maketitle + +\tableofcontents + +\section{Introduction} + +This document describes the new font selection features of the \LaTeX{} +Document Preparation System. It is intended for package writers who +want to write font-loading packages similar to |times| or |latexsym|. + +This document is only a brief introduction to the new facilities and +is intended for package writers who are familiar with \TeX{} fonts and +\LaTeX{} packages. It is \emph{neither} a user-guide \emph{nor} a +reference manual for fonts in \LaTeXe. + +\subsection{\LaTeXe~fonts} + +The most important difference between \LaTeX~2.09 and \LaTeXe{} is the +way that fonts are selected. In \LaTeX~2.09, the Computer Modern fonts +were built into the \LaTeX~format, and so customizing \LaTeX{} to use +other fonts was a major effort. + +In \LaTeXe, very few fonts are built into the format, and there are +commands to load new text and math fonts. Packages such as |times| or +|latexsym| allow authors to access these fonts. +This document describes how to write similar font-loading packages. + +The \LaTeXe{} font selection system was first released as the `New Font +Selection Scheme' (NFSS) in 1989, and then in release~2 in 1993. +\LaTeXe{} includes NFSS release~2 as standard. + +\subsection{Overview} + +This document contains an overview of the new font commands +of \LaTeX. + +\begin{description} + +\item[Section~\ref{Sec:text}] describes the commands for selecting fonts + in classes and packages. It lists the five \LaTeX{} font + attributes, and lists the commands for selecting fonts. It also + describes how to customize the author commands such as |\textrm| and + |\textit| to suit your document design. + +\item[Section~\ref{Sec:math}] explains the commands for controlling + \LaTeX{} math fonts. It describes how to specify new math fonts and + new math symbols. + +\item[Section~\ref{Sec:install}] explains how to install new fonts into + \LaTeX. It shows how \LaTeX{} font attributes are turned into \TeX{} + font names, and how to specify your own fonts using font definition + files. + +\item[Section~\ref{Sec:encode}] discusses text font encodings. + It describes how to declare a new encoding and how to define + commands, such as |\AE| or |\"|, which have different definitions in + different encodings, depending on whether ligatures, etc.\ are + available in the encoding. + +\item[Section~\ref{Sec:misc}] covers font miscellanea. It describes how + \LaTeX{} performs font substitution, how to customize fonts that are + preloaded in the \LaTeX{} format, and the naming conventions used in + \LaTeX{} font selection. + +\end{description} + +\subsection{Further information} + +For a general introduction to \LaTeX, including the new features of +\LaTeXe, you should read \emph{\LaTeXbook}, +Leslie Lamport, Addison Wesley, 2nd~ed, 1994. + +A more detailed description of the \LaTeX{} font selection scheme is to +be found in \emph{\LaTeXcomp}, 2nd~ed, by Mittelbach and Goossens, Addison +Wesley, 2004. + +The \LaTeX{} font selection scheme is based on \TeX, which is described +by its developer in \emph{The \TeX book}, Donald E.~Knuth, Addison +Wesley, 1986, revised in 1991 to include the features of \TeX~3. + +Sebastian Rahtz's |psnfss| software contains the software for using a +large number of Type~1 fonts (including the Adobe Laser Writer 35 and +the Monotype CD-ROM fonts) in \LaTeX. It should be available from the +same source as your copy of \LaTeX. + +The |psnfss| software uses fonts generated by Alan Jeffrey's +|fontinst| software. This can convert fonts from Adobe Font Metric +format into a format readable by \LaTeX, including the generation of +the font definition files described in Section~\ref{Sec:install}. The +|fontinst| software should be available from the same source as your +copy of \LaTeX. + +Whenever practical, \LaTeX{} uses the font naming scheme called +`fontname'; this was described in \emph{Filenames for fonts},% +\footnote{An up-to-date electronic version +of this document can be found on any CTAN server, in the directory +\texttt{info/fontname}.} +\emph{TUGboat}~11(4),~1990. + +The class-writer's guide \emph{\clsguide} describes +the new \LaTeX{} features for writers of document classes and packages +and is kept in |clsguide.tex|. Configuring +\LaTeX{} is covered by the guide \emph{\cfgguide} in +\texttt{cfgguide.tex} whilst the philosophy behind our policy on +modifying \LaTeX{} is described in \emph{\modguide} in +\texttt{modguide.tex}. + +The documented source code (from the files used to produce +the kernel format via |latex.ltx|) is now available as +\emph{The \LaTeXe\ Sources}. +This very large document also includes an index of \LaTeX{} +commands. It can be typeset from the \LaTeX{} file |source2e.tex| +in the |base| directory; this uses the class file |ltxdoc.cls|. + +For more information about \TeX{} and \LaTeX{}, please contact your +local \TeX{} Users Group, or the international \TeX{} Users Group. +Addresses and other details can be found at: +\begin{quote}\small\label{addrs} + \texttt{http://www.tug.org/lugs.html} +\end{quote} + + +\section{Text fonts} +\label{Sec:text} + +This section describes the commands available to class and package +writers for specifying and selecting fonts. + +\subsection{Text font attributes} + +Every text font in \LaTeX{} has five \emph{attributes}: +\begin{description} + +\item[encoding] This specifies the order that characters appear in the + font. The two most common text encodings used in \LaTeX{} are + Knuth's `\TeX{} text' encoding, and the `\TeX{} text extended' + encoding developed by the \TeX{} Users Group members during a \TeX{} + Conference at Cork in~1990 (hence its informal name `Cork encoding'). + +\item[family] The name for a collection of fonts, usually grouped under + a common name by the font foundry. For example, `Adobe Times', `ITC + Garamond', and Knuth's `Computer Modern Roman' are all font families. + +\item[series] How heavy and/or expanded a font is. For example, `medium + weight', `narrow' and `bold extended' are all series. + +\item[shape] The form of the letters within a font family. For + example, `italic', `oblique' and `upright' (sometimes called + `roman') are all font shapes. + +\item[size] The design size of the font, for example `10pt'. If no + dimension is specified, `pt' is assumed. + +\end{description} +The possible values for these attributes are given short acronyms by +\LaTeX. The most common values for the font encoding are: +\begin{center} +\begin{minipage}{.7\linewidth} + \begin{tabular}{rl} + |OT1| & \TeX{} text \\ + |T1| & \TeX{} extended text \\ + |OML| & \TeX{} math italic \\ + |OMS| & \TeX{} math symbols \\ + |OMX| & \TeX{} math large symbols \\ + |U| & Unknown \\ + |L<xx>| & A local encoding + \end{tabular} +\end{minipage} +\end{center} +The `local' encodings are intended for font encodings which are only +locally available, for example a font containing an organization's +logo in various sizes. + +There are far too many font families to list them all, but some common +ones are: +\begin{center} +\begin{minipage}{.7\linewidth} + \begin{tabular}{rl} + |cmr| & Computer Modern Roman \\ + |cmss| & Computer Modern Sans \\ + |cmtt| & Computer Modern Typewriter \\ + |cmm| & Computer Modern Math Italic \\ + |cmsy| & Computer Modern Math Symbols \\ + |cmex| & Computer Modern Math Extensions \\ + |ptm| & Adobe Times \\ + |phv| & Adobe Helvetica \\ + |pcr| & Adobe Courier + \end{tabular} +\end{minipage} +\end{center} +\NEWdescription{2019/07/10} +The font series is denoting a combination of the weight (boldness) and +the width (amount of expansion). The standard supported for weights +and widths are: +\begin{center} +%\begin{minipage}{.7\linewidth} + \begin{tabular}{rl} + |ul| & Ultra Light \\ + |el| & Extra Light \\ + |l| & Light \\ + |sl| & Semi Light \\ + |m| & Medium (normal)\\ + |sb| & Semi Bold \\ + |b| & Bold \\ + |eb| & Extra Bold \\ + |ub| & Ultra Bold \\ + \end{tabular} +\qquad + \begin{tabular}{rlr} + |uc| & Ultra Condensed & 50\% \\ + |ec| & Extra Condensed & 62.5\% \\ + |c| & Condensed & 75\% \\ + |sc| & Semi Condensed & 87.5\% \\ + |m| & Medium & 100\% \\ + |sx| & Semi Expanded & 112.5\% \\ + |x| & Expanded & 125\% \\ + |ex| & Extra Expanded & 150\% \\ + |ux| & Ultra Expanded & 200\% \\ + \end{tabular} +\end{center} +These are concatenated to a single series value except that |m| is +dropped unless both weight and width are medium in which case a single +|m| is used. + +\newpage + +Examples for series values are then: +\begin{center} +\begin{minipage}{.7\linewidth} + \begin{tabular}{rl} + |m| & Medium weight and width \\ + |b| & Bold weight, medium width \\ + |bx| & Bold extended \\ + |sb| & Semi-bold, medium width\\ + |sbx| & Semi-bold extended\\ + |c| & Medium weight, condensed width + \end{tabular} +\end{minipage} +\end{center} +\NEWdescription{2019/07/10} +Note, that there are a large variety of names floating around like +``regular'', ``black'', ``demi-bold'', ``thin'', ``heavy'' and many +more. If at all possible they should be matched into the standard +naming scheme to allow for sensible default substitutions if +necessary, e.g., ``demi-bold'' is normally just another name for +``semi-bold'', so should get |sb| assigned, etc. + +The most common values for the font shape are: +\begin{center} +\begin{minipage}{.7\linewidth} + \begin{tabular}{rl} + |n| & Normal (that is `upright' or `roman') \\ + |it| & Italic \\ + |sl| & Slanted (or `oblique') \\ + |sc| & Caps and small caps + \end{tabular} +\end{minipage} +\end{center} +The font size is specified as a dimension, for example |10pt| or +|1.5in| or |3mm|; if no unit is specified, |pt| is assumed. These five +parameters specify every \LaTeX{} font, for example: +\begin{center} + \begin{tabular}{@{}r@{\,}l@{\,}c@{\,}c@{\,}cc@{}r@{}} + \multicolumn{5}{@{}c}{\emph{\LaTeX{} specification}} & + \emph{Font} & + \emph{\TeX{} font name} \\ + |OT1| & |cmr| & |m| & |n| & |10| & + Computer Modern Roman 10 point & + |cmr10| \\ + |OT1| & |cmss| & |m| & |sl| & |1pc| & + Computer Modern Sans Oblique 1 pica & + |cmssi12| \\ + |OML| & |cmm| & |m| & |it| & |10pt| & + Computer Modern Math Italic 10 point & + |cmmi10| \\ + |T1| & |ptm| & |b| & |it| & |1in| & + Adobe Times Bold Italic 1 inch & + |ptmb8t at 1in| + \end{tabular} +\end{center} +These five parameters are displayed whenever \LaTeX{} gives an overfull +box warning, for example: +\begin{verbatim} + Overfull \hbox (3.80855pt too wide) in paragraph at lines 314--318 + []\OT1/cmr/m/n/10 Normally [] and [] will be iden-ti-cal, +\end{verbatim} +The author commands for fonts set the five attributes: +\begin{center} + \begin{tabular}{rcl} + \emph{Author command} & + \emph{Attribute} & + \emph{Value in} |article| \emph{class} \\ + |\textnormal{..}| or |\normalfont| & family & |cmr| \\ + |\textrm{..}| or |\rmfamily| & family & |cmr| \\ + |\textsf{..}| or |\sffamily| & family & |cmss| \\ + |\texttt{..}| or |\ttfamily| & family & |cmtt| \\ + |\textmd{..}| or |\mdseries| & series & |m| \\ + |\textbf{..}| or |\bfseries| & series & |bx| \\ + |\textup{..}| or |\upshape| & shape & |n| \\ + |\textit{..}| or |\itshape| & shape & |it| \\ + |\textsl{..}| or |\slshape| & shape & |sl| \\ + |\textsc{..}| or |\scshape| & shape & |sc| \\ + |\tiny| & size & |5pt| \\ + |\scriptsize| & size & |7pt| \\ + |\footnotesize| & size & |8pt| \\ + |\small| & size & |9pt| \\ + |\normalsize| & size & |10pt| \\ + |\large| & size & |12pt| \\ + |\Large| & size & |14.4pt| \\ + |\LARGE| & size & |17.28pt| \\ + |\huge| & size & |20.74pt| \\ + |\Huge| & size & |24.88pt| + \end{tabular} +\end{center} +The values used by these commands are determined by the document class, +using the parameters defined in Section~\ref{Sec:text.param}. + +Note that there are no author commands for selecting new encodings. +These should be provided by packages, such as the |fontenc| package. + +This section does not explain how \LaTeX{} font specifications are +turned into \TeX{} font names. This is described in +Section~\ref{Sec:install}. + +\subsection{Selection commands} + +The low-level commands used to select a text font are as follows. + +\begin{decl} +|\fontencoding| \arg{encoding} \\ +|\fontfamily| \arg{family}\\ +|\fontseries| \arg{series}\\ +|\fontshape| \arg{shape}\\ +|\fontsize| \arg{size} \arg{baselineskip}\\ +|\linespread| \arg{factor} +\end{decl} + +\NEWdescription{1998/12/01} +Each of the commands starting with |\font...| sets one of the font +attributes; |\fontsize| also sets |\baselineskip|. The |\linespread| +command prepares to multiply the current (or newly defined) +|\baselineskip| with \m{factor} (e.g., spreads the lines apart for +values greater one). + +The actual font in use is not altered by these commands, but the +current attributes are used to determine which font and baseline skip +to use after the next |\selectfont| command. + + +\begin{decl} +|\selectfont| +\end{decl} +Selects a text font, based on the current values of the font attributes. + +\emph{Warning}: There \emph{must} be a |\selectfont| command +immediately after any settings of the font parameters by (some of) +the six commands above, before any following text. +For example, it is legal to say: +\begin{verbatim} + \fontfamily{ptm}\fontseries{b}\selectfont Some text. +\end{verbatim} +but it is \emph{not} legal to say: +\begin{verbatim} + \fontfamily{ptm} Some \fontseries{b}\selectfont text. +\end{verbatim} +You may get unexpected results if you put text between a +|\font<parameter>| command (or |\linespread|) and a |\selectfont|. + +\begin{decl} +|\usefont| \arg{encoding} \arg{family} \arg{series} \arg{shape} +\end{decl} +A short hand for the equivalent |\font...| commands followed by a +call to |\selectfont|. + + +\subsection{Internals} + +The current values of the font attributes are held in internal macros. + +\begin{decl} + |\f@encoding| \\ + |\f@family| \\ + |\f@series| \\ + |\f@shape| \\ + |\f@size| \\ + |\f@baselineskip| \\ + |\tf@size| \\ + |\sf@size| \\ + |\ssf@size| +\end{decl} + +These hold the current values of the encoding, the family, the series, +the shape, the size, the baseline skip, the main math size, the +`script' math size and the `scriptscript' math size. The last three +are accessible only within a formula; outside of math they may contain +arbitrary values. + +For example, to set the size to 12 without +changing the baseline skip: +\begin{verbatim} + \fontsize{12}{\f@baselineskip} +\end{verbatim} +However, you should \emph{never} alter the values of the internal +commands directly; they must only be modified using the low-level +commands like |\fontfamily|, |\fontseries|, etc. If you disobey this +warning you might produce code that loops. + +\subsection{Parameters for author commands} +\label{Sec:text.param} + +The parameter values set by author commands such as |\textrm| and +|\rmfamily|, etc.\ are not hard-wired into \LaTeX; instead these +commands use the values of a number of parameters set by the document +class and packages. For example, |\rmdefault| is the name of the +default family selected by |\textrm| and |\rmfamily|. Thus to set a +document in Adobe Times, Helvetica and Courier, the document designer +specifies: +\begin{verbatim} + \renewcommand{\rmdefault}{ptm} + \renewcommand{\sfdefault}{phv} + \renewcommand{\ttdefault}{pcr} +\end{verbatim} + +\begin{decl} + |\encodingdefault| \\ + |\familydefault| \\ + |\seriesdefault| \\ + |\shapedefault| +\end{decl} +The encoding, family, series and shape of the main body font. By +default these are |OT1|, |\rmdefault|, |m| and |n|. Note that since +the default family is |\rmdefault|, this means that changing +|\rmdefault| will change the main body font of the document. + +\begin{decl} + |\rmdefault| \\ + |\sfdefault| \\ + |\ttdefault| +\end{decl} +The families selected by |\textrm|, |\rmfamily|, |\textsf|, +|\sffamily|, |\texttt| and |\ttfamily|. By default these are |cmr|, +|cmss| and |cmtt|. + +\begin{decl} + |\bfdefault| \\ + |\mddefault| +\end{decl} +The series selected by |\textbf|, |\bfseries|, |\textmd| and +|\mdseries|. By default these are |bx| and |m|. +These values are suitable for the default families used. If other +fonts are used as standard document fonts (for example, certain +PostScript fonts) it might be necessary to adjust the value of +|\bfdefault| to |b| since only a few such families have a `bold +extended' series. An alternative (taken for the fonts provided by +|psnfss|) is to define silent substitutions from |bx| series to |b| +series with special |\DeclareFontShape| declarations and the |ssub| +size function, see Section~\ref{sec:sizefunct}. + + +\begin{decl} + |\itdefault| \\ + |\sldefault| \\ + |\scdefault| \\ + |\updefault| +\end{decl} +The shapes selected by |\textit|, |\itshape|, |\textsl|, |\slshape|, +|\textsc|, |\scshape|, |\textup| and |\upshape|. By default these are +|it|, |sl|, |sc| and |n|. + +Note that there are no parameters for the size commands. These should +be defined directly in class files, for example: +\begin{verbatim} + \renewcommand{\normalsize}{\fontsize{10}{12}\selectfont} +\end{verbatim} +More elaborate examples (setting additional parameters when the text +size is changed) can be found in |classes.dtx| the source +documentation for the classes |article|, |report|, and |book|. + + +\subsection{Special font declaration commands} + +\begin{decl} +|\DeclareFixedFont| \arg{cmd} \arg{encoding} \arg{family} \arg{series} + \arg{shape} \arg{size} +\end{decl} + +Declares command \m{cmd} to be a font switch which selects the font +that is specified by the attributes \m{encoding}, \m{family}, +\m{series}, \m{shape}, and \m{size}. + +The font is selected without any adjustments to baselineskip and other +surrounding conditions. + +This example makes |{\picturechar .}| select a small dot very quickly: +\begin{verbatim} + \DeclareFixedFont{\picturechar}{OT1}{cmr}{m}{n}{5} +\end{verbatim} + + +\begin{decl} +|\DeclareTextFontCommand| \arg{cmd} \arg{font-switches} +\end{decl} + +Declares command \m{cmd} to be a font command with one argument. +The current font attributes are locally modified by \m{font-switches} +and then the argument of \m{cmd} is typeset in the resulting new font. + +Commands defined by |\DeclareTextFontCommand| automatically take care +of any necessary italic correction (on either side). + +The following example shows how |\textrm| is defined by the kernel. +\begin{verbatim} + \DeclareTextFontCommand{\textrm}{\rmfamily} +\end{verbatim} + +To define a command that always typeset its argument in the italic +shape of the main document font you could declare: +\begin{verbatim} + \DeclareTextFontCommand{\normalit}{\normalfont\itshape} +\end{verbatim} + +This declaration can be used to change the meaning of a command; if +\m{cmd} is already defined, a log that it has been redefined +is put in the transcript file. + +\begin{decl} +|\DeclareOldFontCommand| \arg{cmd} \arg{text-switch} + \arg{math-switch} +\end{decl} + +Declares command \m{cmd} to be a font switch (i.e.~used with the +syntax |{<cmd>...}|) having the definition \m{text-switch} +when used in text and the definition \m{math-switch} when used in a +formula. +Math alphabet commands, like |\mathit|, when used within \m{math-switch} +should not have an argument. Their use in this argument causes their +semantics to change so that they here act as a font switch, as +required by the usage of the \m{cmd}. + +This declaration is useful for setting up commands like |\rm| to behave +as they did in \LaTeX~2.09. We strongly urge you \emph{not} to misuse +this declaration to invent new font commands. + +The following example defines |\it| to produce the italic shape of the +main document font if used in text and to switch to the font that would +normally be produced by the math alphabet |\mathit| if used in a +formula. +\begin{verbatim} + \DeclareOldFontCommand{\it}{\normalfont\itshape}{\mathit} +\end{verbatim} + +This declaration can be used to change the meaning of a command; if +\m{cmd} is already defined, a log that it has been redefined +is put in the transcript file. + + +\section{Math fonts} +\label{Sec:math} + +This section describes the commands available to class and package +writers for specifying math fonts and math commands. + +\subsection{Math font attributes} + +The selection of fonts within math mode is quite different to that of +text fonts. + +Some math fonts are selected explicitly by one-argument commands such +as |\mathsf{max}| or |\mathbf{vec}|; such fonts are called \emph{math +alphabets}. These math alphabet commands affect only the font used +for letters and symbols of type |\mathalpha| (see +Section~\ref{Sec:math.commands}); other symbols within the argument +will be left unchanged. The predefined math alphabets are: +\begin{center} + \begin{tabular}{ccc} + \emph{Alphabet} & \emph{Description} & \emph{Example} \\ + |\mathnormal| & default & $abcXYZ$ \\ + |\mathrm| & roman & $\mathrm{abcXYZ}$ \\ + |\mathbf| & bold roman & $\mathbf{abcXYZ}$ \\ + |\mathsf| & sans serif & $\mathsf{abcXYZ}$ \\ + |\mathit| & text italic & $\mathit{abcXYZ}$ \\ + |\mathtt| & typewriter & $\mathtt{abcXYZ}$ \\ + |\mathcal| & calligraphic & $\mathcal{XYZ}$ + \end{tabular} +\end{center} +Other math fonts are selected implicitly by \TeX{} for symbols, with +commands such as |\oplus| (producing $\oplus$) or with straight +characters like |>>| or |+|. Fonts containing such math symbols are +called \emph{math symbol fonts}. The predefined math symbol fonts +are: +\begin{center} + \begin{tabular}{ccc} + \emph{Symbol font} & \emph{Description} & \emph{Example} \\ + |operators| & symbols from |\mathrm| & $[\;+\;]$ \\ + |letters| & symbols from |\mathnormal| & $<<\star>>$ \\ + |symbols| & most \LaTeX{} symbols & $\leq*\geq$ \\ + |largesymbols| & large symbols & $\sum\prod\int$ + \end{tabular} +\end{center} +Some math fonts are both \emph{math alphabets} and \emph{math symbol +fonts}, for example |\mathrm| and |operators| are the same font, and +|\mathnormal| and |letters| are the same font. + +Math fonts in \LaTeX{} have the same five attributes as text fonts: +encoding, family, series, shape and size. However, there are no +commands that allow the attributes to be individually changed. +Instead, the conversion from math fonts to these five attributes is +controlled by the \emph{math version}. For example, the |normal| math +version maps: +\begin{center} + \begin{tabular}{rlc@{ }c@{ }c@{ }c} + \multicolumn{2}{c}{\emph{Math font}} & + \multicolumn{4}{c}{\emph{External font}} \\ + \emph{Alphabets} & \emph{Symbol fonts} & + \multicolumn{4}{c}{\emph{Attributes}} \\ + |\mathnormal| & |letters| & |OML| & |cmm| & |m| & |it| \\ + |\mathrm| & |operators| & |OT1| & |cmr| & |m| & |n| \\ + |\mathcal| & |symbols| & |OMS| & |cmsy| & |m| & |n| \\ + & |largesymbols| & |OMX| & |cmex| & |m| & |n| \\ + |\mathbf| & & |OT1| & |cmr| & |bx| & |n| \\ + |\mathsf| & & |OT1| & |cmss| & |m| & |n| \\ + |\mathit| & & |OT1| & |cmr| & |m| & |it| \\ + |\mathtt| & & |OT1| & |cmtt| & |m| & |n| + \end{tabular} +\end{center} +The |bold| math version is similar except that it contains bold fonts. +The command |\boldmath| selects the |bold| math version. + +Math versions can only be changed outside of math mode. + +The two predefined math versions are: +\begin{center} + \begin{tabular}{rl} + |normal| & the default math version \\ + |bold| & the bold math version + \end{tabular} +\end{center} +Packages may define new math alphabets, math symbol fonts, and math +versions. This section describes the commands for writing such +packages. + +\subsection{Selection commands} + +There are no commands for selecting symbol fonts. Instead, these are +selected indirectly through symbol commands like |\oplus|. +Section~\ref{Sec:math.commands} explains how to define symbol commands. + +\begin{decl} + |\mathnormal{<math>}|\\ + |\mathcal{<math>}|\\ + |\mathrm{<math>}|\\ + |\mathbf{<math>}|\\ + |\mathsf{<math>}|\\ + |\mathit{<math>}|\\ + |\mathtt{<math>}| +\end{decl} +Each math alphabet is a command which can only be used inside math +mode. For example, |$x + \mathsf{y} + \mathcal{Z}$| produces $x + +\mathsf{y} + \mathcal{Z}$. + +\begin{decl} +|\mathversion{<version>}| +\end{decl} +This command selects a math version; it can only be used outside math +mode. For example, |\boldmath| is defined to be |\mathversion{bold}|. + +\subsection{Declaring math versions} + +\begin{decl} +|\DeclareMathVersion| \arg{version} +\end{decl} + +Defines \m{version} to be a math version. + +The newly declared version is initialized with the defaults for all +symbol fonts and math alphabets declared so far (see the commands +|\DeclareSymbolFont| and |\DeclareMathAlphabet|). + +If used on an already existing version, an information message is +written to the transcript file and all previous |\SetSymbolFont| or +|\SetMathAlphabet| declarations for this version are overwritten by +the math alphabet and symbol font defaults, i.e.~one ends up with a +virgin math version. + +Example: +\begin{verbatim} + \DeclareMathVersion{normal} +\end{verbatim} + + +\subsection{Declaring math alphabets} + +\begin{decl} +|\DeclareMathAlphabet| \arg{math-alph} \arg{encoding} \arg{family} + \arg{series} \arg{shape} +\end{decl} + +\NEWdescription{1997/12/01} +If this is the first declaration for \m{math-alph} then a new math +alphabet with this as its command name is created. + +The arguments \m{encoding} \m{family} \m{series} \m{shape} are used to +set, or reset, the default values for this math alphabet in all math +versions; if required, these must be further reset later for a +particular math version by a |\SetMathAlphabet| command. + +If \m{shape} is empty then this \m{math-alph} is declared to be invalid +in all versions, unless it is set by a later |\SetMathAlphabet| +command for a particular math version. + +Checks that the command \m{math-alph} is either already a math +alphabet command or is undefined; and that \m{encoding} is a known +encoding scheme, i.e., has been previously declared. + + +In these examples, |\foo| is defined for all math versions but |\baz|, +by default, is defined nowhere. +\begin{verbatim} + \DeclareMathAlphabet{\foo}{OT1}{cmtt}{m}{n} + \DeclareMathAlphabet{\baz}{OT1}{}{}{} +\end{verbatim} + + +\begin{decl} +|\SetMathAlphabet| \arg{math-alph} \arg{version}\\ + \null\hfill\arg{encoding} \arg{family} \arg{series} \arg{shape} +\end{decl} + +Changes, or sets, the font for the math alphabet \m{math-alph} in math +version \m{version} to \m{encoding}\m{family}\m{series}\m{shape}. + +Checks that \m{math-alph} has been declared as a math alphabet, +\m{version} is a known math version and \m{encoding} is a known +encoding scheme. + + +This example defines |\baz| for the `normal' math version only: +\begin{verbatim} + \SetMathAlphabet{\baz}{normal}{OT1}{cmss}{m}{n} +\end{verbatim} + +Note that this declaration is not used for all math alphabets: +Section~\ref{sec:symalph} describes |\DeclareSymbolFontAlphabet|, +which is used to set up math alphabets contained in fonts which have +been declared as symbol fonts. + + +\subsection{Declaring symbol fonts} +\label{sec:symalph} + +\begin{decl} +|\DeclareSymbolFont| \arg{sym-font} \arg{encoding} \arg{family} + \arg{series} \arg{shape} +\end{decl} + +\NEWdescription{1997/12/01} +If this is the first declaration for \m{sym-font} then a new +symbol font with this name is created (i.e.~this identifier is assigned +to a new \TeX{} math group). + +The arguments \m{encoding} \m{family} \m{series} \m{shape} are used to +set, or reset. the default values for this symbol font in \emph{all} +math versions; if required, these must be further reset later for +a particular math version by a |\SetSymbolFont| command. + +Checks that \m{encoding} is a declared encoding scheme. + + +For example, the following sets up the first four standard math symbol +fonts: +\begin{verbatim} + \DeclareSymbolFont{operators}{OT1}{cmr}{m}{n} + \DeclareSymbolFont{letters}{OML}{cmm}{m}{it} + \DeclareSymbolFont{symbols}{OMS}{cmsy}{m}{n} + \DeclareSymbolFont{largesymbols}{OMX}{cmex}{m}{n} +\end{verbatim} + + +\begin{decl} +|\SetSymbolFont| \arg{sym-font} \arg{version}\\ + \null\hfill \arg{encoding} \arg{family} \arg{series} \arg{shape} +\end{decl} + +Changes the symbol font \m{sym-font} for math version \m{version} +to \m{encoding} \m{family} \m{series} \m{shape}. + +Checks that \m{sym-font} has been declared as a symbol font, +\m{version} is a known math version and \m{encoding} is a +declared encoding scheme. + + +For example, the following come from the set up of the `bold' +math version: +\begin{verbatim} + \SetSymbolFont{operators}{bold}{OT1}{cmr}{bx}{n} + \SetSymbolFont{letters}{bold}{OML}{cmm}{b}{it} +\end{verbatim} + + +\begin{decl} +|\DeclareSymbolFontAlphabet| \arg{math-alph} \arg{sym-font} +\end{decl} + +\NEWdescription{1997/12/01} +Allows the previously declared symbol font \m{sym-font} to be the +math alphabet with command \m{math-alph} in \emph{all} math versions. + +Checks that the command \m{math-alph} is either already a math alphabet +command or is undefined; and that \m{sym-font} is a symbol font. + + +Example: +\begin{verbatim} + \DeclareSymbolFontAlphabet{\mathrm}{operators} + \DeclareSymbolFontAlphabet{\mathcal}{symbols} +\end{verbatim} + +This declaration should be used in preference to +|\DeclareMathAlphabet| and |\SetMathAlphabet| when a math alphabet is +the same as a symbol font; this is because it makes better use of the +limited number (only 16) of \TeX's math groups. + +\NEWdescription{1997/12/01} +Note that, whereas a \TeX{} math group is allocated to each symbol font +when it is first declared, a math alphabet uses a \TeX{} math group +only when its command is used within a math formula. + + +\subsection{Declaring math symbols} +\label{Sec:math.commands} + +\begin{decl} +|\DeclareMathSymbol| \arg{symbol} \arg{type} \arg{sym-font} + \arg{slot} +\end{decl} + +The \m{symbol} can be either a single character such as `|>>|', or a +macro name, such as |\sum|. + +Defines the \m{symbol} to be a math symbol of type +\m{type} in slot \m{slot} of symbol font \m{sym-font}. The +\m{type} can be given as a number or as a command: +\begin{center} + \begin{tabular}{ccc} + \emph{Type} & \emph{Meaning} & \emph{Example} \\ + |0| or |\mathord | & Ordinary & $\alpha$ \\ + |1| or |\mathop | & Large operator & $\sum$ \\ + |2| or |\mathbin | & Binary operation & $\times$ \\ + |3| or |\mathrel | & Relation & $\leq$ \\ + |4| or |\mathopen | & Opening & $\langle$ \\ + |5| or |\mathclose| & Closing & $\rangle$ \\ + |6| or |\mathpunct| & Punctuation & $;$ \\ + |7| or |\mathalpha| & Alphabet character & $A$ + \end{tabular} +\end{center} +Only symbols of type |\mathalpha| will be affected by math alphabet +commands: within the argument of a math alphabet command they will +produce the character in slot \m{slot} of that math alphabet's font. +Symbols of other types will always produce the same symbol +(within one math version). + +|\DeclareMathSymbol| allows a macro \m{symbol} to be redefined only if +it was previously defined to be a math symbol. It also checks that +the \m{sym-font} is a declared symbol font. + +Example: +\begin{verbatim} + \DeclareMathSymbol{\alpha}{0}{letters}{"0B} + \DeclareMathSymbol{\lessdot}{\mathbin}{AMSb}{"0C} + \DeclareMathSymbol{\alphld}{\mathalpha}{AMSb}{"0C} +\end{verbatim} + +\begin{decl} + |\DeclareMathDelimiter| \arg{cmd} \arg{type} + \arg{sym-font-1} \arg{slot-1}\\ + \null\hfill \arg{sym-font-2} \arg{slot-2} +\end{decl} +Defines \m{cmd} to be a math delimiter where the small variant is in +slot \m{slot-1} of symbol font \m{sym-font-1} and the large +variant is in slot \m{slot-2} of symbol font \m{sym-font-2}. +Both symbol fonts must have been declared previously. + +Checks that \m{sym-font-i} are both declared symbol fonts. + +If \TeX{} is not looking for a delimiter, \m{cmd} is treated just as +if it had been defined with |\DeclareMathSymbol| using +\m{type}, \m{sym-font-1} and \m{slot-1}. In other words, if a +command is defined as a delimiter then this automatically defines it +as a math symbol. + +\NEWdescription{1998/06/01} +In case \m{cmd} is a single character such as `|[|', the same syntax is +used. Previously the \arg{type} argument was not present (and thus the +corresponding math symbol declaration had to be provided separately). + +Example: +\begin{verbatim} + \DeclareMathDelimiter{\langle}{\mathopen}{symbols}{"68} + {largesymbols}{"0A} + \DeclareMathDelimiter{(} {\mathopen}{operators}{"28} + {largesymbols}{"00} +\end{verbatim} + + +\begin{decl} +|\DeclareMathAccent| \arg{cmd} \arg{type} \arg{sym-font} \arg{slot} +\end{decl} + +Defines \m{cmd} to act as a math accent. + +The accent character comes from slot \m{slot} in +\m{sym-font}. The \m{type} can be either +|\mathord| or |\mathalpha|; in the latter case the accent character +changes font when used in a math alphabet. + +Example: +\begin{verbatim} + \DeclareMathAccent{\acute}{\mathalpha}{operators}{"13} + \DeclareMathAccent{\vec}{\mathord}{letters}{"7E} +\end{verbatim} + + +\begin{decl} +|\DeclareMathRadical| \arg{cmd} + \arg{sym-font-1} \arg{slot-1}\\ + \null\hfill \arg{sym-font-2} \arg{slot-2} +\end{decl} + +Defines \m{cmd} to be a radical where the small variant is in +slot \m{slot-1} of symbol font \m{sym-font-1} and the +large variant is in slot \m{slot-2} of symbol font +\m{sym-font-2}. Both symbol fonts must have been declared +previously. + +Example (probably the only use for it!): +\begin{verbatim} + \DeclareMathRadical{\sqrt}{symbols}{"70}{largesymbols}{"70} +\end{verbatim} + +\subsection{Declaring math sizes} + +\begin{decl} +|\DeclareMathSizes| \arg{t-size} \arg{mt-size} \arg{s-size} + \arg{ss-size} +\end{decl} + +Declares that \m{mt-size} is the (main) math text size, \m{s-size} is +the `script' size and \m{ss-size} the `scriptscript' size to be used +in math, when \m{t-size} is the current text size. For text sizes for +which no such declaration is given the `script' and `scriptscript' +size will be calculated and then fonts are loaded for the calculated +sizes or the best approximation (this may result in a warning +message). + +Normally, \m{t-size} and \m{mt-size} will be identical; however, if, +for example, PostScript text fonts are mixed with bit-map math fonts +then you may not have available a \m{mt-size} for every \m{t-size}. + +Example: +\begin{verbatim} + \DeclareMathSizes{13.82}{14.4}{10}{7} +\end{verbatim} + +\section{Font installation} +\label{Sec:install} + +This section explains how \LaTeX's font attributes are turned into +\TeX{} font specifications. + +\subsection{Font definition files} + +\NEWdescription{1997/12/01} +The description of how \LaTeX{} font attributes are turned into \TeX{} +fonts is usually kept in a \emph{font definition file} (|.fd|). The +file for family \m{family} in encoding \m{ENC} must be +called |<enc><family>.fd|: for example, |ot1cmr.fd| for Computer +Modern Roman with encoding |OT1| or |t1ptm.fd| for Adobe Times with +encoding |T1|. Note that encoding names are converted to lowercase +when used as part of file names. + +Whenever \LaTeX{} encounters an encoding/family combination that it +does not know (e.g.~if the document designer says +|\fontfamily{ptm}\selectfont|) then \LaTeX{} attempts to load the +appropriate |.fd| file. ``Not known'' means: there was no +|\DeclareFontFamily| declaration issued for this encoding/family +combination. If the |.fd| file could not be found, a warning is +issued and font substitutions are made. + +The declarations in the font definition file are responsible for +telling \LaTeX{} how to load fonts for that encoding/family +combination. + +\subsection{Font definition file commands} + +\emph{Note}: A font definition file should contain only commands +from this subsection. + +Note that these commands can also be used outside a font definition +file: they can be put in package or class files, or even in the +preamble of a document. + +\begin{decl} + |\ProvidesFile{<file-name>}[<release-info>]| +\end{decl} +The file should announce itself with a |\ProvidesFile| command, +as described in \emph{\clsguide}. For example: +\begin{verbatim} + \ProvidesFile{t1ptm.fd}[1994/06/01 Adobe Times font definitions] +\end{verbatim} + +Spaces within the arguments specific to font definition files are +ignored to avoid surplus spaces in the document. If a real space is +necessary use |\space|. +\NEWdescription{2004/02/10}However, note that this is only true if the +declaration is made at top level! If used within the definition of +another command, within |\AtBeginDocument|, option code or in similar +places, then spaces within the argument will remain and may result in +incorrect table entries. + +\begin{decl} +|\DeclareFontFamily| \arg{encoding} \arg{family} \arg{loading-settings} +\end{decl} + +Declares a font family \m{family} to be available in encoding scheme +\m{encoding}. + +The \m{loading-settings} are executed immediately after loading any +font with this encoding and family. + +Checks that \m{encoding} was previously declared. + +This example refers to the Computer Modern Typewriter font family in +the Cork encoding: +\begin{verbatim} + \DeclareFontFamily{T1}{cmtt}{\hyphenchar\font=-1} +\end{verbatim} + +Each |.fd| file should contain exactly one |\DeclareFontFamily| +command, and it should be for the appropriate encoding/family +combination. + +\begin{decl} +|\DeclareFontShape| \arg{encoding} \arg{family} \arg{series} + \arg{shape}\\ + \null\hfill \arg{loading-info} \arg{loading-settings} +\end{decl} + +Declares a font shape combination; here \m{loading-info} contains the +information that combines sizes with external fonts. The syntax is +complex and is described in Section~\ref{sec:loadinfo} below. + +The \m{loading-settings} are executed after loading any font with this +font shape. They are executed immediately after the +`loading-settings' which were declared by |\DeclareFontFamily| and so +they can be used to overwrite the settings made at the family level. + +Checks that the combination \m{encoding}\m{family} was previously +declared via |\DeclareFontFamily|. + +Example: +\begin{verbatim} + \DeclareFontShape{OT1}{cmr}{m}{sl}{% + <<5-8>> sub * cmr/m/n + <<8>> cmsl8 + <<9>> cmsl9 + <<10>> <<10.95>> cmsl10 + <<12>> <<14.4>> <<17.28>> <<20.74>> <<24.88>> cmsl12 + }{} +\end{verbatim} +The file can contain any number of |\DeclareFontShape| commands, +which should be for the appropriate \m{encoding} and \m{family}. + +\NEWfeature{1996/06/01} +The font family declarations for the |OT1|-encoded fonts now all +contain: +\begin{verbatim} + \hyphenchar\font=`\- +\end{verbatim} +This enables the use of an alternative |\hyphenchar| in other encodings +whilst maintaining the correct value for all fonts. + +\subsection{Font file loading information} +\label{sec:loadinfo} + +The information which tells \LaTeX{} exactly which font (\texttt{.tfm}) +files to load is contained in the \m{loading-info} part of a +|\DeclareFontShape| declaration. This part consists of one or more +\m{fontshape-decl}s, each of which has the following form: + +\begin{center} +\begin{tabular}{r@{ $::=$ }l} + \m{fontshape-decl} & \m{size-infos} \m{font-info} \\ + \m{size-infos} & \m{size-infos} \m{size-info} $\mid$ + \m{size-info} \\ + \m{size-info} & ``|<<|'' \m{number-or-range} ``|>>|'' \\ + \m{font-info} & $[$ \m{size-function} ``|*|'' $]$ + $[$ ``|[|'' \m{optarg} ``|]|'' $]$ \m{fontarg} \\ +\end{tabular} +\end{center} +The \m{number-or-range} denotes the size or size-range +for which this entry applies. + +If it contains a hyphen it is a +range: lower bound on the left (if missing, zero implied), upper bound +on the right (if missing, $\infty$ implied). For ranges, the +upper bound is \emph{not} included in the range and the lower bound is. + +Examples: +\begin{center} +\begin{tabular}{lll} + |<<10>>| & simple size& 10pt only\\ + |<<-8>>| & range& all sizes less than 8pt\\ + |<<8-14.4>>| & range& all sizes greater than or equal to 8pt\\ + & & \ but less than 14.4pt\\ + |<<14.4->>| & range& all sizes greater than or equal 14.4pt +\end{tabular} +\end{center} +If more than one \m{size-info} entry follows without any +intervening \m{font-info}, they all share the next \m{font-info}. + +The \m{size-function}, if present, handles the use of \m{font-info}. +If not present, the `empty' \m{size-function} is assumed. + +All the \m{size-info}s are inspected in the order in which they appear +in the font shape declaration. If a \m{size-info} matches the +requested size, its \m{size-function} is executed. If |\external@font| +is non-empty afterwards this process stops, otherwise the next +\m{size-info} is inspected. (See also |\DeclareSizeFunction|.) + +If this process does not lead to a non-empty |\external@font|, +\LaTeX{} tries the nearest simple size. If the entry contains only +ranges an error is returned. + + +\subsection{Size functions} +\label{sec:sizefunct} + + +\LaTeX{} provides the following size functions, whose `inputs' are +\m{fontarg} and \m{optarg} (when present). + +\begin{description} +\item[`' (empty)] +Load the external font \m{fontarg} at the user-requested size. If +\m{optarg} is present, it is used as the scale-factor. + +\item[s] +Like the empty function but without terminal warnings, only +loggings. + +\item[gen] +Generates the external font from \m{fontarg} followed by +the user-requested size, e.g.~|<<8>> <<9>> <<10>> gen * cmtt| + +\item[sgen] +Like the `gen' function but without terminal warnings, only loggings. + +\item[genb] +\NEWfeature{1995/12/01} +Generates the external font from \m{fontarg} followed by +the user-requested size, using the conventions of the `ec' fonts. +e.g.~|<<10.98>> genb * dctt| produces |dctt1098|. + +\item[sgenb] +\NEWfeature{1995/12/01} +Like the `genb' function but without terminal warnings, only loggings. + +\item[sub] +Tries to load a font from a different font shape declaration given by +\m{fontarg} in the form \m{family}|/|\m{series}|/|\m{shape}. + +\item[ssub] +Silent variant of `sub', only loggings. + +\item[subf] +Like the empty function but issues a warning that it has to substitute +the external font \m{fontarg} because the desired font shape was not +available in the requested size. + +\item[ssubf] +Silent variant of `subf', only loggings. + +\item[fixed] +Load font \m{fontarg} as is, disregarding the user-requested size. +If present, \m{optarg} gives the ``at \ldots pt'' size to be used. + +\item[sfixed] +Silent variant of `fixed', only loggings. + +\end{description} + +Examples for the use of most of the above size functions can be found +in the file |cmfonts.fdd|---the source for the standard |.fd| files +describing the Computer Modern fonts by Donald Knuth. + + +\begin{decl} +|\DeclareSizeFunction| \arg{name} \arg{code} +\end{decl} + +Declares a size-function \m{name} for use in |\DeclareFontShape| +commands. The interface is still under development but there should be +no real need to a define new size functions. + +The \m{code} is executed when the size or size-range in +|\DeclareFontShape| matches the user-requested size. + +The arguments of the size-function are automatically parsed and placed +into |\mandatory@arg| and |\optional@arg| for use in \m{code}. Also +available, of course, is |\f@size|, which is the user-requested size. + +To signal success \m{code} must define the command |\external@font| +to contain the external name and any scaling options (if present) for +the font to be loaded. + +This example sets up the `empty' size function (simplified): +\begin{verbatim} + \DeclareSizeFunction{} + {\edef\external@font{\mandatory@arg\space at\f@size} +\end{verbatim} + + +\section{Encodings} +\label{Sec:encode} + +This section explains how to declare and use new font encodings and +how to declare commands for use with particular encodings. + +\subsection{The \textsf{fontenc} package} + +Users can select new font encodings using the |fontenc| package. The +|fontenc| package has options for encodings; the last option becomes +the default encoding. For example, to use the |OT2| (Washington +University Cyrillic encoding) and |T1| encodings, with |T1| as the +default, an author types: +\begin{verbatim} + \usepackage[OT2,T1]{fontenc} +\end{verbatim} + +\NEWdescription{1997/12/01} +For each font encoding \m{ENC} given as an option, this package loads +the \emph{encoding definition} (|<enc>enc.def|, with an all +lower-case name) file; it also sets |\encodingdefault| to be the last +encoding in the option list. + +The declarations in the encoding definition file |<enc>enc.def| for +encoding \m{ENC} are responsible for declaring this encoding and +telling \LaTeX{} how to produce characters in this encoding; this file +should contain nothing else (see Section~\ref{Sec:encode.def}. + +The standard \LaTeX{} format declares the |OT1| and |T1| text +encodings by inputting the files |ot1enc.def| and |t1enc.def|; it also +sets up various defaults which require that |OT1|-encoded fonts are +available. +Other encoding set-ups might be added to the distribution at a +later stage. + +Thus the example above loads the files |ot2enc.def| and |t1enc.def| +and sets |\encodingdefault| to |T1|. + +\emph{Warning}: If you wish to use |T1|-encoded fonts other than the `cmr' +family then you may need to load the package (e.g.~\texttt{times}) +that selects the fonts \emph{before} loading \texttt{fontenc} (this +prevents the system from attempting to load any |T1|-encoded fonts from +the `cmr' family). + + + +\subsection{Encoding definition file commands} +\label{Sec:encode.def} + +\emph{Note}: An encoding definition file should contain only commands +from this subsection. + +\NEWdescription{2019/07/10} +As an exception it may also contain a |\DeclareFontsubstitution| +declaration (described in \ref{sec:encoding-defaults}) to specify how +font substitution for this encoding should be handled. In that case +it is important that the values used point to a font that is guaranteed +to be available on all \LaTeX{} installations.\footnote{If the font + encoding file is made available as part of a CTAN bundle, that could + be a font that is provided together with that bundle, but it should + not point to font which requires further installation steps and + therefore may or may not be installed.} + + +\NEWdescription{1997/12/01} +As with the font definition file commands, it is also possible +(although normally not necessary) to use these declarations directly +within a class or package file. + +\emph{Warning}: Some aspects of the contents of font definition files +are still under development. Therefore, the current versions of the +files |ot1enc.def| and |t1enc.def| are temporary versions and should +not be used as models for producing further such files. For further +information you should read the documentation in |ltoutenc.dtx|. + +\begin{decl} + |\ProvidesFile{<file-name>}[<release-info>]| +\end{decl} +The file should announce itself with a |\ProvidesFile| +command, described in \emph{\clsguide}. For example: +\begin{verbatim} + \ProvidesFile{ot2enc.def} + [1994/06/01 Washington University Cyrillic encoding] +\end{verbatim} + + +\begin{decl} +|\DeclareFontEncoding| \arg{encoding} \arg{text-settings} + \arg{math-settings} +\end{decl} + +Declares a new encoding scheme \m{encoding}. + +The \m{text-settings} are +declarations which are executed every time |\selectfont| changes the +encoding to be \m{encoding}. + +The \m{math-settings} are similar but are for math alphabets. They +are executed whenever a math alphabet with this encoding is +called. + +\NEWfeature{1998/12/01} +It also saves the value of \m{encoding} in the macro +|\LastDeclaredEncoding|. + +Example: +\begin{verbatim} + \DeclareFontEncoding{OT1}{}{} +\end{verbatim} + +Some author commands need to change their definition depending on +which encoding is currently in use. For example, in the |OT1| +encoding, the letter `\AE' is in slot |"1D|, whereas in the |T1| +encoding it is in slot |"C6|. So the definition of |\AE| has to +change depending on whether the current encoding is |OT1| or |T1|. +The following commands allow this to happen. + +\begin{decl} + |\DeclareTextCommand| \arg{cmd} \arg{encoding} + \oarg{num} \oarg{default} \arg{definition} +\end{decl} +This command is like |\newcommand|, except that it defines a +command which is specific to one encoding. For example, the +definition of |\k| in the |T1| encoding is: +\begin{verbatim} + \DeclareTextCommand{\k}{T1}[1] + {\oalign{\null#1\crcr\hidewidth\char12}} +\end{verbatim} +|\DeclareTextCommand| takes the same optional arguments as +|\newcommand|. + +The resulting command is +robust, even if the code in \m{definition} is fragile. + +It does not produce an error if the command has already +been defined but logs the redefinition in the transcript file. + +\begin{decl}[1994/12/01] + |\ProvideTextCommand| \arg{cmd} \arg{encoding} + \oarg{num} \oarg{default} \arg{definition} +\end{decl} +This command is the same as |\DeclareTextCommand|, except that +if \m{cmd} is already defined in encoding \m{encoding}, then the +definition is ignored. + +\begin{decl} + |\DeclareTextSymbol| \arg{cmd} \arg{encoding} \arg{slot} +\end{decl} +This command defines a text symbol with slot \m{slot} in the +encoding. For example, the definition of |\ss| in the |OT1| encoding +is: +\begin{verbatim} + \DeclareTextSymbol{\ss}{OT1}{25} +\end{verbatim} +It does not produce an error if the command has already +been defined but logs the redefinition in the transcript file. + +\begin{decl} + |\DeclareTextAccent| \arg{cmd} \arg{encoding} \arg{slot} +\end{decl} +This command declares a text accent, with the accent taken from slot +\m{slot} in the encoding. For example, the definition of |\"| in +the |OT1| encoding is: +\begin{verbatim} + \DeclareTextAccent{\"}{OT1}{127} +\end{verbatim} +It does not produce an error if the command has already +been defined but logs the redefinition in the transcript file. + +\begin{decl} + |\DeclareTextComposite| \arg{cmd} \arg{encoding} \arg{letter} + \arg{slot} +\end{decl} +This command declares that the composite letter formed from applying +\m{cmd} to \m{letter} is defined to be simply slot \m{slot} in the +encoding. The \m{letter} should be a single letter (such as |a|) or +a single command (such as |\i|). + + +For example, the definition of |\'{a}| +in the |T1| encoding could be declared like this: +\begin{verbatim} + \DeclareTextComposite{\'}{T1}{a}{225} +\end{verbatim} + +The \m{cmd} will normally have been previously declared +for this encoding, either by using +|\DeclareTextAccent|, or as a one-argument |\DeclareTextCommand|. + +\begin{decl}[1994/12/01] + |\DeclareTextCompositeCommand| \arg{cmd} \arg{encoding} \arg{letter} + \arg{definition} +\end{decl} +This is a more general form of |\DeclareTextComposite|, which allows +for an arbitrary \m{definition}, not just a \m{slot}. The main use +for this is to allow accents on |i| to act like accents on |\i|, for +example: +\begin{verbatim} + \DeclareTextCompositeCommand{\'}{OT1}{i}{\'\i} +\end{verbatim} +It has the same restrictions as |\DeclareTextComposite|. + + +\begin{decl}[1998/12/01] + |\LastDeclaredEncoding| +\end{decl} +This holds the name of the last encoding declared via +|\DeclareFontEncoding| (this should also be the currently most +efficient encoding). It can be used in the \m{encoding} argument +of the above declarations in place of explicitly mentioning the +encoding, e.g. +\begin{verbatim} + \DeclareFontEncoding{T1}{}{} + \DeclareTextAccent{\`}{\LastDeclaredEncoding}{0} + \DeclareTextAccent{\'}{\LastDeclaredEncoding}{1} +\end{verbatim} +This can be useful in cases where encoding files sharing common code +are generated from one source. + + +\subsection{Default definitions} + +\NEWdescription{1997/12/01} +The declarations used in encoding definition files define +encoding-specific commands but they do not allow those commands to be +used without explicitly changing the encoding. For some commands, +such as symbols, this is not enough. For example, the~|OMS| encoding +contains the symbol~`\S', but we need to be able to use the +command~|\S| whatever the current encoding may be, without explicitly +selecting the encoding~|OMS|. + +\NEWdescription{1997/12/01} +To allow this, \LaTeX{} has commands that declare default definitions +for commands; these defaults are used when the command is not defined +in the current encoding. For example, the default encoding for~|\S| +is~|OMS|, and so in an encoding (such as |OT1|) which does not +contain~|\S|, the~|OMS| encoding is selected in order to access this +glyph. But in an encoding (such as~|T1|) which does contain~|\S|, the +glyph in that encoding is used. The standard \LaTeXe{} format sets +up several such defaults using the following encodings: |OT1|,~|OMS| +and~|OML|. + +\emph{Warning}: These commands should \emph{not} occur in encoding +definition files, since those files should declare only commands for use +when that encoding has been selected. They should instead be placed +in packages; they must, of course, always refer to encodings that are +known to be available. + +\begin{decl}[1994/12/01] + |\DeclareTextCommandDefault| \arg{cmd} \arg{definition} +\end{decl} +This command allows an encoding-specific command to be given a default +definition. For example, the default definition for |\copyright| is +defined be be a circled `c' with: +\begin{verbatim} + \DeclareTextCommandDefault{\copyright}{\textcircled{c}} +\end{verbatim} +\begin{decl}[1994/12/01] + |\DeclareTextAccentDefault| \arg{cmd} \arg{encoding} \\ + |\DeclareTextSymbolDefault| \arg{cmd} \arg{encoding} +\end{decl} +These commands allow an encoding-specific command to be given a +default encoding. For example, the default encoding for |\"| and +|\ae| is set to be |OT1| by: +\begin{verbatim} + \DeclareTextAccentDefault{\"}{OT1} + \DeclareTextSymbolDefault{\ae}{OT1} +\end{verbatim} +Note that |\DeclareTextAccentDefault| can be used on any one-argument +encoding-specific command, not just those defined with +|\DeclareTextAccent|. Similarly, |\DeclareTextSymbolDefault| can be +used on any encoding-specific command with no arguments, not just +those defined with |\DeclareTextSymbol|. + +For more examples of these definitions, see |ltoutenc.dtx|. + +\begin{decl}[1994/12/01] + |\ProvideTextCommandDefault| \arg{cmd} \arg{definition} +\end{decl} +This command is the same as |\DeclareTextCommandDefault|, except that +if the command already has a default definition, then the definition +is ignored. This is useful to give `faked' definitions of symbols +which may be given `real' definitions by other packages. For example, +a package might give a fake definition of |\textonequarter| by saying: +\begin{verbatim} + \ProvideTextCommandDefault{\textonequarter}{$\m@th\frac14$} +\end{verbatim} + + \subsection{Encoding defaults} \label{sec:encoding-defaults} + +\begin{decl} +|\DeclareFontEncodingDefaults| \arg{text-settings} \arg{math-settings} +\end{decl} + +Declares \m{text-settings} and \m{math-settings} for all encoding +schemes. These are executed before the encoding scheme dependent ones +are executed so that one can use the defaults for the major cases and +overwrite them if necessary using |\DeclareFontEncoding|. + +If |\relax| is used as an argument, the current setting of this default +is left unchanged. + +This example is used by amsfonts.sty for accent positioning; it changes +only the math settings: +\begin{verbatim} + \DeclareFontEncodingDefaults{\relax}{\def\accentclass@{7}} +\end{verbatim} + + +\begin{decl} +|\DeclareFontSubstitution| \arg{encoding} \arg{family} \arg{series} + \arg{shape} +\end{decl} + +Declares the default values for font substitution which will be used +when a font with encoding \m{encoding} +should be loaded but no font can be found with the current +attributes. + +These substitutions are local to the encoding scheme because the +encoding scheme is never substituted! They are tried in the order +\m{shape} then \m{series} and finally \m{family}. + +\NEWdescription{2019/07/10} +This declaration is normally done in an encoding definition file +(see~\ref{Sec:encode.def}), but can also be used in a class file or +the document preamble to alter the default for a specific encoding. + +If no defaults are set up for an encoding, the values given by +|\DeclareErrorFont| are used. + +The font specification for +\m{encoding}\m{family}\m{series}\m{shape} +must have been defined by |\DeclareFontShape| +before the |\begin{document}| is reached. + +Example: +\begin{verbatim} + \DeclareFontSubstitution{T1}{cmr}{m}{n} +\end{verbatim} + +\subsection{Case changing} +\label{sec:case} + +\begin{decl} + |\MakeUppercase| \arg{text} \\ + |\MakeLowercase| \arg{text} +\end{decl} + +\NEWfeature{1995/06/01} +\TeX{} provides the two primitives |\uppercase| and |\lowercase| for +changing the case of text. Unfortunately, these \TeX{} primitives do +not change the case of characters accessed by commands like |\ae| or +|\aa|. To overcome this problem, \LaTeX{} provides these two commands. + +In the long run, we would like to use all-caps fonts rather than any +command like |\MakeUppercase| but this is not possible at the moment +because such fonts do not exist. + +For further details, see \texttt{clsguide.tex}. + +\NEWdescription{1999/04/23} +In order that upper/lower-casing will work reasonably well, and in +order to provide any correct hyphenation, \LaTeXe{} \emph{must} use, +throughout a document, the same fixed table for changing case. The +table used is designed for the font encoding |T1|; this works well +with the standard \TeX{} fonts for all Latin alphabets but will cause +problems when using other alphabets. As an experiment, it has now +been extended for use with some Cyrillic encodings. + + +\section{Miscellanea} +\label{Sec:misc} + +This section covers the remaining font commands in \LaTeX{} and some +other issues. + +\subsection{Font substitution} + +\begin{decl} +|\DeclareErrorFont| \arg{encoding} \arg{family} \arg{series} + \arg{shape} \arg{size} +\end{decl} + +Declares \m{encoding}\m{family}\m{series}\m{shape} to be the font shape +used in cases where the standard substitution mechanism fails +(i.e.~would loop). For the standard mechanism see the command +|\DeclareFontSubstitution| above. + +The font specification for +\m{encoding}\m{family}\m{series}\m{shape} +must have been defined by |\DeclareFontShape| +before the |\begin{document}| is reached. + +Example: +\begin{verbatim} + \DeclareErrorFont{OT1}{cmr}{m}{n}{10} +\end{verbatim} + +\NEWdescription{2019/07/10} +This declaration is a system wide fallback and it should normally not +be changed, in particular it does not belong into font encoding +definition files but rather into the \LaTeX{} format. It is normally +set up in \texttt{fonttext.cfg}. Adjustments on a per encoding base +should be made through |\DeclareFontSubstitution| instead! + + +\begin{decl} +|\fontsubfuzz| +\end{decl} + +This parameter is used to decide whether or not to produce a terminal +warning if a font size substitution takes place. If the difference +between the requested and the chosen size is less than |\fontsubfuzz| +the warning is only written to the transcript file. The default value +is |0.4pt|. This can be redefined with |\renewcommand|, for example: +\begin{verbatim} + \renewcommand{\fontsubfuzz}{0pt} % always warn +\end{verbatim} + +\subsection{Preloading} + +\begin{decl} +|\DeclarePreloadSizes| \arg{encoding} \arg{family} \arg{series} + \arg{shape} +\arg{size-list} +\end{decl} + + +Specifies the fonts that should be preloaded by the format. These +commands should be put in a |preload.cfg| file, which is read in when +the \LaTeX{} format is being built. +Read |preload.dtx| for more information on how to built such a +configuration file. + +Example: +\begin{verbatim} + \DeclarePreloadSizes{OT1}{cmr}{m}{sl}{10,10.95,12} +\end{verbatim} + +\NEWdescription{2019/07/10} +Preloading is really an artifact of the days when loading fonts while +processing a document contributed substantially to the processing +time. These days it is usually best not to use this mechanism any more. + +\subsection{Accented characters} + +\NEWdescription{1996/06/01} +Accented characters in \LaTeX{} can be produced using commands such as +|\"a| etc. The precise effect of such commands depends on the font +encoding being used. When using a font encoding that contains the +accented characters as individual glyphs (such as the |T1| encoding, +in the case of |\"a|) words that contain such accented characters can +be automatically hyphenated. For font encodings that do not contain +the requested individual glyph (such as the |OT1| encoding) such a +command invokes typesetting instructions that produce the accented +character as a combination of character glyphs and diacritical marks +in the font. In most cases this involves a call to the \TeX{} +primitive |\accent|. Glyphs constructed as composites in this way +inhibit hyphenation of the current word; this is one reason why the +|T1| encoding is preferable to the original \TeX{} font encoding +|OT1|. + +It is important to understand that commands like |\"a| in \LaTeXe{} +represent just a name for a single glyph (in this case `umlaut a') and +contain no information about how to typeset that glyph---thus it does +\emph{not} mean `put two dots on top of the character a'. The +decision as to what typesetting routine to use will depend on the +encoding of the current font and so this decision is taken at the last +minute. Indeed, it is possible that the same input will be typeset in +more than one way in the same document; for example, text in section +headings may also appear in table of contents and in running heads; and +each of these may use a font with a different encoding. + +For this reason the notation |\"a| is \emph{not} equivalent to: +\begin{verbatim} + \newcommand \chara {a} \"\chara +\end{verbatim} +In the latter case, \LaTeX{} does not expand the macro |\chara| but +simply compares the notation (the string |\"\chara|) to its list of +known composite notations in the current encoding; when it fails to +find |\"\chara| it does the best it can and invokes the typesetting +instructions that put the umlaut accent on top of the expansion of +|\chara|. Thus, even if the font actually contains `\"a' as an +individual glyph, it will not be used. + +The low-level accent commands in \LaTeX{} are defined in such a way +that it is possible to combine a diacritical mark from one font with a +glyph from another font; for example, |\"\textparagraph| will produce +\"\textparagraph. The umlaut here +is taken from the |OT1| encoded font |cmr10| whilst the paragraph sign +is from the |OMS| encoded font |cmsy10|. (This example may be +typographically silly but better ones would involve font encodings +like |OT2| (Cyrillic) that might not be available at every +site.) + +There are, however, restrictions on the font-changing commands that +will work within the argument to such an accent command. These are +\TeX{}nical in the sense that they follow from the way that \TeX{}'s +|\accent| primitive works, allowing only a special class of commands +between the accent and the accented character. + +The following are examples of commands that will not work correctly as +the accent will appear above a space: the font commands with text +arguments (|\textbf{...}| and friends); all the font size declarations +(|\fontsize| and |\Large|, etc.); |\usefont| and declarations that +depend on it, such as |\normalfont|; box commands (e.g.~|\mbox{...}|). + +The lower-level font declarations that set the attributes family, +series and shape (such as |\fontshape{sl}\selectfont|) will produce +correct typesetting, as will the default declarations such as +|\bfseries|. + + +\subsection{Naming conventions} + +\begin{itemize} +\item +Math alphabet commands all start with |\math...|: examples are +|\mathbf|, |\mathcal|, etc. + +\item +The text font changing commands with arguments all start with +|\text...|: e.g.~|\textbf| and |\textrm|. The exception to this is +|\emph|, since it occurs very commonly in author documents and so +deserves a shorter name. + +\item +Names for encoding schemes are strings of up to three letters (all +upper case) plus digits. + +The \LaTeX3 project reserves the use of encodings starting with the +following letters: |T| (standard 256-long text encodings), |TS| +(symbols that are designed to extend a corresponding |T| encoding), +|X| (text encodings that do not conform to the strict requirements for +|T| encodings), |M| (standard 256-long math encodings), |S| (other +symbol encodings), |A| (other special applications), |OT| (standard +128-long text encodings) and |OM| (standard 128-long math encodings). + +Please do not use the above starting letters for non-portable +encodings. If new standard encodings emerge then we shall add them in +a later release of \LaTeX. + +Encoding schemes which are local to a site or a system should start +with |L|, experimental encodings intended for wide distribution will +start with |E|, whilst |U| is for Unknown or Unclassified encodings. + +\item +Font family names should contain up to five lower case letters. +Where possible, these should conform to the \emph{Filenames for fonts} +font naming scheme. + +\item +Font series names should contain up to four lower case letters. + +\item +Font shapes should contain up to two letters lower case. + +\item +Names for symbol fonts are built from lower and upper case letters +with no restriction. +\end{itemize} + +Whenever possible, you should use the series and shape names suggested +in \emph{\LaTeXcomp} since this will make it easier to combine new +fonts with existing fonts. + +\NEWdescription{1994/12/01} + Where possible, text symbols should be named as |\text| followed by + the Adobe glyph name: for example |\textonequarter| or + |\textsterling|. Similarly, math symbols should be named as + |\math| followed by the glyph name, for example |\mathonequarter| + or |\mathsterling|. Commands which can be used in text or math can + then be defined using |\ifmmode|, for example: +\begin{verbatim} + \DeclareRobustCommand{\pounds}{% + \ifmmode \mathsterling \else \textsterling \fi + } +\end{verbatim} + Note that commands defined in this way must be robust, in case they + get put into a section title or other moving argument. + +\section{If you need to know more \ldots} + +\NEWdescription{1996/06/01} +The |tracefnt| package provides for tracing the actions concerned with +loading, substituting and using fonts. +The package accepts the following options: +\begin{description} +\item[errorshow] Write all information about font changes, etc.\ but + only to the transcript file unless an error occurs. This means that + information about font substitution will not be shown on the + terminal. + +\item[warningshow] Show all font warnings on the terminal. This + setting corresponds to the default behavior when this + \texttt{tracefnt} package is \emph{not} used! + +\item[infoshow] Show all font warnings and all font info messages + (that are normally only written to the transcript file) also on the + terminal. This is the default when this \texttt{tracefnt} package is + loaded. + +\item[debugshow] In addition to what is shown by \texttt{infoshow}, + show also changes of math fonts (as far as possible): beware, this + option can produce a large amount of output. + +\item[loading] Show the names of external font files when they are + loaded. This option shows only `newly loaded' fonts, not those + already preloaded in the format or the class file before this + \texttt{tracefnt} package becomes active. + +\item[pausing] + Turn all font warnings into errors so that \LaTeX{} will stop. +\end{description} + +\emph{Warning}: The actions of this package can change the layout of a +document and even, in rare cases, produce clearly wrong output, so +it should not be used in the final formatting of `real documents'. + +\begin{thebibliography}{1} + +\bibitem{A-W:MG2004} +Frank Mittelbach and Michel Goossens. +\newblock {\em The {\LaTeX} Companion second edition}. +\newblock With Johannes Braams, David Carlisle, and Chris Rowley. +\newblock Addison-Wesley, Reading, Massachusetts, 2004. + +\bibitem{tub:DKn89} +Donald~E. Knuth. +\newblock Typesetting concrete mathematics. +\newblock {\em {TUG}boat}, 10(1):31--36, April 1989. + +\bibitem{A-W:LLa94} +Leslie Lamport. +\newblock {\em {\LaTeX:} A Document Preparation System}. +\newblock Addison-Wesley, Reading, Massachusetts, second edition, 1994. + +\end{thebibliography} + +\end{document} diff --git a/macros/latex-dev/doc/latexchanges.pdf b/macros/latex-dev/doc/latexchanges.pdf new file mode 100644 index 0000000000..ec91b76940 Binary files /dev/null and b/macros/latex-dev/doc/latexchanges.pdf differ diff --git a/macros/latex-dev/doc/latexchanges.tex b/macros/latex-dev/doc/latexchanges.tex new file mode 100644 index 0000000000..59a8488c2f --- /dev/null +++ b/macros/latex-dev/doc/latexchanges.tex @@ -0,0 +1,756 @@ +% \iffalse meta-comment +% +% Copyright 2015-2019 +% The LaTeX3 Project and any individual authors listed elsewhere +% in this file. +% +% This file is part of the LaTeX base system. +% ------------------------------------------- +% +% 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 +% 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 file has the LPPL maintenance status "maintained". +% +% The list of all files belonging to the LaTeX base distribution is +% given in the file `manifest.txt'. See also `legal.txt' for additional +% information. +% +% The list of derived (unpacked) files belonging to the distribution +% and covered by LPPL is defined by the unpacking scripts (with +% extension .ins) which are part of the distribution. +% +% \fi +% Filename: latexchanges.tex + +\NeedsTeXFormat{LaTeX2e} + +\documentclass{ltxguide} + +\usepackage[T1]{fontenc} + +\title{Changes to the \LaTeXe{} format} + +\author{\copyright~Copyright 2015--2019, \LaTeX3 Project Team.\\ + All rights reserved.} + +\date{2019-10-01} + +% a few commands from doc +\newcommand\Lpack[1]{\mbox{\textsf{#1}}} +\newcommand\DescribeMacro[1]{\texttt{\string#1}} + +\makeatletter % -- provide command introduced in new release + % so this typesets with an old format + +\DeclareTextCommandDefault\textcommabelow[1] + {\hmode@bgroup\ooalign{\null#1\crcr\hidewidth\raise-.31ex + \hbox{\check@mathfonts\fontsize\ssf@size\z@ + \math@fontsfalse\selectfont,}\hidewidth}\egroup} +\makeatother + +\ifx\href\undefined + \newcommand\ghissue[1]{#1} + \newcommand\gnatsissue[1]{#1} + \newcommand\ltnewsissue[1]{\LaTeX\ News~#1} + \newcommand\sxanswer[1]{https://tex.stackexchange.com\slash a\slash #1} + \newcommand\sxquestion[1]{https://tex.stackexchange.com\slash q\slash #1} +\else + \newcommand\ghissue[1]{% + \href{https://github.com/latex3/latex2e/issues/#1}{#1}} + \newcommand\gnatsissue[1]{% + \href{https://www.latex-project.org/cgi-bin/ltxbugs2html?pr=latex/#1}{#1}} + \newcommand\ltnewsissue[1]{% + \href{https://www.latex-project.org/news/latex2e-news/ltnews#1.pdf}{\LaTeX\ News~#1}} + \newcommand\sxanswer[1]{% + \url{https://tex.stackexchange.com/a/#1}} + \newcommand\sxquestion[1]{% + \url{https://tex.stackexchange.com/q/#1}} +\fi + +\begin{document} + +\maketitle + +\tableofcontents + +\newpage + +\section{Introduction} + +This document describes changes that have been made to the +\LaTeX\ format since the 2014/05/01 \LaTeX\ release. + + +As announced in \ltnewsissue{22}, the 2015 \LaTeX{} release adopts a new +policy. Improvements and bug fixes will be made to the format sources, +with the \Lpack{latexrelease} package being available to revert +changes to use definitions from an earlier format. + + +\section{Changes introduced in 2019-10-01} + +\emph{to be added} + +\section{Changes introduced in 2018-12-01} + +Further additions to the characters supported by default in UTF-8. +\verb|\guillemetleft| and \verb|\guillemetright| provided as alias for +the names based on the Adobe font names (\ghissue{65}). + +The use of potrusion in tables of contents is suppressed by default, +see \sxquestion{172785}. + +The handling of visible space in verbation was adjusted for +\ghissue{69} and \ghissue{70}. + +Spaces are removed from the argument passed to BiBTeX, \ghissue{88}. + +New commands \verb\Hwithstroke| and \verb|\hwithstroke| added to T1 encoding support. + +The internal box structure for floats is adjusted to preserve box +levels of split hyperlinks, avoiding a fatal pdftex error. \ghissue{94}. + + +\section{Changes introduced in 2018-04-01 patch~5} +Improved support for non ASCII filenames on the commandline on +filesystems using legacy encodings. + +Adjusted the new package rollback code so that some edge cases where rollback +can not be guaranteed become a warning not an error. + +\section{Changes introduced in 2018-04-01 patch~4} +No changes to the format, but \texttt{docstrip} adjusted so that non-ASCII +\texttt{.ins} files work with the new UTF-8 defaults. + +\section{Changes introduced in 2018-04-01 patch~3} +Additional adjustments for GitHub issues \ghissue{34} and \ghissue{38}, adjustment to the +location of some documentation files, such as \texttt{source2e.tex} to +be installed in the documentation sources not the default \TeX\ input +tree. + + +\section{Changes introduced in 2018-04-01 patch~2} +Additional adjustments for GitHub issues \ghissue{32} and \ghissue{33}. + +\section{Changes introduced in 2018-04-01 patch~1} +Make \verb|\UseRawInputEncoding| and \Lpack{latexrelease} reset \verb|\inputencodingname| +when disabling the UTF-8 input handling. + +\section{Changes introduced in 2018-04-01} +Further details of changes at this release are given in \ltnewsissue{28}, but in brief +the main changes are as listed below. + +The default encoding for files has been changed to UTF-8. + +A new possibility to refer to older versions of packages has been added. + +New commands previously available in \Lpack{remreset} and +\Lpack{chngcntr} packages for controlling counters have been added. + +The definition of \verb|\@ifundefined| has been refined to use the e-\TeX \verb|\ifcsname| +primitive when available, and to avoid defining the command being tested to be \verb|\relax| +in the case that it was previously undefined. + +\section{Changes introduced in 2017-04-15} +Optionally, \LaTeX{} format and package dates may use ISO style dates with +\texttt{-} rather than \texttt{/}. + +For Unicode \TeX{}s, made further adjustments to the composite accent +code in \texttt{tuenc.def}, and further updates tracking changes in +Lua\TeX, now at 1.04. + +Previously defining an encoding-specific composite with an undeclared +accent (or an accent declared later) gave no error, but did nothing useful. +\LaTeX\ will now detect this and give the accent comamnd a default definition +as an error, allowing the declared composite to work as intended. + +The definition of \verb|\-| is adjusted to match the comments in +\gnatsissue{3855} to accomodate non standard settings of \verb|\hyphenchar|. + +In parboxes and similar settings, \verb|\lineskiplimit| is now +reset (to the existing default value, \verb|\normallineskiplimit|). +See \sxanswer{359934}. + + The code for verb|\newpage| has been adjusted to add a test on the value of +\verb|\prevdepth| so that the depth of the last line is preserved in +forced page breaks. + +\section{Changes introduced in 2017/01/01 patch~3} +Emergency patch to correct a typo in a change introduced in patch~2. + +\section{Changes introduced in 2017/01/01 patch~2} +More adjustments for TU encoding, allowing for characters missing in +common system fonts. Additional \texttt{fd} files +for Latin Modern variants are included in the documented sources. + +\section{Changes introduced in 2017/01/01 patch~1} +Fixes to TU encoding definitions for Lua\TeX\ and Xe\TeX. + +\section{Changes introduced in 2017/01/01} + +A new test is added during format making that e\TeX\ extensions are +available. As noted in \LaTeX\ news, e\TeX\ will now be required to +build \LaTeX. + +Further updates tracking changes for Lua\TeX~1.0. + +The definition of \verb|\showhyphens| is changed in formats built +with Xe\TeX, as the original version, inherited from plain \TeX\ does +not work with Xe-\TeX. + +Changes to the default encoding used by Lua\TeX\ and Xe\TeX\ formats to +be TU (Unicode) rather than OT1 (7 bit legacy \TeX\ encoding). + +\section{Changes introduced in 2016/03/31 patch~3} +Fixes to \verb|\newinsert| and \verb|\extrafloats|. + +\section{Changes introduced in 2016/03/31 patch~2} +Adjustments to \verb|\c{g}| in OT1 encoding. + +\section{Changes introduced in 2016/03/31 patch~1} +Adjust the upper limit for Character Class allocation in Xe-\TeX\ to +4096 to match a change in Xe-\TeX. + +\section{Changes introduced in 2016/03/31} +Modify picture mode as suggested in latex/4452 to avoid leaders of +almost zero length. + +Modify the checks in \verb|\DeclareMathSymbol| and related commands +so that they do not give errors with new Lua\TeX\ releases. + +\section{Changes introduced in 2016/02/01} +Adjustments to Lua\TeX\ support to match changes to the Lua\TeX\ engine, +and to the character class allocation in Xe\TeX. + +Load Unicode data from new generic \texttt{unicode-data} distribution. + +\section{Changes introduced in 2015/10/01 patch~2} + +This release fixes the behaviour of the allocation mechanism if the switch +from the standard to extended pool takes place within a group. + +\section{Changes introduced in 2015/10/01 patch~1} +This release allows \Lpack{latexrelease} to revert the +Lua\TeX{}-specific +changes, in particular fixing an incorrect date in part of the mechanism and +adding a method to disable callback management entirely. + +\section{Changes introduced in \LaTeX\ 2015/10/01} + +\subsection{LuaTeX allocation} +Almost all changes at this release relate to incorporating allocation macros for luatex into the format +as done for etex and xetex in 2015/01/01. For details see |ltluatex.dtx| or \ltnewsissue{22}. +|ltluatex.dtx| now forms a new chapter (N) in the documented sources, |source2e.tex|. + + +\subsection{Increased number of floats} +The default float list has been increased from 18 to 52 registers if +e\TeX\ is available. +The list can be increased further using |\extrafloats| however this +default allocation uses classic registers below 256 so the registers are +also available for |\newinsert| as described below. + +\subsection{Improved \texttt{\textbackslash newinsert}} +The command |\newinsert| has been extended to take registers from the lists of free float +registers once the classic register allocation is used up. This should make it highly unlikely +to get ``no room'' errors on register allocation assuming the format is used with +an e-\TeX\ based \TeX\ engine. + +\subsection{New accent, \texttt{\textbackslash textcommabelow} (pr/4414)} +The command |\textcommabelow| has been added. This is mainly intended for Romanian letters +\textcommabelow{S}\,\textcommabelow{s}\,\textcommabelow{T}\,\textcommabelow{t}. + +\subsection{Unicode 8} +The file |unicode-letters.def| used to initialise character data in +Unicode \TeX\ variants has been regenerated from data files updated +to Unicode~8. + +\section{Changes introduced in 2015/01/01 patch~2} +There were no changes to the format at this release, but the sources were fixed to fix bug latex/4434 +affecting bottom float positioning if the \Lpack{latexrelease} package was used. + +\section{Changes introduced in 2015/01/01 patch~1} +This release re-introduces the ``Patch Level'' scheme for identifying +releases between main ``dated'' releases. Early \LaTeXe\ releases +included a mechanism whereby updates could be provided by a +\emph{patch + file}. This was mainly intended to allow updates to be made without +downloading the full sources again, which was an important +consideration with download speeds and costs at the time. + +The new mechanism incorporates any changes directly into the sources, +but having the patch level identified in the banner allows the +\LaTeX\ release to be identified, even if (as in this case) most of the +changes do not affect the format but affect other base packages such +as \Lpack{latexrelease} and \Lpack{inputenc}. The patch level is shown +in the banner at the start of the job, but does not affect the date +handling of the |\IncludeInRelease| mechanism. + +Apart from re-arranging the version banner, the only change in the +format is that |\newtoks| was accidentally defined twice, using the +old and new allocation scheme described in Section \ref{e@alloc}. +The old definition is now only in the \Lpack{latexrelease} package, +for use when emulating old formats. + + + + +\section +[Changes between \LaTeX\ releases 2014/05/01 and 2015/01/01] +{Changes between \LaTeX\ releases 2014/05/01 and 2015/01/01\footnote{Much of this text +is taken from \Lpack{fixltx2e} package which was formerly used to make such changes available separately.}} + +\subsection{Support for \LaTeX\ version changes} +\DescribeMacro{\includeInRelease}\arg{date}\oarg{date}\arg{label}\arg{message}\arg{code} + +\smallskip + +The |\includeInRelease| command has been added to support backward and +forward compatibility for the \LaTeX\ format. It supports the +declaration of conditional code that can be loaded based on options +given to the \Lpack{latexrelease} package. Its use is described in +detail in the \Lpack{latexrelease} package documentation. + +\subsection{New Allocation Code\label{e@alloc}} +Previously |\newcount| and related commands were based on classic TeX +and only allocated in the range 0--255. This was extended (in +different ways) for e-\TeX\ in the |etex| package and in the +|xelatex.ini| and |lualatex.ini| files used in those formats. Related +to this the number of boxes allocated to store floats was +limited. This was extended to a certain extent in the |morefloats| +package (by Don Hosek and H.-Martin Muench) but the new allocation +incorporates float allocation directly and supports much larger float +lists using the extended registers. + +The new code allocates registers in the full extended range ( +$2^{15}-1$ for etex and xelatex, $2^{16}-1$ for lualatex. +In addition a new command |\extrafloats| is provided. + +\DescribeMacro{\extrafloats}\arg{number} +\smallskip + +This allocates additional registers for the \LaTeX\ float system to +hold figures and tables etc. Similar functionality has been +available via the \Lpack{morefloats} package but this is a different +implementation using extended e-\TeX\ registers when available so +allows many more registers to be reserved for floats as they are +allocated from a pool of 32 or 64 thousand rather than 256 registers, +depending on the engine in use. + +\DescribeMacro{\newmarks}\arg{command} +\smallskip + +e-\TeX\ only, previously available via the \Lpack{etex} package. +Allocates commands to use the extended e-\TeX\ mark mechanism. + +\DescribeMacro{\newXeTeXintercharclass}\arg{command} +\smallskip + +Xe-\TeX\ only, previously in the Xe-\LaTeX\ format, but added via +|xelatex.ini| not part of the core release. +Allocates commands to use the Xe-\TeX\ character class mechanism. + + +\subsection{e-\TeX\ tracing if available} +|\loggingall| (Usually used via |\tracingall|) is extended to enable +additional e-\TeX\ tracing if e-\TeX\ is available. (|\tracingall| +extension has been available as part of the |etex| package previously). + +Also based on code from the |etex| package, a command |\tracingnone| +is added to reverse the effects of |\tracingall| and turn off all primitive +\TeX\ tracing. A new command |\hideoutput| has been added which resets the +tracing parameters set by |\showoutput|. + + + + +\subsection{\texttt{\textbackslash textsubscript} not defined in + latex.ltx (pr/3492)} + +\begin{verbatim} +>>Number: 3492 +>>Category: latex +>>Synopsis: \textsubscript not defined in latex.ltx +>>Arrival-Date: Tue Jan 14 23:01:00 CET 2003 +>>Originator: Ionel Mugurel Ciobica + +I use \textsubscript much more often than \textsuperscript, and +\textsubscript it is not defined in latex.ltx. Could you please +consider including the definition of \textsubscript in the latex.ltx +for the next versions of LaTeX. Thank you. +\end{verbatim} + +\subsection{\texttt{\textbackslash @} discards spaces when moving + (pr/3039)} + +\begin{verbatim} +>>Number: 3039 +>>Category: latex +>>Synopsis: \@ discards spaces when moving +>>Arrival-Date: Sat May 22 09:01:06 1999 +>>Originator: Donald Arseneau +>>Description: +The \@ command expands to \spacefactor\@m in auxiliary files, +which then ignores following spaces when it is reprocessed. +\end{verbatim} + +\subsection{1-col fig can come before earlier 2-col fig + (pr/2346)} + +\begin{verbatim} +>>Number: 2346 +>>Category: latex +>>Synopsis: 2-col: 1-col fig can come before earlier 2-col fig +>>Arrival-Date: Wed Dec 18 15:41:07 1996 +>>Originator: bil kleb +>>Description: +as documented in Lamport's book, p. 198, concerning figure +placement, "a figure will not be printed before an earlier +figure, and a table will not be printed before an earlier +table." however, there is a footnote stating, "However, +in two-column page style, a single-column figure can come before +an earlier double-column figure, and vice versa." + +This twocolumn behavior is undesirable---at least by me and +most professional organizations i publish in. ed snyzter developed +a hack fix for 2.09 several years ago which links the two +counters, but i have not run across a similar "fix" for 2e... +\end{verbatim} + +Originally fixed in package \Lpack{fix2col} which was merged into +this package. Documentation and code from this package have been +merged into this file. + +\subsubsection{Notes on the Implementation Strategy} + +The standard output routine maintains two lists of floats that have +been `deferred' for later consideration. One list for single column +floats, and one for double column floats (which are always +immediately put onto their deferred list). This mechanism means +that \LaTeX\ `knows' which type of float is contained in each box +by the list that it is processing, but having two lists means +that there is no mechanism for preserving the order between the +floats in each list. + +The solution to this problem consists of two small changes to +the output routine. + +Firstly, abandon the `double column float list' |\@dbldeferlist| +and change every command where it is used so that instead the +same |\@deferlist| is used as for single column floats. +That one change ensures that double and single column floats +stay in the same sequence, but as \LaTeX\ no longer `knows' +whether a float is double or single column, it will happily +insert a double float into a single column, overprinting the +other column, or the margin. + +The second change is to provide an alternative mechanism for +recording the two column floats. \LaTeX\ already has a compact +mechanism for recording float information, an integer count register +assigned to each float records information about the `type' of float +`figure', `table' and the position information `htp' etc. + +The type information is stored in the `high' bits, one bit position +(above `32') allocated to each float type. The `low' bits store +information about the allowed positions, one bit each allocated for +|h t b p|. In the \LaTeX2.09 system, the bit corresponding to `16' +formed a `boundary' between these two sets of information, and it +was never actually used by the system. Ed Sznyter's +\Lpack{fixfloats} package not unreasonably used this position to +store the double column information, setting the bit for double +column floats. Then at each point in the output routine at which a +float is committed to a certain region, an additional check must be +made to check that the float is (or is not) double column. If it +spans the wrong number of columns it is deferred rather than being +added. + +Unfortunately the bit `16' is not available in \LaTeXe. It is used +to encode the extra float position possibility `|!|' that was added +in that system. It would be possible to use position `32' and to +move the flags for `table', `figure',\ldots\ up one position, to +start at 64, but this would mean that in principle one less float +type would be supported, and more importantly is likely to break +any other packages that assume anything about the output routine +internals. So here I instead use another mechanism for flagging +double column floats: By default all floats have depth 0pt. +This package arranges that double column ones have depth 1sp. +This information may then be used in the same manner as in +the \Lpack{fixfloats} package, to defer any floats that are not of +the correct column spanning type. + + + +\subsection{Infinite glue found (pr/4023 and pr/2346)} + +The fix for pr/2346 did not work as intended when used in conjunction +with |\enlargethispage| as the latter introduced an infinite negative +glue at the bottom of the page. That in turn make a |\vsplit| +operation to get at the column marks invalid. + +\subsection{Wrong header for twocolumn (pr/2613)} + +\begin{verbatim} +>>Number: 2613 +>>Category: latex +>>Synopsis: wrong headline for twocolumn +>>Arrival-Date: Mon Sep 22 16:41:09 1997 +>>Originator: Daniel Reischert +>>Description: +When setting the document in two columns +the headline shows the top mark of the second column, +but it should show the top mark of the first column. +\end{verbatim} + +Originally fixed in package \Lpack{fix2col} which was merged into +this package. Documentation and code from this package have been +merged into this file. + +\subsubsection{Notes on the Implementation Strategy} + +The standard \LaTeX\ twocolumn system works internally by making +each column a separate `page' that is passed independently to \TeX's +page breaker. (Unlike say the \Lpack{multicol} package, where all +columns are gathered together and then split into columns later, +using |\vsplit|.) This means that the primitive \TeX\ marks that are +normally used for header information, are globally reset after the +first column. By default \LaTeX\ does nothing about this. +A good solution is provided by Piet van Oostrum (building on earlier +work of Joe Pallas) in his \Lpack{fixmarks} package. + +After the first column box has been collected the mark information +for that box is saved, so that any |\firstmark| can be +`artificially' used to set the page-level marks after the second +column has been collected. (The second column |\firstmark| is not +normally required.) Unfortunately \TeX\ does not provide a direct +way of knowing if any marks are in the page, |\firstmark| always has a +value from previous pages, even if there is no mark in this page. +The solution is to make a copy of the box and then |\vsplit| it +so that any marks show up as |\splitfirstmark|. + +The use of |\vsplit| does mean that the output routine will globally +change the value of |\splitfirstmark| and +|\splitbotmark|. The \Lpack{fixmarks} package goes to some trouble +to save and restore these values so that the output routine does +\emph{not} change the values. This part of \Lpack{fixmarks} is not +copied here as it is quite costly (having to be run on every page) and +there is no reason why anyone writing code using |\vsplit| should +allow the output routine to be triggered before the split marks have +been accessed. + + + +\subsection{\texttt{\textbackslash setlength} produces error if + used with registers like \texttt{\textbackslash dimen0} (pr/3066)} + +\begin{verbatim} +>>Number: 3066 +>>Category: latex +>>Synopsis: \setlength{\dimen0}{10pt} +>>Arrival-Date: Tue Jul 6 15:01:06 1999 +>>Originator: Heiko Oberdiek +>>Description: +The current implementation of \setlength causes an error, +because the length specification isn't terminated properly. +More safe: +\def\setlength#1#2{#1=#2\relax} +\end{verbatim} + +\subsection{Fewer fragile commands} + +\begin{verbatim} +>>Number: 3816 +>>Category: latex +>>Synopsis: Argument of \@sect has an extra }. +>>Arrival-Date: Sat Oct 22 23:11:01 +0200 2005 +>>Originator: Susanne Wunsch + +Use of a \raisebox in \section{} produces the error message +mentioned in the subject. + +PR latex/1738 described a similar problem, which has been solved +10 years ago. Protecting the \raisebox with \protect solved my +problem as well, but wouldn't it make sense to have a similar fix +as in the PR? + +It is particularly confusing, that an unprotected \raisebox in a +\section*-environment works fine, while in a \section-environment +produces error. +\end{verbatim} + +While not technically a bug, in this day and age there are few +reasons why commands taking optional arguments should not be robust. + +\subsubsection{Notes on the implementation strategy} + +Rather than changing the kernel macros to be robust, we have decided +to add the macro \DescribeMacro{\MakeRobust}|\MakeRobust| in +\Lpack{fixltx2e} so that users can easily turn fragile macros into +robust ones. A macro |\foo| is made robust by doing the simple +|\MakeRobust{\foo}|. \Lpack{fixltx2e} makes the following kernel +macros robust: |\(|, |\)|, |\[|, |\]|, + |\makebox|, |\savebox|, +|\framebox|, |\parbox|, |\rule| and |\raisebox|. + +\ldots TODO \ldots fleqn vesion of |\[\]| + +\subsection{\texttt{\textbackslash addpenalty} ruins flush-bottom (pr/3073)} + +\begin{verbatim} +>>Number: 3073 +>>Category: latex +>>Synopsis: \addpenalty ruins flush-bottom +>>Arrival-Date: Sat Jul 17 05:11:05 1999 +>>Originator: Donald Arseneau +>>Description: +Just to keep in mind for further development eh? +A page break at an \addpenalty after \vspace does *not* +give a flush-bottom page. (The intent of \addpenalty is +apparently just to preserve the flush bottom by putting +the breakpoint `above' the skip.) +\end{verbatim} + +\subsection{Within counters only reset next level down (pr4393)} + +This is actually implicitly documented behavior in the \LaTeX{} +Manual that states that |\stepcounter| resets all counters marked +``within''. However it means that if, for example, theorems are +numbered within sections and you start a new chapter in a book, the +section counter is reset to zero but the theorem counter is not +until the first section appears. Thus a theorem directly within the +chapter body (without a new section) would show an incremented +number relative to the last theorem of the previous chapter. + + +For this reason we are now resetting all levels of within in one go +even if that means that some of these resets may happen several times +unnecessarily. + + +\subsection{Check the optional arguments of floats} + +By default LaTeX silently ignores unknown letters in the optional +arguments of floats. |\begin{figure}[tB]| the |B| is ignored so it +acts like |\begin{figure}[t]| However |\begin{figure}[B]| does +\emph{not} act like |\begin{figure}[]| as the check for an empty +argument, or unsupplied argument, is earlier. |[]| causes the +default float placement to be used, but |[B]| means that \emph{no} +float area is allowed and so the float will not be placed until the +next |\clearpage| or end of document, no warning is given. + +This package adds a check on each letter, and if it not one of +|!tbhp| then an error is given and the code acts as if |p| had been +used, so that the float may be placed somewhere. + +\subsection{\texttt{\textbackslash DeclareMathSizes} only take pts. + (pr/3693)} + +\begin{verbatim} +>>Number: 3693 +>>Category: latex +>>Synopsis: \DeclareMathSizes only take pts. +>>Arrival-Date: Fri Jun 11 16:21:00 CEST 2004 +>>Originator: Morten Hoegholm + +The last three arguments of \@DeclareMathSizes cannot take a dimension +as argument, making it inconsistent with the rest of the font changing +commands and itself, as the second argument can take a dimension +specification. +\end{verbatim} + +\subsection{No hyphenation in first word after float environment (pr/3498)} + +\begin{verbatim} +>>Number: 3498 +>>Category: latex +>>Synopsis: No hyphenation in first word after float environment +>>Arrival-Date: Thu Jan 30 13:21:00 CET 2003 +>>Originator: Harald Harders + +If a float environment (figure, table) is written within a paragraph, +the first word after the environment is not hyphenated. +\end{verbatim} + +\subsection{\texttt{\textbackslash fnsymbol} should use text symbols + (pr/3400)} + +\begin{verbatim} +>>Number: 3400 +>>Category: latex +>>Synopsis: \fnsymbol should use text symbols if possible +>>Arrival-Date: Fri Jan 04 20:41:00 CET 2002 +>>Originator: Walter Schmidt + +The \fnsymbol command can be used in both text and math +mode. The symbols produced are, however, always taken from +the math fonts. As a result, they may not match the text +fonts, even if the symbols are actually available, for +instance from the TS1 encoding. Since \fnsymbol is +primarily used for footnotes in text, this should be fixed, +IMO. +\end{verbatim} + + + + + +\subsection{\texttt{\textbackslash footnotemark}[x] crashes with fixltx2e.sty + (pr/3752)} + +\begin{verbatim} +>>Number: 3752 +>>Category: tools +>>Synopsis: feature \footnotemark[x] crashes with fixltx2e.sty +>>Arrival-Date: Fri Dec 17 10:11:00 +0100 2004 +>>Originator: Stefan Pofahl + + If I use /fnsymbol together with fixltx2e.sty I can not use + optional parameter [num] + \footnotemark[1] is not showing the mark number 1 but + the mark \value{footnote}. +\end{verbatim} +This bug was related to pr/3400, where |\@fnsymbol| was made robust. + +\subsubsection{Notes on the implementation strategy} + +Pr/3400 made |\@fnsymbol| decide between text-mode and math-mode, +which requires a certain level of robustness somewhere as the +decision between text and math must be made at typesetting time and +not when inside |\protected@edef| or similar commands. One way of +dealing with this is to make sure the value seen by |\@fnsymbol| is +a fully expanded number, which could be handled by code such as +\begin{verbatim} +\def\fnsymbol#1{\expandafter\@fnsymbol + \expandafter{\the\csname c@#1\endcsname}} +\end{verbatim} +This would be a good solution if everybody used the high level +commands only by writing code like |\fnsymbol{footnote}|. Unfortunately +many classes (including the standard classes) and packages use the +internal forms directly as in |\@fnsymbol\c@footnote| so the easy +solution of changing |\fnsymbol| would break code that had worked for +the past 20~years. + +Therefore the implementation here makes |\@fnsymbol| itself a +non-robust command again and instead uses a new robust command +\DescribeMacro{\TextOrMath}|\TextOrMath|, which will take care of +typesetting either the math or the text symbol. In order to do so, +we face an age old problem and unsolvable problem in \TeX: A +reliable test for math mode that doesn't destroy +kerning. Fortunately this problem can be solved when using e\TeX\ so +if you use this as engine for your \LaTeX\ format, as recommended by +the \LaTeX3 Project, you will get a fully functioning |\TextOrMath| +command with no side effects. If you use regular \TeX\ as engine for +your \LaTeX\ format then we have to choose between the lesser of two +evils: 1)~breaking ligatures and preventing kerning or 2)~face the +risk of choosing text-mode at the beginning of an alignment cell, +which was supposed to be math-mode. We have decided upon 1) as is +customary for regular robust commands in \LaTeX. + + + +\end{document} diff --git a/macros/latex-dev/doc/ltnews.pdf b/macros/latex-dev/doc/ltnews.pdf new file mode 100644 index 0000000000..4b8a3bcbed Binary files /dev/null and b/macros/latex-dev/doc/ltnews.pdf differ diff --git a/macros/latex-dev/doc/ltnews.tex b/macros/latex-dev/doc/ltnews.tex new file mode 100644 index 0000000000..d989ff8c42 --- /dev/null +++ b/macros/latex-dev/doc/ltnews.tex @@ -0,0 +1,276 @@ +% \iffalse meta-comment +% +% Copyright 2006, 2009, 2011, 2014 Heiko Oberdiek +% Copyright 2014-2018 The LaTeX3 Project +% +% This file is part of the LaTeX base system. +% ------------------------------------------- +% +% 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 +% 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 file has the LPPL maintenance status "maintained". +% +% 2006/06/02 v1.0: First version. +% 2009/09/25 v1.1: \usepackage disabled. +% 2011/07/01 v1.2: Fixes. +% 2014/02/30 v1.3: +% * Update for LaTeX 2014/05/01. +% * Fix for anchor positions of issue titles. +% 2014/05/15 v1.4: +% * Updates for ltnews21.tex. +% 2014/11/14 v1.4a: +% * LaTeX Project version +% 2015/02/16 v1.4b: +% * Fix TOC issue +% \fi + +\NeedsTeXFormat{LaTeX2e} +\ProvidesFile{ltnews.tex}% + [2015/02/16 v1.4b Master file for ltnews*.tex (LaTeX Project)] +\providecommand*{\lastissue}{30} +\InputIfFileExists{ltnews-lastissue.cfg}{}{} + + +\ifx\pdfoutput\undefined +\let\pdfoutput\outputmode +\protected\def\pdfinfo{\pdfextension info } +\fi + +\RequirePackage{ifpdf} +\ifpdf + % overwrite nasty stuff of ltnews.cfg + % (use of hyperref for this would also support other drivers) + \pdfinfo{% + /Title(LaTeX News)% + /Subject(Issues 1--\lastissue)% + /Author(The LaTeX Project)% + /Creator(LaTeX)% + } + \newtoks\pdfinfo +\else + \AtBeginDocument{% + \hypersetup{% + pdftitle={LaTeX News},% + pdfsubject={Issues 1\textendash\lastissue},% + pdfauthor={The LaTeX Project},% + pdfcreator={LaTeX}% + }% + }% +\fi + +\RequirePackage{lmodern} +\RequirePackage[T1]{fontenc} +\RequirePackage{hologo} +\RequirePackage{graphicx} + + +\documentclass{ltnews} + +\RequirePackage{url,csquotes} + +\expandafter +\DeclareRobustCommand\expandafter*\expandafter\small\expandafter{\small} + +\RequirePackage{hyperref} +\hypersetup{colorlinks} +\RequirePackage{bookmark} + +\makeatletter + +\newcounter{issue} +\renewcommand*{\theissue}{% + \ifnum\value{issue}<10 0\fi + \number\value{issue}% +} + +\newcommand*{\MonthJanuary}{01} +\newcommand*{\MonthFebruary}{02} +\newcommand*{\MonthMarch}{03} +\newcommand*{\MonthApril}{04} +\newcommand*{\MonthMay}{05} +\newcommand*{\MonthJune}{06} +\newcommand*{\MonthJuly}{07} +\newcommand*{\MonthAugust}{08} +\newcommand*{\MonthSeptember}{09} +\newcommand*{\MonthOctober}{10} +\newcommand*{\MonthNovember}{11} +\newcommand*{\MonthDecember}{12} +\newcommand*{\printissue}{% + Issue % + \texorpdfstring{\number\value{issue}}{\theissue}, % + \texorpdfstring{\@month\space\@year}{\@year/\@nameuse{Month\@month}}% +} +\let\l@part\l@section +\let\l@section\l@subsection +\let\l@subsection\l@subsubsection +\let\l@subsubsection\l@paragraph +\let\l@paragraph\l@subparagraph + +\newcommand*{\makefirsttitle}{% + \twocolumn[{% + \parbox[t][4\baselineskip]{\textwidth}{% + \@titlefont\@title, Issues 1--\lastissue + }% + }]% +} + +% table of contents with underlined links +\iffalse % disable if option colorlinks is used +\@ifpackagelater{hyperref}{2006/06/01}{% + \newcommand*{\saved@tableofcontents}{}% + \let\saved@tableofcontents\tableofcontents + \renewcommand*{\tableofcontents}{% + \begingroup + \hypersetup{pdfborderstyle={/S/U/W 1}}% + \saved@tableofcontents + \endgroup + }% +}{} +\fi + +% -- provide command introduced in new release +% so this typesets with an old format +\DeclareTextCommandDefault\textcommabelow[1] + {\hmode@bgroup\ooalign{\null#1\crcr\hidewidth\raise-.31ex + \hbox{\check@mathfonts\fontsize\ssf@size\z@ + \math@fontsfalse\selectfont,}\hidewidth}\egroup} +\DeclareTextCommandDefault\textcommaabove[1]{% + \hmode@bgroup + \ooalign{% + \hidewidth + \raise.7ex\hbox{% + \check@mathfonts\fontsize\ssf@size\z@\math@fontsfalse\selectfont`% + }% + \hidewidth\crcr + \null#1\crcr + }% + \egroup + } + +\makeatother + +\begin{document} + +%%% Title and Table of Contents + +\makefirsttitle +\pdfbookmark[0]{\contentsname}{toc} +\tableofcontents +\clearpage + +%%% Issues + +\begingroup + \makeatletter + \renewcommand*{\usepackage}[2][]{% + \begingroup + \def\x{#1|#2}% + \def\y{T1|fontenc}% + \ifx\x\y + \else + \def\y{|lmodern,url}% + \ifx\x\y + \else + \def\y{|lmodern,url,hologo}% + \ifx\x\y + \else + \def\y{|csquotes}% + \ifx\x\y + \else + \def\y{|graphicx}% + \ifx\x\y + \else + \@latex@error{ltnews.tex: \string\usepackage[#1]{#2} found}\@ehc + \fi + \fi + \fi + \fi + \fi + \endgroup + }% + \renewcommand*{\documentclass}[2][]{% + \setcounter{footnote}{0}% + \gobbleopt + }% + \newcommand*{\gobbleopt}[1][]{}% + \let\org@twocolumn\twocolumn + \renewenvironment{document}{% + \clearpage + \ifnum\@issue=20 % + \addtocontents{toc}{\protect\setcounter{tocdepth}{5}}% + \addtocontents{toc}{% + \protect\makeatletter + }% + \addtocontents{toc}{% + \let\protect\saved@l@paragraph\protect\l@paragraph + }% + \addtocontents{toc}{% + \let\protect\l@paragraph\protect\l@subsection + }% + \fi + \ifnum\@issue=\lastissue\space + \addtocontents{toc}{% + \let\protect\l@paragraph\protect\saved@l@paragraph + }% + \def\toclevel@subsection{1}% + \def\toclevel@subsubsection{2}% + \addtocontents{toc}{\protect\setcounter{tocdepth}{4}}% + \renewcommand*{\tableofcontents}{% + \section*{\contentsname}% + \@starttoc{toc\lastissue}% + }% + \let\saved@addtocontents\addtocontents + \renewcommand*{\addtocontents}[2]{% + \saved@addtocontents{##1}{##2}% + \def\temp@toc{toc}% + \def\temp@param{##1}% + \ifx\temp@toc\temp@param + \saved@addtocontents{toc\lastissue}{##2}% + \fi + }% + \let\l@subsubsection\l@subsection + \let\l@subsection\l@section + \let\l@section\l@part + \let\l@part\@gobbletwo + \fi + \def\twocolumn[{% + \let\twocolumn\org@twocolumn + \org@twocolumn[% + {% because of optional argument of \twocolumn + \pdfbookmark[0]{\printissue}{issue\theissue}% + }% + \begingroup + \let\WriteBookmarks\relax + \@firstofone{% inside opt. arg. of \twocolumn: protect "]" + \renewcommand*{\Hy@writebookmark}[5]{}% + }% + \phantomsection + \addcontentsline{toc}{part}{\printissue}% + \endgroup + }% + }{% + \clearpage + }% + \makeatother + \loop + \ifnum\value{issue}<\lastissue + \stepcounter{issue}% + \input{ltnews\theissue}% + \repeat + \stepcounter{issue}% + \makeatletter + \IfFileExists{ltnews\theissue}{% + \@latex@error{\jobname.tex is out of date,\MessageBreak + there is `ltnews\theissue.tex'% + }\@ehc + }{}% + \makeatother +\endgroup + +\end{document} diff --git a/macros/latex-dev/doc/ltnews01.tex b/macros/latex-dev/doc/ltnews01.tex new file mode 100644 index 0000000000..92090e17d0 --- /dev/null +++ b/macros/latex-dev/doc/ltnews01.tex @@ -0,0 +1,152 @@ +% \iffalse meta-comment +% +% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 +% The LaTeX3 Project and any individual authors listed elsewhere +% in this file. +% +% This file is part of the LaTeX base system. +% ------------------------------------------- +% +% 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 +% 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 file has the LPPL maintenance status "maintained". +% +% The list of all files belonging to the LaTeX base distribution is +% given in the file `manifest.txt'. See also `legal.txt' for additional +% information. +% +% The list of derived (unpacked) files belonging to the distribution +% and covered by LPPL is defined by the unpacking scripts (with +% extension .ins) which are part of the distribution. +% +% \fi +% Filename: ltnews01.tex + +% This is issue 1 of LaTeX News. + +\documentclass +% [type1fonts] + {ltnews} + +\publicationmonth{June} +\publicationyear{1994} +\publicationissue{1} + +\begin{document} + +\maketitle + +\section{Welcome to \LaTeXNews} + +An issue of \emph{\LaTeXNews} will accompany every future release of +\LaTeX. It will tell you about important events, such as major bug +fixes, newly available packages, or any other \LaTeX{} news. + +\section{\LaTeXe---the new \LaTeX{} release} + +The most important news is the release of \LaTeXe, the new version of +the \LaTeX{} software. This version has better support for fonts, +graphics and colour, and will be actively maintained by the \LaTeX3 +project team. Upgrades will be issued every six months, in June and +December. + +\section{Why a new \LaTeX?} + +Over the years many extensions have been developed for \LaTeX. This +is, of course, a sure sign of its continuing popularity but it has had +one unfortunate result: incompatible \LaTeX{} formats came into use at +different sites. Thus, to process documents from various places, a +site maintainer was forced to keep \LaTeX{} (with and without \NFSS), +\SLiTeX, \AmSLaTeX, and so on. In addition, when looking at a source +file it was not always clear for which format the document was written. + +To put an end to this unsatisfactory +situation a new release of \LaTeX{} was produced. +It brings all such extensions back under a single format and thus +prevents the proliferation of mutually incompatible dialects of +\LaTeX~2.09. The new release was available for several months as a +test version, and the final release of 1~June officially +replaces the old version. + +\section{Processing documents with \LaTeXe} + +Documents written for \LaTeX~2.09 will +still be read by \LaTeXe. Any such document is run in +\emph{\LaTeX~2.09 compatibility mode}. + +Unfortunately, compatibility mode comes with a price: it can run +up to 50\% slower than \LaTeX~2.09 did. If you want to run your document +in the faster \emph{native mode}, you should try replacing the line: +\begin{verbatim} + \documentstyle[<options>,<packages>]{<class>} +\end{verbatim} +with: +\begin{verbatim} + \documentclass[<options>]{<class>} + \usepackage{latexsym,<packages>} +\end{verbatim} +Unfortunately, this will not always work, because some \LaTeX~2.09 +packages will only work in \LaTeXe{} compatibility mode. You should find +out if there is a \LaTeXe{} version of the package available. + +\LaTeXe{} native mode also gives access to the new features of \LaTeXe, +described in \emph{\LaTeXe{} for authors}. + +\section{New packages} + +\LaTeXe{} has much better support for graphics, colour, fonts, and +multi-lingual typesetting. The following software should be available +from the distributor who brought you \LaTeXe: + +\begin{citations} +\item[babel] for typesetting in many languages. +\item[color] for colour support. +\item[graphics] for including images. +\item[mfnfss] for using bitmap fonts. +\item[psnfss] for using Type~1 fonts. +\item[tools] other packages by the \LaTeX3 team. +\end{citations} +The packages come with full documentation, and are also described in +\emph{\LaTeX: A Document Processing System} or +\emph{The \LaTeX{} Companion}. + +\section{Further information} + +More information about \LaTeXe{} is to be found in: + +\begin{citations} +\item[\LaTeX: A Document Preparation System] + Leslie Lamport, \AW, 2nd ed, 1994. +\item[The \LaTeX{} Companion] + Goossens, Mittelbach and Samarin, \AW, 1994. +\end{citations} +The \LaTeX{} distribution comes with documentation on the new features of +\LaTeX: + +\begin{citations} +\item[\LaTeXe{} for authors] + describes the new features of \LaTeX{} documents, + in the file \verb|usrguide.tex|. +\item[\LaTeXe{} for class and package writers] + describes the new features of \LaTeX{} classes and packages, + in the file \verb|clsguide.tex|. +\item[\LaTeXe{} font selection] + describes the new features of \LaTeX{} fonts for + class and package writers, + in the file \verb|fntguide.tex|. +\end{citations} +For more information on \TeX{} and \LaTeX, get in touch with your local +\TeX{} Users Group, or the international \TeX{} Users Group, +P.~O.~Box~869, Santa~Barbara, CA~93102-0869, USA, Fax:~+1~805~963~8358, +EMail:~tug@tug.org. + +\end{document} + + + diff --git a/macros/latex-dev/doc/ltnews02.tex b/macros/latex-dev/doc/ltnews02.tex new file mode 100644 index 0000000000..d46cb1b52f --- /dev/null +++ b/macros/latex-dev/doc/ltnews02.tex @@ -0,0 +1,154 @@ +% \iffalse meta-comment +% +% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 +% The LaTeX3 Project and any individual authors listed elsewhere +% in this file. +% +% This file is part of the LaTeX base system. +% ------------------------------------------- +% +% 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 +% 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 file has the LPPL maintenance status "maintained". +% +% The list of all files belonging to the LaTeX base distribution is +% given in the file `manifest.txt'. See also `legal.txt' for additional +% information. +% +% The list of derived (unpacked) files belonging to the distribution +% and covered by LPPL is defined by the unpacking scripts (with +% extension .ins) which are part of the distribution. +% +% \fi +% Filename: ltnews02.tex + +% This is issue 2 of LaTeX News. + +\documentclass +% [lw35fonts] + {ltnews} + +\publicationmonth{December} +\publicationyear{1994} +\publicationissue{2} + +\begin{document} + +\maketitle + +\section{Welcome to \LaTeXNews~2} + +An issue of \emph{\LaTeXNews} will accompany every future release of +\LaTeX. It will tell you about important events, such as major bug +fixes, newly available packages, or any other \LaTeX{} news. + +\section{December 1994 release of \LaTeX} + +December 1994 sees the second release of \LaTeXe. We are on schedule +to deliver a release of \LaTeX{} every six months, in December and +June. + +This release has seen quite a lot of activity, which is not too +surprising as it's only been a year since the first test release of +\LaTeXe. We don't expect so much activity in the next six months. + +Many of the changes are minor improvements and bug-fixes---see +\emph{\LaTeXe{} for authors} (\verb|usrguide.tex|), \emph{\LaTeXe{} +font selection} (\verb|fntguide.tex|) and our change log +(\verb|changes.txt|) for more details. + +However, there are two important new packages available for \LaTeX: +\texttt{inputenc} and AMS-\LaTeX. + +\section{Accented input} + +One of the problems with writing non-English documents in \LaTeX{} is +the accent commands. Reading documents containing text like +\verb|na\"\i ve| is frustrating, especially if your keyboard allows +you to type \texttt{na\"\i ve}. + +In the past, \LaTeX{} has not supported input containing accented +characters such as \texttt{\"\i}, because Windows, Macintosh and Unix +all have different ways of dealing with accented input, called +\emph{input encodings}. + +However, the \verb|inputenc| package allows you to specify which input +encoding your document is written with, for example to use the ISO +Latin-1 encoding, you type: +\begin{verbatim} + \usepackage[latin1]{inputenc} +\end{verbatim} +At the moment, \verb|inputenc| supports the \verb|ascii| and +\verb|latin1| input encodings, but more will be added with future +releases. + +The \verb|inputenc| package is +currently a test release. The user interface for the full release will +be upwardly compatible with the test version. + +\section{AMS-\LaTeX{}} + + AMS-\LaTeX{} is a set of miscellaneous extensions for \LaTeX{} + distributed by the American Mathematical Society. They provide superior + information structure and superior printed output for mathematical + documents. + + There are far too many features of AMS-\LaTeX{} to list here. + AMS-\LaTeX{} is described in the accompanying documentation, + and in \emph{The \LaTeX{} Companion}. + + Version 1.2beta of AMS-\LaTeX{} was released for testing by intrepid + users in October 1994. The full release of AMS-\LaTeX{}~1.2 is expected + in early January 1995. + + It will be divided into two bundles: + \begin{itemize} + + \item the \verb|amsfonts| packages, which give access to + hundreds of new mathematical symbols, and new math fonts + such as blackboard bold and fraktur. + + \item the \verb|amsmath| packages, which provide finer control over + mathematical typesetting, such as multi-line subscripts, + enhanced theorem and proof environments, + and improved displayed equations, + + \end{itemize} + For compatibility with older documents, an \verb|amstex| package will be + provided. + +\section{\LaTeX{} on the internet} + +\LaTeX{} has its own home page on the World Wide Web, with the URL: +\begin{verbatim} + http://www.tex.ac.uk/CTAN/latex/ +\end{verbatim} +This page describes \LaTeX{} and the \LaTeX3 project, and contains +pointers to other \LaTeX{} resources, such as the user guides, the +\TeX{} Frequently Asked Questions, and the \LaTeX{} bugs database. + +The electronic home of anything \TeX-related is the Comprehensive +\TeX{} Archive Network (CTAN). This is a network of cooperating ftp +sites, with over a gigabyte of \TeX{} material: +\begin{verbatim} + ftp://ftp.tex.ac.uk/tex-archive/ + ftp://ftp.shsu.edu/tex-archive/ + ftp://ftp.dante.de/tex-archive/ +\end{verbatim} +For more information, see the \LaTeX{} home page. + +\section{Further information} + +For more information on \TeX{} and \LaTeX, get in touch with your local +\TeX{} Users Group, or the international \TeX{} Users Group, +P.~O.~Box~869, Santa~Barbara, CA~93102-0869, USA, Fax:~+1~805~963~8358, +EMail:~tug@tug.org. + + +\end{document} diff --git a/macros/latex-dev/doc/ltnews03.tex b/macros/latex-dev/doc/ltnews03.tex new file mode 100644 index 0000000000..d7c8ff0b20 --- /dev/null +++ b/macros/latex-dev/doc/ltnews03.tex @@ -0,0 +1,145 @@ +% \iffalse meta-comment +% +% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 +% The LaTeX3 Project and any individual authors listed elsewhere +% in this file. +% +% This file is part of the LaTeX base system. +% ------------------------------------------- +% +% 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 +% 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 file has the LPPL maintenance status "maintained". +% +% The list of all files belonging to the LaTeX base distribution is +% given in the file `manifest.txt'. See also `legal.txt' for additional +% information. +% +% The list of derived (unpacked) files belonging to the distribution +% and covered by LPPL is defined by the unpacking scripts (with +% extension .ins) which are part of the distribution. +% +% \fi +% Filename: ltnews03.tex + +% This is issue 3 of LaTeX News. + +\documentclass +% [lw35fonts] + {ltnews} + +\publicationmonth{June} +\publicationyear{1995} +\publicationissue{3} + +\begin{document} + +\maketitle + +\section{Welcome to \LaTeXNews~3} + +An issue of \emph{\LaTeXNews} will accompany every future release of +\LaTeX. It will tell you about important events, such as major bug +fixes, newly available packages, or any other \LaTeX{} news. + +\section{June 1995 release of \LaTeX} + +June 1995 sees the third release of \LaTeXe. We are on schedule +to deliver a release of \LaTeX{} every six months, in December and +June. + +In the last \emph{\LaTeXNews}, we said ``we don't expect so much +activity in the next six months,'' which has turned out not to be +true! + +\section{Additional input encodings} + +In the last release of \LaTeX{} we distributed a test version of the +\texttt{inputenc} package which allows the use of input characters +other than just a--z and A--Z. The package has proved to be robust, +so we are now distributing an expanded version. +The new release comes with a number of input encodings: + +\begin{itemize} +\item \texttt{ascii} the standard encoding, +\item \texttt{latin1} the ISO Western European alphabet, +\item \texttt{latin2} the ISO Eastern European alphabet, +\item \texttt{cp437} the IBM codepage 437, +\item \texttt{cp850} the IBM codepage 850, and +\item \texttt{applemac} the Apple Macintosh encoding. +\end{itemize} +These can be used by specifying an option to the \texttt{inputenc} +package, for example: +\begin{verbatim} + \usepackage[latin1]{inputenc} +\end{verbatim} +The new input encodings are currently being tested, but we don't +expect any major changes. + +\section{\LaTeX\ getting smaller} + +In the past releases of \LaTeXe, the amount of memory \LaTeX{} +requires has increased, but we are pleased to say that this trend has +been reversed. We hope that future releases of \LaTeX{} will continue +to get smaller. + +For example, on this document, the December 1994 release used 52,622 +words of memory, and the June 1995 release uses 51,216 words of +memory, which is a 2.7\% reduction. + +We are currently experimenting with other ways of reducing the size of +\LaTeX. For example, we are experimenting with an option to remove +the \texttt{picture} and \texttt{tabbing} environments from the +\LaTeX{} kernel, and to load them from a file the first time they are +used. This should help \LaTeX{} to run on machines with limited +memory. See \texttt{autoload.txt} for details. + +\section{Distribution and modification} + +One topic of discussion that has kept us busy is the distribution and +modification conditions of \LaTeX. We are committed to keeping +\LaTeX{} as free reliable software, and ensuring that (as far as +possible) \LaTeX{} documents will produce the same results on all +systems. + +The modification conditions are currently under discussion, and we +would like to hear from anyone interested. Please read +\texttt{modguide.tex} for more information. + +\section{AMS-\LaTeX\ full release} + +The AMS-\LaTeX\ packages were still in beta test in the December 1994 +release of \LaTeX, and the full release came out in January 1995. + +AMS-\LaTeX\ is described in the \emph{User's Guide} +(\texttt{amsldoc.tex}) and in \emph{The \LaTeX{} Companion}. + +\section{PostScript fonts} + +There is a new test release of the PSNFSS packages for accessing +PostScript fonts in \LaTeXe. This includes an update to all of the +fonts, to remove many of the underfull and overfull \verb|\hbox| +warnings, and improve the setting of non-English languages. + +The new release of \LaTeX{} removes all of the `hidden' uses of +Computer Modern mathematics. For example, the footnote markers used +to use math mode, so always used Computer Modern digits rather than +ones from the current text font. This has now been fixed. + +\section{Further information} + +For more information on \TeX{} and \LaTeX, get in touch with your local +\TeX{} Users Group, or the international \TeX{} Users Group, +P.~O.~Box~869, Santa~Barbara, CA~93102-0869, USA, Fax:~+1~805~963~8358, +EMail:~tug@tug.org. + +The \LaTeX{} home page is \verb|http://www.tex.ac.uk/ctan/latex/| +and contains links to other WWW resources for \LaTeX. + +\end{document} diff --git a/macros/latex-dev/doc/ltnews04.tex b/macros/latex-dev/doc/ltnews04.tex new file mode 100644 index 0000000000..15e9599952 --- /dev/null +++ b/macros/latex-dev/doc/ltnews04.tex @@ -0,0 +1,143 @@ +% \iffalse meta-comment +% +% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 +% The LaTeX3 Project and any individual authors listed elsewhere +% in this file. +% +% This file is part of the LaTeX base system. +% ------------------------------------------- +% +% 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 +% 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 file has the LPPL maintenance status "maintained". +% +% The list of all files belonging to the LaTeX base distribution is +% given in the file `manifest.txt'. See also `legal.txt' for additional +% information. +% +% The list of derived (unpacked) files belonging to the distribution +% and covered by LPPL is defined by the unpacking scripts (with +% extension .ins) which are part of the distribution. +% +% \fi +% Filename: ltnews04.tex + +% This is issue 4 of LaTeX News. + +\documentclass +% [lw35fonts] + {ltnews} + + +\publicationmonth{December} +\publicationyear{1995} +\publicationissue{4} + +\begin{document} + +\maketitle + +\section{Welcome to \LaTeXNews~4} + +An issue of \emph{\LaTeXNews} will accompany every future release of +\LaTeX. It will tell you about important events, such as major bug +fixes, newly available packages, or any other \LaTeX{} news. +This issue accompanies the fourth release of \LaTeXe. + + +\section{\LaTeX\ getting smaller} + +The last release in June started a trend of \LaTeX\ becoming +smaller, we are pleased to announce that this has continued with this +release. In particular the experimental `autoload' version described in +\texttt{autoload.txt} is much smaller as more parts of \LaTeX\ are +autoloaded. + +\section{New `concurrent' docstrip} + +The time taken to `unpack' this release from the documented sources +should be much reduced (roughly half the time, depending on +installation conditions). This is due to an improved version of the +docstrip program that has been contributed by Marcin Woli\'nski. +This can write up to 16 files at once. The +previous version could only write one file at a time which meant that +it was very slow when producing many small files from the same source +file as the source needed to be re-read for each file written. + +\section{New T1 encoded fonts} + +This year J\"org Knappen has completed a new release of the `Cork' +(T1) encoded Computer Modern fonts: the dc fonts release 1.2. + +This release of the dc fonts fixes many bugs (including the missing +\verb|?`| (?`) and \verb|!`| (!`) ligatures) and improves the fonts in +many other ways. It is strongly recommended that you upgrade as soon as +possible if currently you are using the old dc fonts, release 1.1 or +earlier. The new fonts are available from the CTAN archives, in +\texttt{tex-archive/fonts/dc}. + +The names of the font files are \emph{different}. This does not affect +\LaTeX\ documents but \emph{does} affect the installation procedure as +it assumes that you have the \emph{new} fonts, and will write suitable +`fd' files for those fonts. If you have not yet upgraded your dc fonts +then, after unpacking the distribution, you \emph{must} +\verb|latex olddc.ins| to produce `fd' files for the old dc fonts. +This must be done \emph{before} the format is made. Running the test +document at \texttt{ltxcheck.tex} the end of the installation will +inform you if the wrong set of `fd' files has been installed. + +Note that this change does not affect the standard `OT1' Computer +Modern fonts that \LaTeX\ uses by default. + +\section{More robust commands} + +The commands \verb|\cite| and \verb|\sqrt| are now robust. + +Although most commands with optional arguments are fragile, as +documented, such commands defined using the second optional argument +of \verb|\newcommand| and its derivatives are now \emph{robust}. + +\section{New Interface to building `extension' classes} + +The mechanism provided by \verb|\DeclareOption|, \verb|\ProcessOptions| +and \verb|\LoadClass| has proved to be a powerful and expressive means +of defining one class in terms of another `base' class. However there +have been some requests to simplify the declaration of the common case +where you want the `base' class to be called with \emph{all} the +options that were specified to the extension class. This is now +provided by the new command \verb|\LoadClassWithOptions|. A similar +command \verb|\RequirePackageWithOptions| is provided for package use. +More details of this feature are provided in \texttt{clsguide.tex} and +\texttt{ltclass.dtx}. + +\section{More Input Encodings} + +The experimental \texttt{inputenc} package allows a more natural style +of input of accented and other characters. + +Three new input encodings are now supported. +\begin{itemize} +\item \texttt{ansinew} the Windows ansi encoding, + as used in Microsoft Windows 3.x. +\item \texttt{cp437de} a variant of \texttt{cp437}, which uses \ss\ + rather than $\beta$ in the appropriate slot. +\item \texttt{next} the encoding used on Next computers. +\end{itemize} + +\section{Further information} + +For more information on \TeX{} and \LaTeX, get in touch with your local +\TeX{} Users Group, or the international \TeX{} Users Group, +1850 Union Street, \#1637, San Francisco, CA~94123, USA, +Fax:~+1~415~982~8559, +EMail:~tug@tug.org. +The \LaTeX{} home page is \verb|http://www.tex.ac.uk/ctan/latex/| +and contains links to other WWW resources for \LaTeX. + +\end{document} diff --git a/macros/latex-dev/doc/ltnews05.tex b/macros/latex-dev/doc/ltnews05.tex new file mode 100644 index 0000000000..9416f0e4ed --- /dev/null +++ b/macros/latex-dev/doc/ltnews05.tex @@ -0,0 +1,158 @@ +% \iffalse meta-comment +% +% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 +% The LaTeX3 Project and any individual authors listed elsewhere +% in this file. +% +% This file is part of the LaTeX base system. +% ------------------------------------------- +% +% 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 +% 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 file has the LPPL maintenance status "maintained". +% +% The list of all files belonging to the LaTeX base distribution is +% given in the file `manifest.txt'. See also `legal.txt' for additional +% information. +% +% The list of derived (unpacked) files belonging to the distribution +% and covered by LPPL is defined by the unpacking scripts (with +% extension .ins) which are part of the distribution. +% +% \fi +% Filename: ltnews05.tex + +% This is issue 5 of LaTeX News. + +\documentclass +% [lw35fonts] + {ltnews} + +% \usepackage[T1]{fontenc} + +\publicationmonth{June} +\publicationyear{1996} +\publicationissue{5} + +\begin{document} + +\maketitle + +\section{Welcome to \LaTeXNews~5} +This issue of \emph{\LaTeXNews} accompanies the fifth release of the +new standard \LaTeX{}, \LaTeXe. + +\section{Extra possibilities for section headings} +Most \LaTeX\ sectioning commands are defined using +\verb|\@startsection|. +For example, the \textsf{article} class defines: +\begin{small} +\begin{verbatim} +\newcommand\section{\@startsection + {section}{1}{0pt}{-3.5ex plus-1ex minus-.2ex}% + {2.3ex plus.2ex}{\normalfont\Large\bfseries}} +\end{verbatim} +\end{small} +The last argument specifies the style in which the section heading is +to be typeset. + +The new feature added at this release is that at the \emph{end} of +this argument you may specify a command that \emph{takes an argument}. +This command will be applied to the section number and heading. +For example, one could use the \verb|\MakeUppercase| command to +produce uppercase headings. A package or class file could contain: +\begin{small} +\begin{verbatim} +\renewcommand\section{\@startsection + {section}{1}{0pt}{-3.5ex plus-1ex minus-.2ex}% + {2.3ex plus.2ex}{\normalfont\Large\MakeUppercase}} +\end{verbatim} +\end{small} +to produce section headings using uppercase medium weight text, rather +than the bold text used by \textsf{article}. Note that, like the font +choice, the uppercasing applies only to the actual heading (including +any automatically generated section number), not to the text as it may +appear in the running head or table of contents. + +\section{The `openany' option in the `book' class} +The \textsf{openany} option allows chapter and similar openings to +occur on left hand pages. Previously this option only affected +\verb|\chapter| and \verb|\backmatter|. It now also affects +\verb|\part|, \verb|\frontmatter| and \verb|\mainmatter|. + +\section{More font (output) encodings} +The font encoding name \texttt{T3} has been allocated to the encoding +used in the new 256-character \textsc{IPA} fonts (for the phonetic +alphabet) produced by Rei Fukui. His package, \textsf{tipa}, +gives access to these fonts and should soon be available. (The +encoding named \texttt{OT3} is the 128-character encoding used in the +\textsc{IPA} fonts produced by Washington State University.) + + + +\section{More input encodings supported} +The \textsf{inputenc} package now supports the IBM codepage~852 used +in Eastern Europe, with the option~\texttt{[cp852]} contributed by +Petr~Sojka. + +Also, the \textsf{inputenc} package now activates most `control codes' +with \textsc{ascii} values below 32. +Currently none of the encodings in the standard distribution makes use +of these positions. + +\section{Fixes and improvements} +The \LaTeX\ kernel has only had minor changes, apart from +\verb|\@startsection| mentioned above. +However, some small fixes have been incorporated removing the +following problems: + +\begin{itemize} +\item + In tabular and array, previous versions of \LaTeX\ `lost' the + inter-column space from an `\texttt{l}'-column, when that column + was completely empty. + +\item + Previously, the use of the \verb|\nofiles| command could change + the \emph{vertical spacing} in a document.\\ A side effect of fixing + this is that when \verb|\nofiles| is used, \verb|\label| puts a + blank line in the log file. + +\item + \LaTeX~often loads fonts `on demand'. Previously, this could + happen inside the argument of an accent command and this would + cause the accent to appear in the wrong place. + +\end{itemize} + +\section{Changes to the `tools' packages} + +\begin{itemize} +\item + The \textsf{longtable} package now uses a modified algorithm, + contributed by David Kastrup, to align the `chunks' of a table. + It is now unnecessary to edit the document to add + \verb|\setlongtables| before the final run of \LaTeX. + In certain cases of overlapping \verb|\multicolumn| entries, the new + algorithm will produce better column widths than the old (at the + price of extra passes through \LaTeX). + +\item + The \textsf{dcolumn} package now has the extra possibility of + specifying the number of digits both \emph{before} and after the + `decimal point'. This makes it easy to centre the column of numbers + under a wide heading. +\end{itemize} + +\section{New copy of the \LaTeX\ bug database} +\verb|http://www.tex.ac.uk/ctan/latex/bugs.html| will soon have links +to a copy of the searchable \LaTeX\ bugs database at Mainz (Germany) +as well as the original copy at Sussex (England). + +\end{document} diff --git a/macros/latex-dev/doc/ltnews06.tex b/macros/latex-dev/doc/ltnews06.tex new file mode 100644 index 0000000000..b5c7a28a24 --- /dev/null +++ b/macros/latex-dev/doc/ltnews06.tex @@ -0,0 +1,149 @@ +% \iffalse meta-comment +% +% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 +% The LaTeX3 Project and any individual authors listed elsewhere +% in this file. +% +% This file is part of the LaTeX base system. +% ------------------------------------------- +% +% 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 +% 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 file has the LPPL maintenance status "maintained". +% +% The list of all files belonging to the LaTeX base distribution is +% given in the file `manifest.txt'. See also `legal.txt' for additional +% information. +% +% The list of derived (unpacked) files belonging to the distribution +% and covered by LPPL is defined by the unpacking scripts (with +% extension .ins) which are part of the distribution. +% +% \fi +% Filename: ltnews06.tex + +% This is issue 6 of LaTeX News. + +\documentclass +% [lw35fonts] + {ltnews} + +% \usepackage[T1]{fontenc} + +\publicationmonth{December} +\publicationyear{1996} +\publicationissue{6} + +\begin{document} + +\maketitle + +\section{Welcome to \LaTeXNews~6} +This issue of \emph{\LaTeXNews} accompanies the sixth release of the +new standard \LaTeX{}, \LaTeXe. + +\section{Mono-case file names} +Previously \LaTeX\ has used some files with `mixed-case' file names +such as \texttt{T1cmr.fd} and \texttt{T1enc.def}. + +These file names cause problems on some systems (in particular they +are illegal on the ISO 9660 CDROM format) and so in this release +all file names have been made lowercase (for example +\texttt{t1cmr.fd} and \texttt{t1enc.def}). + +This change should \emph{not} affect any document. Within \LaTeX, +encodings still have the usual uppercase names in uses such as +\verb|\usepackage[T1]{fontenc}| and \verb|\fontencoding{T1}|. +\LaTeX\ will automatically convert to the lowercase form while +constructing the file name. +\LaTeX\ will input the `fd' file under the old name if it fails to +find the file with the new name, so existing collections of fd files +should still work with this new release. + +The change \emph{does} affect the configuration files that may be used +to make the \LaTeX\ format with initex. For example, the file +\texttt{fonttext.ltx} previously specified \verb|\input{T1cmr.fd}|. +It now has \verb|\input{t1cmr.fd}|. +If you use a local file \texttt{fonttext.cfg} +you will need to make similar changes, as \verb|\input{T1cmr.fd}| +will not work as \texttt{T1cmr.fd} is no longer in the distribution. + +The files affected by this change all have names of the form +\verb|*.fd| or \verb|*enc.def|. + +\section{Another input encoding} +Thanks to work by S\o ren Sandmann, the \textsf{inputenc} package now +supports the IBM codepage~865 used in Scandinavia. + +\section{Better user-defined math display environments} +Suppose that you want to define an environment for displaying text +that is numbered as an equation. A straightforward way to do this is +as follows: +\begin{verbatim} + \newenvironment{texteqn} + {\begin{equation} + \begin{minipage}{0.9\linewidth}} + {\end{minipage} + \end{equation}} +\end{verbatim} +However, if you have tried this then you will probably have noticed +that it does not work perfectly when used in the middle of a paragraph +because an inter-word space appears at the beginning of the first +line after the environment. + +There is now an extra command (with a very long name) available that +you can use to avoid this problem; it should be inserted as shown here: +\begin{verbatim} + \newenvironment{texteqn} + {\begin{equation} + \begin{minipage}{0.9\linewidth}} + {\end{minipage} + \end{equation} + \ignorespacesafterend} +\end{verbatim} + +\section{Docstrip improvements} +The \textsf{docstrip} program that is used to unpack the \LaTeX\ +sources has undergone further development. The new version should be +able to process all old `batchfiles' but it allows a simpler syntax in +new `batchfiles' (no need to define \verb|\def\batchfile{|\ldots). + +It also allows `target' directories to be specified when writing +files. This directory support is disabled by default unless activated +in a local \texttt{docstrip.cfg} configuration file. +See \texttt{docstrip.dtx} for details. + +\section{AMS \LaTeX\ update} +Since the last \LaTeX\ release in June, the American Mathematical +Society have re-issued the `AMS\LaTeX' classes and packages, fixing +several reported problems. + +\section{Graphics package update} +The \LaTeX\ color and graphics packages have been updated slightly, +principally to support more dvi drivers, see the readme file in the +\textsf{graphics} distribution. + +\section{EC Fonts released} +The first release of the Extended Computer Modern fonts has just been +made. (In January 1997.) + +This release of \LaTeX\ does \emph{not} default to these `ec' fonts +as its T1 encoded fonts. By default it will +use the `dc' fonts if the T1 encoding is requested. + +As noted in \texttt{install.txt} you may run \TeX\ on the install file +\texttt{ec.ins} \emph{after} unpacking the base distribution but +\emph{before} making the \LaTeX\ format. This will produce +suitable `fd' files making \LaTeX\ (including, for the first time, the +\textsf{slides} class) use the `ec' fonts as the default T1 encoded +font set. + + +\end{document} + diff --git a/macros/latex-dev/doc/ltnews07.tex b/macros/latex-dev/doc/ltnews07.tex new file mode 100644 index 0000000000..81d0ed3143 --- /dev/null +++ b/macros/latex-dev/doc/ltnews07.tex @@ -0,0 +1,146 @@ +% \iffalse meta-comment +% +% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 +% The LaTeX3 Project and any individual authors listed elsewhere +% in this file. +% +% This file is part of the LaTeX base system. +% ------------------------------------------- +% +% 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 +% 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 file has the LPPL maintenance status "maintained". +% +% The list of all files belonging to the LaTeX base distribution is +% given in the file `manifest.txt'. See also `legal.txt' for additional +% information. +% +% The list of derived (unpacked) files belonging to the distribution +% and covered by LPPL is defined by the unpacking scripts (with +% extension .ins) which are part of the distribution. +% +% \fi +% Filename: ltnews07.tex + +% This is issue 7 of LaTeX News. + +\documentclass +% [lw35fonts] + {ltnews} + +% \usepackage[T1]{fontenc} + +\publicationmonth{June} +\publicationyear{1997} +\publicationissue{7} + +\begin{document} + +\maketitle + +\section{T1 encoded Computer Modern fonts} +As in the last release the base \LaTeX\ distribution contains +three different sets of `fd' files for T1 encoded fonts. + +In this release the default installation uses \texttt{ec.ins} +and so installs files suitable for the current `EC fonts' +distribution. If you have still not updated to the EC fonts and +are using the earlier test versions, known as DC then you should +unpack \texttt{newdc.ins} (for DC release 1.2 or later) or +\texttt{olddc.ins} (for the original releases of the DC fonts). +This should be done after unpacking \texttt{unpack.ins} but +before making the format by running ini\TeX{} on \texttt{latex.ltx}. +There are further details in \texttt{install.txt}. + + +\section{T1 encoded Concrete fonts} +The Metafont sources for T1 encoded `Concrete' fonts have been +removed from the \textsf{mfnss} distribution as they were based +on the now obsolete DC fonts release 1.1. Similarly the +\textsf{cmextra.ins} install file in the \textsf{base} distribution no +longer generates fd files for the `Concrete' fonts. +To use these fonts in either T1 or OT1 encoding it is +recommended that you obtain Walter Schmidt's \textsf{ccfonts} package +and fonts from CTAN \texttt{macros/latex/contrib/supported/ccfonts}. + + +\section{Further input encodings} +Two more \textsf{inputenc} packages have been added: for latin5, +thanks to H. Turgut Uyar; and for latin3, thanks to J\"org Knappen. + + +\section{Normalising spacing after punctuation} +The command \verb|\normalsfcodes| was introduced at the last patch +release. This is normally given the correct definition automatically +and so need not be explicitly set. It is used to correct a problem, +reported by Donald Arseneau, that punctuation in page headers has +always (in all known \TeX\ formats) been potentially incorrect if the +page break happens while a local setting of the space codes (for +instance by the command \verb|\frenchspacing|) is in effect. A common +example of this happening in \LaTeX\ is in the \textsf{verbatim} +environment. + + +\section{Accessing Bold Math Symbols} +The \textsf{tools} distribution contains a new package, \textsf{bm}, +which defines a command \verb|\bm| that allows individual bold symbols +to be accessed within a math expression (in contrast to +\verb|\boldmath| which makes whole math expressions default to bold +fonts). It is more general than the existing \textsf{amsbsy} package; +however, to ease the translation of documents between these two +packages, \textsf{bm} makes \verb|\boldsymbol| an alias for +\verb|\bm|. + +This package was previously made available from the `contrib' area of +the CTAN archives, and as part of Y\&Y's \LaTeX\ support for the +MathTime fonts. + + +\section{Policy on standard classes} + +Many of the problem reports we receive concerning the standard classes +are not concerned with bugs but are suggesting, more or less politely, +that the design decisions embodied in them are `not optimal' and +asking us to modify them. + +There are several reasons why we have decided not to make such changes +to these files. +\begin{itemize} +\item + However misguided, the current behaviour is clearly what was + intended when these classes were designed. +\item + It is not good practice to change such aspects of `standard classes' + because many people will be relying on them. +\end{itemize} + +We have therefore decided not to even consider making such +modifications, nor to spend time justifying that decision. This does +not mean that we do not agree that there are many deficiencies in the +design of these classes, but we have many tasks with higher priority +than continually explaining why the standard classes for \LaTeX{} +cannot be changed. + +We would, of course, welcome the production of better classes, or of +packages that can be used to enhance these classes. + + +\section{New addresses for TUG} +For information about joining the \TeX{} Users Group, and about lots +of other \LaTeX-related matters, please contact +them at their new address: +\begin{quote}\small + \TeX{} Users Group, P.O. Box 1239,\\ + Three Rivers, CA~93271-1239, USA\\ + Fax:~+1~209~561~4584\\ + E-mail: \texttt{tug@mail.tug.org}\\ + URL: \texttt{http://www.tug.org/} +\end{quote} + +\end{document} diff --git a/macros/latex-dev/doc/ltnews08.tex b/macros/latex-dev/doc/ltnews08.tex new file mode 100644 index 0000000000..b43c4f53f9 --- /dev/null +++ b/macros/latex-dev/doc/ltnews08.tex @@ -0,0 +1,154 @@ +% \iffalse meta-comment +% +% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 +% The LaTeX3 Project and any individual authors listed elsewhere +% in this file. +% +% This file is part of the LaTeX base system. +% ------------------------------------------- +% +% 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 +% 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 file has the LPPL maintenance status "maintained". +% +% The list of all files belonging to the LaTeX base distribution is +% given in the file `manifest.txt'. See also `legal.txt' for additional +% information. +% +% The list of derived (unpacked) files belonging to the distribution +% and covered by LPPL is defined by the unpacking scripts (with +% extension .ins) which are part of the distribution. +% +% \fi +% Filename: ltnews08.tex + +% This is issue 8 of LaTeX News. + +\documentclass +% [lw35fonts] + {ltnews} + +% \usepackage[T1]{fontenc} + +\publicationmonth{December} +\publicationyear{1997} +\publicationissue{8} + +\begin{document} + +\maketitle + +\section{New supported font encodings} + +Two new font encodings are supported as options to the \textsf{fontenc} +package: +\begin{description} +\item [OT4] +This is a seven-bit encoding designed for Polish. The \LaTeX\ support +was developed by Mariusz Olko. +\item [TS1] This is the `Text Companion Encoding'; it contains symbols +designed to be used in text, as opposed to mathematical formulas, and +some accents designed for uppercase letters. It is currently +supported by the `tc' fonts, which match the T1 encoded `ec' text +fonts. A subset of the glyphs in this encoding is supported by +virtual fonts distributed with the PostScript font metrics on the +\textsc{ctan} archives. (This is the `8c' encoding in Karl Berry's +fontname scheme.) The \textsf{textcomp} package provides access to +this encoding but here is a warning to current users of that package: +some of the internal names for the characters have changed. +\end{description} + + +\section{New input encodings} + +These additions to the \textsf{inputenc} package are +\texttt{decmulti} (the DEC Multinational +Character Set, contributed by M.~Y.~Chartoire) +and \texttt{cp1250} (an MS-Windows encoding for Central and Eastern +Europe, contributed by Marcin Woli\'nski). There is also a +\texttt{cp1252} encoding that is identical to \texttt{ansinew}. + + +\section{Tools} + +The \textsf{calc} package (used in many examples in \emph{The \LaTeX\ +Companion}) has been contributed to this distribution by Kresten Krab +Thorup and Frank Jensen. This is essentially the same as the version +that has been available from the \textsc{ctan} archives for some time, +with one minor change: to use \LaTeX-style error messages. It enables +the use of arithmetic expressions within arguments to standard +\LaTeX{} commands where a length or a counter value is required. For +example: +\begin{verbatim} + \setcounter {page} { \value{page} * 2 + 1 } + \parbox { 3in - ( 2mm + \textwidth / 9 ) } +\end{verbatim} + +There have also been some improvements to several other packages in +this collection. In particular, \textsf{bm} now works correctly with +constructions such as \verb|\bm{f'}| involving \texttt{'} or other +characters which use \TeX's special ``\verb|\mathcode"8000|'' +feature. Also, \textsf{multicol} sets the length \verb|\columnwidth| +to an appropriate value; this enables it to work with classes that +support two-column setting, e.g.,~the AMS classes. + + +\section{Graphics} + +The special \verb|oztex.def| driver file has been removed, and Oz\TeX\ +support has been merged with dvips, following advice from +Andrew Trevorrow about Oz\TeX~3.x. + +The \textsf{keyval} package has had some internal improvements: to +use \LaTeX\ format error messages; and to avoid `\verb|#| doubling'. +This latter change means that the \verb|command| key for the +\textsf{graphicx} version of \verb|\includegraphics| should now be used +with one \verb|#| rather than two. For example, \verb|command = `gunzip #1|. +Fortunately this key is almost never used in practice, so few if any +documents should be affected by this change. + + +\section{\LaTeX3 experimental programming conventions} + +As announced at the \TeX\ Users Group meeting (Summer 1997), a group of +highly experimental packages will soon be released to allow experienced\\ +\TeX\ programmers to experiment with, and comment on, a proposed set +of syntax conventions and basic data-types that might form +the basis for programming large scale projects in \TeX. +They will be located in\\ +this CTAN directory: +\begin{verbatim} + CTAN:macros/latex/packages/expl3 +\end{verbatim} +The documentation of this material is as follows: individual package +files provide outline, draft documentation; there is an article that +gives an overview of the syntax and related concepts; there is a +\texttt{readme.txt} file containing a brief description of the +collection. + +All aspects of these packages are liable, indeed likely, to change. +They should not be used at this stage for anything +that requires a stable system. However, we do encourage people to +experiment with these packages, and to send comments on them to the +\texttt{LaTeX-L} mailing list. +To subscribe to this list, mail to: +\begin{verbatim} + listserv@urz.uni-heidelberg.de +\end{verbatim} +the following one line message: +\begin{verbatim} + subscribe LATEX-L <<first-name>> <<second-name>> +\end{verbatim} + +% Revert to this if gets too full. +% See \texttt{modguide.tex} for +% information on how to subscribe to \texttt{LaTeX-L}. + +\end{document} + diff --git a/macros/latex-dev/doc/ltnews09.tex b/macros/latex-dev/doc/ltnews09.tex new file mode 100644 index 0000000000..c4f8b43ec8 --- /dev/null +++ b/macros/latex-dev/doc/ltnews09.tex @@ -0,0 +1,142 @@ +% \iffalse meta-comment +% +% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 +% The LaTeX3 Project and any individual authors listed elsewhere +% in this file. +% +% This file is part of the LaTeX base system. +% ------------------------------------------- +% +% 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 +% 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 file has the LPPL maintenance status "maintained". +% +% The list of all files belonging to the LaTeX base distribution is +% given in the file `manifest.txt'. See also `legal.txt' for additional +% information. +% +% The list of derived (unpacked) files belonging to the distribution +% and covered by LPPL is defined by the unpacking scripts (with +% extension .ins) which are part of the distribution. +% +% \fi +% Filename: ltnews09.tex + +% This is issue 9 of LaTeX News. + +\documentclass +% [lw35fonts] + {ltnews}[1999/02/23] + +%\usepackage[T1]{fontenc} + +\publicationmonth{June} +\publicationyear{1998} +\publicationissue{9} + +\begin{document} + +\maketitle + + +\section{New math font encodings} + +A joint working group of the \TeX{} Users Group and the \LaTeX3 +Project is developing a new 8-bit math font encoding for \TeX{}. +It is designed to overcome several limitations and implementation +problems of the old math font encodings and to simplify switching +between different sets of math fonts, much as the \LaTeX{} font +selection interface has simplified switching between text fonts. + +Since the work on this project relies entirely on volunteer work, we +cannot give a specific release date yet. However, a prototype +implementation already exists. This contains several sets of virtual +fonts, some \LaTeX{} packages and a kernel module; we hope to +integrate it into the main \LaTeX{} distribution for the next +release. + +Documents using only standard \LaTeX{} commands for math symbols +should not be affected by switching to the new math font encodings +However, documents, classes or packages making specific assumptions +about the encoding of math symbol fonts are likely to break. + +Further information about the Math Font Group may be found on +the World Wide Web at \texttt{http://www.tug.org/twg/mfg/}. + + +\section{A new math accent} + +A new math accent, \verb|\mathring|, has been added. This is a math mode +version of the ring accent (\r{}) which is available in text +mode with the command \verb|\r|. + +\section{Extended \cs{DeclareMathDelimiter}} + +The command \verb|\DeclareMathDelimiter| has been extended. +Normally this command takes six arguments. Previously, when being used +to declare a character (such as \texttt{[}) as a delimiter, a variant +form was used with only five arguments. The argument specifying the +default `math class' was omitted. Now the full six-argument form may be +used in this case. The extra information is used to implicitly declare +the character via \verb|\DeclareMathSymbol| for use when the symbol is +not used with \verb|\left| or \verb|\right|. + +The old five-argument form is detected and will work as before. + +\newpage + +\section{Tools distribution} + +The \texttt{multicol} package now supports the production of multiple +columns without balancing the last page. To get this effect use the +\texttt{multicols*} environment. + +The \texttt{layout} package was partly recoded by Hideo Umeki to +display page layout effects in a better way. + +As suggested by Donald Arseneau, the \texttt{calc} package was extended +to support the new commands \verb|\widthof{<text>}|, +\verb|\heightof{<text>}|, and \verb|\depthof{<text>}| within a +\texttt{calc}-expression. At the same time we modified a few kernel +commands so that \texttt{calc}-expressions can now be used in various +useful places such as the dimension arguments to the \texttt{tabular} +environment and the \verb|\rule| command. For many other standard +\LaTeX{} commands this was already possible. + + +\section{Support for Cyrillic encodings} + +We are very pleased that, after a lengthy period of development, a set +of fonts, encodings and support files for using \LaTeX\ with Cyrillic +characters will soon be available. + +Test versions of the `LH' fonts for these Cyrillic encodings, based on +the Computer Modern design, are available from CTAN archives in the +directory \texttt{fonts/cyrillic/lh-test}. The \LaTeX\ support files +(by Werner Lemberg and Vladimir Volovich) are also available from CTAN +archives in\\ + \texttt{macros/latex/contrib/supported/t2} + + +\section{Default docstrip header} + +Many \LaTeX\ users now distribute packages in documented source form +using the \textsf{docstrip} system. Docstrip allows a header to be +placed on generated package files, suitable for giving copyright +information, or distribution conditions. + +We have changed the default version of this header so that it allows +stripped files to be distributed in ready-to-run installations such as +the \TeX{}Live CD\@. If you use the default header for distributing +your files you should check that the new copyright text is acceptable +to you. The file \texttt{docstrip.dtx} explains how to produce your own +header if you wish to do so. + + +\end{document} diff --git a/macros/latex-dev/doc/ltnews10.tex b/macros/latex-dev/doc/ltnews10.tex new file mode 100644 index 0000000000..d9e0d4de53 --- /dev/null +++ b/macros/latex-dev/doc/ltnews10.tex @@ -0,0 +1,153 @@ +% \iffalse meta-comment +% +% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 +% The LaTeX3 Project and any individual authors listed elsewhere +% in this file. +% +% This file is part of the LaTeX base system. +% ------------------------------------------- +% +% 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 +% 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 file has the LPPL maintenance status "maintained". +% +% The list of all files belonging to the LaTeX base distribution is +% given in the file `manifest.txt'. See also `legal.txt' for additional +% information. +% +% The list of derived (unpacked) files belonging to the distribution +% and covered by LPPL is defined by the unpacking scripts (with +% extension .ins) which are part of the distribution. +% +% \fi +% Filename: ltnews10.tex 12/01/1998 + +% This is issue 10 of LaTeX News. + +\documentclass +% [lw35fonts] + {ltnews}[1999/02/23] + +% \usepackage[T1]{fontenc} + +\publicationmonth{December} +\publicationyear{1998} +\publicationissue{10} + +\begin{document} + +\maketitle + + +\section{Five years of \LaTeXe} + +Since this is the 10th edition of \LaTeX{} News, the (no longer) New +Standard \LaTeX{} must have hit the streets almost this long ago. In +fact it was only the beta-version that some people got just in time for +Christmas~1993, and since then there has been a lot of tidying-up and +smoothing of rough edges (not to mention a few bug fixes!). + +Maybe it is time for something more radically different to emerge and +be hungrily adopted by the world; but don't panic, we shall be +maintaining what you have now for a long time yet. Amongst the more +polite things that have been written about our efforts, we found that this +quote (somewhat censored to protect the guilty) well reflects some of +our feelings about working on \LaTeX{} over the years: \textit{the mere +existence of \LaTeXe{} is a great miracle}. + + + \section{Restructuring the \LaTeX{} distribution} + + Since the (once) `new' standard \LaTeX{} has reached such a venerable + age, we are reviewing the way in which the system is presented to the + world. + + An early intention is to define, given the wide variety of good + packages now available, what now constitutes a useful installation of + \LaTeX{}. We also hope that such a definition will help document + portability if it leads to a future in which a \LaTeX{} class + designer can reasonably assume that a known list of + facilities will be there for all users (so that each class + need not supply them). + + As a first small step towards this definition, we shall replace the + \texttt{latex/packages} subdirectory on \ctan{}. + This directory was a curious mixture of the important, such as the + \LaTeX{} \texttt{tools}, that any self-respecting \LaTeX{} + installation ought to have, and the esoteric or experimental. + + The esoterica from \texttt{packages} will be moved to + new locations, as follows: + \begin{quote} + \texttt{expl3} to \texttt{latex/exptl/project}\\ + \texttt{mfnfss} to \texttt{latex/contrib/supported/mfnfss} + \end{quote} + + The subdirectory that replaces \texttt{packages} will be called + \texttt{latex/required}; all the other sub-directories of + \texttt{packages} will be moved there. + +\vspace{17pt} +\pagebreak + + \section{\LaTeX\ Project on the Internet} +A new \texttt{latex-project.org} domain has been registered. +The web site is not yet fully functional but the old \LaTeX\ pages from +\ctan\ are available at \texttt{http://www.latex-project.org/} and the +\LaTeX\ bug reporting address has been changed to +\texttt{latex-bugs@latex-project.org}. + + \section{Restructuring the \LaTeX{} package licenses} + +Several people have requested an easy mechanism for the distribution +of \LaTeX\ packages and other software ``under the same conditions as +\LaTeX''. The old \texttt{legal.txt} file was unsuitable as a general +licence as it referred to specific \LaTeX\ authors, and to specific +files. + +Therefore, in this release \texttt{legal.txt} contains just the +copyright notice and a reference to the new \emph{\LaTeX\ Project +Public License} (LPPL) for the distribution and modification +conditions. The \texttt{tools}, \texttt{graphics}, and \texttt{mfnfss} +packages also now refer to this license in their distribution notices. + + \section{Support for Cyrillic encodings} + +Basic Cyrillic support, as announced in \LaTeX{} News~9, is now +finally an official part of \LaTeX{}. It includes support for the +following standard Cyrillic font encodings (this list may +grow):~\mbox{\texttt{T2A T2B T2C X2}}. + +It also includes various Cyrillic input encodings (20~in total, +including commonly used variants and Mongolian Cyrillic +encodings). This provides platform independent and +sophisticated basic support for high-quality typesetting in various +Cyrillic-based languages. + +For further information see the file \texttt{cyrguide.tex}. + +\section{Tools distribution} + +The \texttt{varioref} package has been extended to support textual +page references to a range of objects: e.g.,~if \texttt{eq-first} +and \texttt{eq-last} are the label names for the first and last +equation in a sequence, then you can now write +\begin{verbatim} + see~\vrefrange{eq-first}{eq-last} +\end{verbatim} +This results in different text depending on whether both +labels fall on the same page. + +Some additional user commands, as well as building-blocks for writing +private extensions, are described in the accompanying documentation. + + + +\end{document} + diff --git a/macros/latex-dev/doc/ltnews11.tex b/macros/latex-dev/doc/ltnews11.tex new file mode 100644 index 0000000000..6587a691af --- /dev/null +++ b/macros/latex-dev/doc/ltnews11.tex @@ -0,0 +1,141 @@ +% \iffalse meta-comment +% +% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 +% The LaTeX3 Project and any individual authors listed elsewhere +% in this file. +% +% This file is part of the LaTeX base system. +% ------------------------------------------- +% +% 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 +% 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 file has the LPPL maintenance status "maintained". +% +% The list of all files belonging to the LaTeX base distribution is +% given in the file `manifest.txt'. See also `legal.txt' for additional +% information. +% +% The list of derived (unpacked) files belonging to the distribution +% and covered by LPPL is defined by the unpacking scripts (with +% extension .ins) which are part of the distribution. +% +% \fi +% Filename: ltnews11.tex 01/06/1999 +% This is issue 11 of LaTeX News. + +\documentclass +% [lw35fonts] % uncomment this line to get Times + {ltnews} + +% \usepackage[T1]{fontenc} + +\publicationmonth{June} +\publicationyear{1999} +\publicationissue{11} + +\begin{document} + +\maketitle + +\section{Back in sync} + +The last release of \LaTeX{} was delayed even longer than you have +come to expect. We hope that it proved worth waiting for. It +required a major integration of the code from several people and, +independently, the introduction of the LPPL (see \LaTeX{} News~10) plus +several related changes to our internal systems. It therefore seemed +sensible to wait until everything was complete rather than do things +in too much hurry. + +This seem to have been a successful strategy as +the recent patch release was related to an isolated change that was +done many months previously. If this release does not appear a lot +closer to its nominal date then \ldots~well, you will not be reading +this sentence! + +\section{Yearly release cycles} + +With the year 2000 rapidly approaching, we intend to switch to a +release frequency of just one per year (with patches if necessary) for +the core of \LaTeXe{}. These days the system is sufficiently stable +that the original update policy is costing everybody more time than is +now warranted. + +\section{LPPL update} + +Thanks to extensive and valuable input from Matt Swift +(\email{swift@alum.mit.edu}) we now have a clearer and more detailed +form of the \LaTeX{} Project Public Licence. This release contains +both the original version (in \file{lppl-1-0.txt}) and the updated +version, LPPL~1.1. + +\section{The future of Sli\TeX{}} + +We still get a very small trickle of reports about this part of the +system (if you are no longer able to recall \LaTeX~2.09 then you will +know it as the \class{slides} class). We have not classified them (in +our minds at least) as bugs since we have always known that there are +many problems with this class. It is clear to us that the only +sensible action would be to redesign the system completely; in +particular, to remove much of its complexity whose purpose is to +support 10-year-old overlay technology. However, this would take a +lot too much time and would be completely out of proportion to its +current usage. + +We are therefore planning to make the \class{slides} class +unsupported in the sense that any problem related to the use of +invisible fonts is considered to be a feature (The \LaTeXe{} manual by +Leslie Lamport doesn't even describe this part of the class any more). +Of course, if it still has its enthusiasts then we are happy to cede +it to their loving care (somewhat like a preserved steam locomotive, +in some parts of the world). + +\section{Fontenc package peculiarities} + +The \verb=\usepackage= interface normally ensures that a package is +loaded only once. The \pkg{fontenc} package has become an +exception to this rule: it can be loaded several times using different +options, e.g., allowing the user to add a font encoding in the +preamble. This comes at a price for package writers: the low-level +commands (see \file{ltclass.dtx}) used to check if a package was +loaded, and with which options, do not work for the \pkg{fontenc} +package. + +\section{New math font encodings} + +As we announced in \LaTeX{} News~9, a joint working group of the +\TeX{} Users Group and the \LaTeX3 Project has developed a new +\mbox{8-bit} math font encoding for \TeX{}. +The reason why this work is not yet released is because of other +exciting developments in the world of math fonts and math characters. +It is obviously wise to ensure that the encoding work is fully +integrated with the available fonts. + +Those interested are reminded that further information about the Math +Font Group may be found on the World Wide Web at:\\ +\url{http://www.tug.org/twg/mfg/}. + +\section{Tools distribution} + +The \pkg{multicol} package has now got a small but useful extension +which allows you to force a column break where this is really +necessary. This is done with the command \verb=\columnbreak=, which +can be used like \verb=\pagebreak= (e.g.,~within paragraphs) except +that it cannot have an optional argument and thus it always forces a +new column. + +\section{Coming soon} + +Major work on a new class file structure to support flexible +designs is well under way; some of this work will be presented at the +TUG'99 conference in Vancouver, Canada. With a bit of luck much of +this work could be ready for integration into the next release---so +watch this space! + +\end{document} diff --git a/macros/latex-dev/doc/ltnews12.tex b/macros/latex-dev/doc/ltnews12.tex new file mode 100644 index 0000000000..47609689ce --- /dev/null +++ b/macros/latex-dev/doc/ltnews12.tex @@ -0,0 +1,154 @@ +% \iffalse meta-comment +% +% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 +% The LaTeX3 Project and any individual authors listed elsewhere +% in this file. +% +% This file is part of the LaTeX base system. +% ------------------------------------------- +% +% 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 +% 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 file has the LPPL maintenance status "maintained". +% +% The list of all files belonging to the LaTeX base distribution is +% given in the file `manifest.txt'. See also `legal.txt' for additional +% information. +% +% The list of derived (unpacked) files belonging to the distribution +% and covered by LPPL is defined by the unpacking scripts (with +% extension .ins) which are part of the distribution. +% +% \fi +% Filename: ltnews12.tex +% +% This is issue 12 of LaTeX News. + +\documentclass +% [lw35fonts] % uncomment this line to get Times + {ltnews}[1999/12/01] + +% \usepackage[T1]{fontenc} + +\publicationmonth{December} +\publicationyear{1999} +\publicationissue{12} + +% Should go to .cls: +\newcommand{\acro}[1]{\textsc{\MakeLowercase{#1}}} + +\begin{document} + +\maketitle + +\section{LPPL update} + +Since the release of the \LaTeX{} Project Public Licence version~1.1, +we have received a small number of queries which resulted in some +minor changes to improve the wording or explain the intentions better. +As a consequence this release now contains LPPL~1.2 in the file +\file{lppl.txt} and the previous versions as \file{lppl-1-0.txt} and +\file{lppl-1-1.txt}. + +\section{fixltx2e package} + + This package provides fixes to \LaTeXe{} which are desirable but + cannot be integrated into the \LaTeXe{} kernel directly as they + would produce a version incompatible to earlier releases (either + in formatting or functionality). + + By having these fixes in the form of a package, users can benefit + from them without the danger that their documents will fail, or + produce unexpected results, at other sites; this works because a + document will contain a clear indication (the \verb=\usepackage= + line, preferably with a required date) that at least some of these + fixes are required to format it. + +\section{Outcome of TUG '99 (Vancouver)} + +The slides from the \acro{TUG}'99 presentation we gave on \emph{a +new interface for \LaTeX\ class designers} are available from the +\LaTeX\ Project website; look for the file \verb|tug99.pdf| at: +\begin{quote} + \url{http://www.latex-project.org/talks/} +\end{quote} + +Please note that this document was intended only to be informal +``speaker's notes'' for our own use. We decided to make them available (the +speaker's notes as well as the slides that were presented) because several +people requested copies after the talk. However, they are \emph{not} in +a polished copy-edited form and are not intended for publication. + +Prototype implementations of parts of this interface are now available from: +\begin{quote} + \url{http://www.latex-project.org/code/experimental/} +\end{quote} + +We are continuing to add new material at this location so as to +stimulate further discussion of the underlying concepts. As of +December 1, 1999 +the following parts can be downloaded. +\begin{description} + + \item[xparse] Prototype implementation of the interface for declaring + document command syntax. See the \texttt{.dtx} files for + documentation. + + \item[template] Prototype implementation of the template interface + (needs parts of \texttt{xparse}). + + The file \texttt{template.dtx} in that directory has a large section + of documentation at the front describing the commands in the + interface and giving a `worked example' building up some templates + for caption formatting. + + \item[xcontents] Interface description for table of contents data (no + code yet). Coding examples have been thoroughly discussed on the + \texttt{latex-l} list. + + \item[xfootnote] Working examples for generating footnotes, + etc. Needs \texttt{xparse} and \texttt{template}. + + \end{description} +All examples are organised in subdirectories and additionally + available as \texttt{gzip} \texttt{tar} files. + + Please remember +that this material is intended only for experimentation and comments; +thus any aspect of it, e.g., the user interface or the functionality, +may change and, in fact, is very likely to change. +For this reason it is explicitly forbidden to place this material on +\acro{CD-ROM} distributions or public servers. + +These concepts, as well as their implementation, are under discussion +on the list \texttt{LATEX-L}. You can join this list, which is +intended solely for discussing ideas and concepts for future versions +of \LaTeX, by sending mail to +%\begin{quote} + \email{listserv@URZ.UNI-HEIDELBERG.DE} +%\end{quote} +containing the line + \begin{quote} + \texttt{SUBSCRIBE LATEX-L} \textit{Your Name} + \end{quote} + +This list is archived and, after subscription, you can retrieve older +posts to it by sending mail to the above address, containing a command +such as: +\begin{quote} +\texttt{GET LATEX-L LOGyymm} +\end{quote} +where \texttt{yy}=Year and \texttt{mm}=Month, e.g. +\begin{quote} +\texttt{GET LATEX-L LOG9910} +\end{quote} +for all messages sent in October 1999. + + +\end{document} diff --git a/macros/latex-dev/doc/ltnews13.tex b/macros/latex-dev/doc/ltnews13.tex new file mode 100644 index 0000000000..ae08f3d90d --- /dev/null +++ b/macros/latex-dev/doc/ltnews13.tex @@ -0,0 +1,201 @@ +% \iffalse meta-comment +% +% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 +% The LaTeX3 Project and any individual authors listed elsewhere +% in this file. +% +% This file is part of the LaTeX base system. +% ------------------------------------------- +% +% 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 +% 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 file has the LPPL maintenance status "maintained". +% +% The list of all files belonging to the LaTeX base distribution is +% given in the file `manifest.txt'. See also `legal.txt' for additional +% information. +% +% The list of derived (unpacked) files belonging to the distribution +% and covered by LPPL is defined by the unpacking scripts (with +% extension .ins) which are part of the distribution. +% +% \fi +% Filename: ltnews13.tex +% +% This is issue 13 of LaTeX News. + +\documentclass +% [lw35fonts] % uncomment this line to get Palatino + {ltnews}[2000/07/21] + +% \usepackage[T1]{fontenc} + +\publicationmonth{June} +\publicationyear{2000} +\publicationissue{13} + + +\begin{document} + +\maketitle + +\raisefirstsection +\section{Yearly release cycle} + +We announced in \textit{\LaTeX{} News~11} that we intended to switch +to a 12-monthly release schedule. With the present (June~2000) +release, this switch is being made: thus the next release of \LaTeX{} +will be dated June~2001. We shall of course continue, as in the past, +to release patches as needed to fix significant bugs. + + +\section{PSNFSS: \small Quote of the Month} + +\begin{quote} + You should say in the \LaTeX{} News that Walter Schmidt has taken over + \PSNFSS{} from me. It gives me a certain pleasure to be able to draw a + line under that part of my life\ldots + + \begin{latexonly} + \vspace{-\baselineskip} + \end{latexonly} + + \begin{flushright} + Sebastian Rahtz + \end{flushright} +\end{quote} + +\begin{latexonly} + \vspace{-\baselineskip} +\end{latexonly} + +\noindent +The \PSNFSS{} material, which supports the use\latex{\\} +of common PostScript fonts with \LaTeX{}, has been thoroughly updated. +Most noticeably, the \package{mathpple} package, which used to be +distributed separately, is now part of the basic \PSNFSS{} bundle; +this package provides mathematical typesetting with the Palatino +typeface family. In addition, numerous bugs and flaws have been fixed +and the distribution has been `cleaned up'. The file +\file{changes.txt} contains a detailed list of these changes. +\latex{\looseness=-1} %%!!!!! It worked! + +The documentation (in \file{psnfss2e.pdf}) has been completely +rewritten to provide a comprehensive introduction to the use +of PostScript fonts. + +Notice that the new \PSNFSS{} needs updated files for font metrics, +virtual fonts and font definitions. If you received the new +version~(8.1) as part of a complete \TeX{} system then these new font +files should also have been installed. However, if you intend to +install or update \PSNFSS{} yourself, please read the instructions in +the file \file{00readme.txt} of the new \PSNFSS{} distribution. + +Support for commercial PostScript fonts, such as +Lucida~Bright, has been removed from the basic distribution; +it is now available from \ctan{}: +\begin{latexonly} + \file{\ctanhttp macros/latex/\\ + contrib/supported/psnfssx}. +\end{latexonly} +\begin{htmlonly} + \url{http://www.tex.ac.uk/tex-archive/macros/latex/contrib/supported/psnfssx}. +\end{htmlonly} + +\section{New AMS-\LaTeX{}} + +Version 2.0 of AMS-\LaTeX{} was released on December 1, 1999. It can +be obtained via \url{ftp://ftp.ams.org/pub/tex/} or +\url{http://www.ams.org/tex/amslatex.html}, as well from \ctan{}: +\begin{latexonly} + \file{\ctanhttp macros/latex/\\ + required/amslatex}. +\end{latexonly} +\begin{htmlonly} + \url{http://www.tex.ac.uk/tex-archive/macros/latex/required/amslatex}. +\end{htmlonly} + +This release consists chiefly of bug fixes and consolidation of the +existing features. The division of AMS-\LaTeX{} into two main parts +(the math packages;\latex{\\} +the AMS document classes) has been made more pronounced. +The files \file{diffs-m.txt}, \file{diffs-c.txt}, +\file{amsmath.faq}, and \file{amsclass.faq} describe the\latex{\\} +changes and address some common questions. + +The primary documentation files remain \file{amsldoc.tex}, for the +\package{amsmath} package, and \file{instr-l.tex}, for the AMS +document classes.\latex{\\} +The documentation for the \package{amsthm} package,\latex{\\} +however, has been moved from \file{amsldoc.tex}\latex{\\} +to a separate document \file{amsthdoc.tex}. + +\begin{latexonly} + \vfill +\end{latexonly} + +\section{New input encoding \package{latin4}} + +The package \package{inputenc} has, thanks to Hana Skoumalov\'a, +been extended to cover the \package{latin4} input encoding; this +covers Baltic and Scandinavian languages as well as Greenland +Inuit and Lappish. + +\begin{latexonly} + \vfill +\end{latexonly} + +\section{New experimental code} + +In \textit{\LaTeX{} News~12} we announced some ongoing work towards a +`Designer Interface for \LaTeX' and we presented some early results +thereof. Since then, at Gutenberg\,2000 in Toulouse and TUG\,2000 in +Oxford, we described a new output routine and an improved method of +handling vertical mode material between paragraphs. In combination +these support higher quality \emph{automated}\footnote + {The stress here is on automated!} +page-breaking and page make-up\latex{\\} +for complex pages---the best yet achieved with \TeX{}! + +A paper describing the new output routine is +\begin{latexonly} + at\\ + \file{http://www.latex-project.org/papers/xo-pfloat.pdf% + \hspace*{-16pt}}\\ +\end{latexonly} +\begin{htmlonly} + at \url{http://www.latex-project.org/papers/xo-pfloat.pdf}. +\end{htmlonly} +All code examples and documentation are available +\begin{latexonly} + at\\ + \file{http://www.latex-project.org/code/experimental/% + \latex{\hspace*{-5pt}}}.\\[3pt] +\end{latexonly} +\begin{htmlonly} + at \url{http://www.latex-project.org/code/experimental/}. + +\end{htmlonly} +This directory has been extended to contain +\begin{description} + \item[galley] Prototype implementation of the interface\latex{\\} + for manipulating vertical material in galleys. + \item[xinitials] Prototype implementation of the interface\latex{\\} + for paragraph initials (needs the \texttt{galley} package. + \item[xtheorem] Contributed example using the \texttt{template} + package to provide a designer interface for theorem environments. + \item[xoutput] A prototype implementation of the new output routine + as described in the \texttt{xo-pfloat.pdf} paper. Expected + availability: at or shortly after\latex{\\} + the TUG\,2000 conference. +\end{description} + +\end{document} + + diff --git a/macros/latex-dev/doc/ltnews14.tex b/macros/latex-dev/doc/ltnews14.tex new file mode 100644 index 0000000000..1e5c8d72c8 --- /dev/null +++ b/macros/latex-dev/doc/ltnews14.tex @@ -0,0 +1,169 @@ +% \iffalse meta-comment +% +% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 +% The LaTeX3 Project and any individual authors listed elsewhere +% in this file. +% +% This file is part of the LaTeX base system. +% ------------------------------------------- +% +% 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 +% 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 file has the LPPL maintenance status "maintained". +% +% The list of all files belonging to the LaTeX base distribution is +% given in the file `manifest.txt'. See also `legal.txt' for additional +% information. +% +% The list of derived (unpacked) files belonging to the distribution +% and covered by LPPL is defined by the unpacking scripts (with +% extension .ins) which are part of the distribution. +% +% \fi +% Filename: ltnews14.tex +% +% This is issue 14 of LaTeX News. + +\documentclass +% [lw35fonts] % uncomment this line to get Palatino + {ltnews}[2001/07/12] + +% \usepackage[T1]{fontenc} + +\publicationmonth{June} +\publicationyear{2001} +\publicationissue{14} + + +\begin{document} + +\maketitle + +\raisefirstsection +\section{Future releases} + +We are currently exploring how to best support the very large +community of individuals, organisations and enterprises that depend on +the robustness and availability of the current standard \LaTeX{} +distribution. The results of this may lead to some changes in the +regular release schedule and the handling of bug reports during the +next year. + +\section{New release of \textsf{Babel} (required)} + +Earlier this year a new release of \textsf{Babel} (3.7) became +available. You can read about its new features in +\begin{latexonly} + \file{http://www.ctan.org/tex-archive/macros/}\\ + \hspace*{4em}\file{latex/required/babel/announce.txt} +\end{latexonly} +\begin{htmlonly} + \url{http://www.ctan.org/tex-archive/macros/latex/required/babel/announce.txt} +\end{htmlonly} + +One of the bugs that got fixed in this release deals with how labels +are handled by \LaTeX{}. Because this part of the kernel is modified +by \textsf{babel}, the relevant changes need to be coordinated. +Therefore to use \textsf{Babel} with this release of \LaTeX{} you will +need to update your version of \textsf{babel} to at least 3.7. + +\section{New input encoding \package{latin9}} + +The package \package{inputenc} has, thanks to Karsten Tinnefeld, been +extended to cover the \package{latin9} input encoding. The +ISO-Latin~9 encoding is a useful modern replacement for ISO-Latin~1 +that contains a few characters needed for French and Finnish. Of wider +interest, it also contains the euro currency sign; this could be the +killer argument for many 8-bit texts to use Latin-9 in the future. + +According to a Linux manpage, ISO~Latin-9 supports Albanian, Basque, +Breton, Catalan, Danish, Dutch, English, Estonian, Faroese, Finnish, +French, Frisian, Galician, German, Greenlandic, Icelandic, Irish +Gaelic, Italian, Latin, Luxembourgish, Norwegian, Portuguese, +Rhaeto-Romanic, Scottish Gaelic, Spanish and Swedish.\\ +The characters added in \package{latin9} are (in \LaTeX{} notation):\\ +\begin{small} +\verb| \texteuro \v S \v s \v Z \v z \OE \oe \" Y | +\end{small}\\ +They displace the following characters from \package{latin1}:\\ +\begin{small} +\verb| \textcurrency \textbrokenbar \"{} \'{} \c{} |\\ +\verb| \textonequarter \textonehalf \textthreequarters | +\end{small} + + +\section{New tools} + +The new package \package{trace} provides many commands to control +\LaTeX{}'s tracing and debugging output, including the excellent new +information available with \eTeX{} such as the extremely useful +tracing of local assignments. You will find it in the tools +distribution. + +It offers the command \verb|\traceon|, which is similar to +\verb|\tracingall| but suppresses uninteresting stuff such as font +loading by NFSS (which can go on for pages if you are unlucky). It +also offers \verb|\traceoff| to \ldots\ guess what! Full details are +in the documented source file, \file{trace.dtx}. + +In the base \package{ifthen} package we have added +the uppercase synonyms \verb|\NOT| \verb|\AND| and \verb|\OR|. + +\section{New experimental code} + +In \textit{\LaTeX{} News~12} we announced some ongoing work towards a +`Designer Interface for \LaTeX' and we presented some early results +thereof. Since then, at Gutenberg\,2000 in Toulouse and TUG\,2000 in +Oxford, we described a new output routine and an improved method of +handling vertical mode material between paragraphs. In combination +these support higher quality \emph{automated}\footnote + {The stress here is on automated!} +page-breaking and page make-up\latex{\\} +for complex pages---the best yet achieved with \TeX{}! + +More recently we have added material to handle the complex front +matter requirements of journal articles; this was presented at +Gutenberg\,2001 in Metz. + +A paper describing the new output routine is +\begin{latexonly} + at\\ +\begin{small} + \file{http://www.latex-project.org/papers/xo-pfloat.pdf}\\ +\end{small} +\end{latexonly} +\begin{htmlonly} + at \url{http://www.latex-project.org/papers/xo-pfloat.pdf}. +\end{htmlonly} +All code examples and documentation are available +\begin{latexonly} + at\\ +\begin{small} + \file{http://www.latex-project.org/code/experimental} +\end{small} +\end{latexonly} +\begin{htmlonly} + at \url{http://www.latex-project.org/code/experimental/}. +\end{htmlonly} + +This directory has been extended to contain the following. +\begin{description} + \item[galley] Prototype implementation of the interface\latex{\\} + for manipulating vertical material in galleys. + \item[xinitials] Prototype implementation of the interface\latex{\\} + for paragraph initials (needs the \texttt{galley} package). + \item[xtheorem] Contributed example using the \texttt{template} + package to provide a designer interface for theorem environments. + \item[xor] A prototype implementation of the new output routine + as described in the \texttt{xo-pfloat.pdf} paper. + \item[xfrontm] A prototype version of + the new font matter interface. +\end{description} + +\end{document} diff --git a/macros/latex-dev/doc/ltnews15.tex b/macros/latex-dev/doc/ltnews15.tex new file mode 100644 index 0000000000..389ed6334d --- /dev/null +++ b/macros/latex-dev/doc/ltnews15.tex @@ -0,0 +1,169 @@ +% \iffalse meta-comment +% +% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 +% The LaTeX3 Project and any individual authors listed elsewhere +% in this file. +% +% This file is part of the LaTeX base system. +% ------------------------------------------- +% +% 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 +% 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 file has the LPPL maintenance status "maintained". +% +% The list of all files belonging to the LaTeX base distribution is +% given in the file `manifest.txt'. See also `legal.txt' for additional +% information. +% +% The list of derived (unpacked) files belonging to the distribution +% and covered by LPPL is defined by the unpacking scripts (with +% extension .ins) which are part of the distribution. +% +% \fi +% Filename: ltnews15.tex +% +% This is issue 15 of LaTeX News. + +\documentclass +% [lw35fonts] % uncomment this line to get Palatino + {ltnews}[2004/02/28] + +% \usepackage[T1]{fontenc} + +\publicationmonth{December} +\publicationyear{2003} +\publicationissue{15} + +\begin{document} + +\maketitle + +%\raisefirstsection + +\section{Anniversary release} + +Yes, it's now 10~years since the first release in this series and, for +Knuthists, this release also contains \textit{Issue 16}\,! + +Meanwhile this \textit{Issue~15} describes the major new features in +the current release whilst \textit{Issue~16} looks\newline +a little way into the future of \LaTeX{}. + + +\section{LPPL -- new version} + +Most importantly, there is now a new version, 1.3, of the \LaTeX{} +Project Public Licence. Many of you will\newline +be thrilled to know that, following the exchange of over 1600 e-mail +messages dissecting various aspects of its philosophy such as `how +many angels can appear in the name of a file before it becomes +non-free', this version\newline +is now officially a DFSG (Debian Free Software Guidelines) approved license. +The discussions start at +\url{http://lists.debian.org/debian-legal/2002/debian-legal-200207/threads.html} +with high traffic throughout August to October~2002 and further +heated discussions starting in April~2003 and concluding +around June at +\url{http://lists.debian.org/debian-legal/2003/debian-legal-200306/msg00206.html}. + +The important features of the new version are useful clarifications in +the wording, and revised procedures\newline +for making a change to the Current Maintainer of a package. Special +thanks to all those people from\newline Debian Legal who worked +constructively with us\newline +on this onerous task, especially but not exclusively\newline +Jeff Licquia and Branden Robinson. + + +\section{Small updates to varioref} + +The English has been corrected in \verb|\reftextbefore| +(an incompatible change). There are other extensions +such as \verb|\labelformat|, \verb|\Ref|, \verb|\Vref| and \verb|\vpagerefnum|. +Some Dutch text has also been changed and two\newline +new options added: \package{slovak} and \package{slovene}. + + +\section{New and more robust commands} + +Many of the math mode commands for compound symbols have been made +robust and a new robust command has been added: \verb|\nobreakdashes|. +This last is a low-level command, borrowed from the \package{amsmath} +package, for use only before hyphens or dashes. It prevents the line +break that is normally allowed\newline +after the following sequence of dashes. + + +\section{Fixing font sizes} + +The new \package{fix-cm} package, by Walter Schmidt, changes the CM font +definition (\texttt{.fd}) files so that similar design sizes are used +in both the \texttt{OT1} and \texttt{T1} encodings. + + +\section{Font encodings} + +A number of options have been added to the \package{textcomp} package, +enabling only available glyphs to be used. +Also, the `NFSS font families' are now divided into five different groups +according to the subset of glyphs each provides from the full +collection of symbols in the TS1 encoding. +Given sufficient information about a font family +\package{textcomp} will use this in order to limit the\newline +typesetting to those glyphs that are available. + +Use of this mechanism has also enhanced \verb|\oldstylenums| +to use the current font if possible. + + +\section{Displaying font tables} + +With the \package{nfssfont} package you can now +specify the font to display by giving its `NFSS classification', +rather than needing to know its external font file's name. +It is also now possible to generate large collections of font +tables in batch mode by providing a suitable input file. + + +\section{New input encodings} + +The \package{inputenc} package has been extended as follows: +\package{macce} input encoding +(Apple Central European), +thanks to Radek Tryc and Marcin Wolinski; \package{cp1257}\newline +for Baltic languages; \package{latin10}, +thanks to Ionel Ciob\^{i}c\u{a}.\newline +The euro symbol has by +now been added to several encodings: +\package{ansinew}, \package{cp1250} +and \package{cp1252} (which also\newline +has another addition), whilst \package{cp858} +adds it to \package{cp850}. + + +\section{Unicode input} + +Partial, experimental support for text files that use the Unicode +encoding form UTF-8 is now provided by the option \package{utf8} for +the \package{inputenc} package. + +The only Unicode text file characters supported by the current version +are those based on the most common inputs for glyphs from the small +collection\newline +of standard \LaTeX{} Latin encodings. + + +\section{And finally \ldots\ pict2e} + +The old, non-functional version of this package has been removed + as there is now a fully working version from Hubert G\"a{\ss}lein + and Rolf Niepraschk. It is described + in \textit{The \LaTeX{} Manual}. + +\end{document} diff --git a/macros/latex-dev/doc/ltnews16.tex b/macros/latex-dev/doc/ltnews16.tex new file mode 100644 index 0000000000..69e05973a8 --- /dev/null +++ b/macros/latex-dev/doc/ltnews16.tex @@ -0,0 +1,161 @@ +% \iffalse meta-comment +% +% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 +% The LaTeX3 Project and any individual authors listed elsewhere +% in this file. +% +% This file is part of the LaTeX base system. +% ------------------------------------------- +% +% 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 +% 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 file has the LPPL maintenance status "maintained". +% +% The list of all files belonging to the LaTeX base distribution is +% given in the file `manifest.txt'. See also `legal.txt' for additional +% information. +% +% The list of derived (unpacked) files belonging to the distribution +% and covered by LPPL is defined by the unpacking scripts (with +% extension .ins) which are part of the distribution. +% +% \fi +% Filename: ltnews16.tex +% +% This is issue 16 of LaTeX News. + +\documentclass +% [lw35fonts] % uncomment this line to get Palatino + {ltnews}[2004/02/28] + +% \usepackage[T1]{fontenc} + +\publicationmonth{December} +\publicationyear{2003} +\publicationissue{16} + +\begin{document} + +\maketitle + +%\raisefirstsection + +\section{Anniversary news} + +This anniversary \textit{Issue~16} takes a brief look into the future work of +the \LaTeX3 Project Team, both short and and longer range. Please let +us know if you want %\newline +to get involved with us in any of this work (see below). + +An overview of the 10th Anniversary Release, dated 2003/12/01, is +can be found in \textit{Issue~15}. + + +\section{TLC2: The \LaTeX{} Companion -- 2nd edition!} + +Since you are reading this newsletter, there is a good chance that +you, or a friend, has already bought this encyclopedic volume: the +incomparable Second\newline +Edition of this work that is every \LaTeX{}ie's\newline +ultimate lucky charm. + +If by some chance you have not yet purchased your own copy then get +into training, get shopping, and get flexing your muscles (both +physical---it's $1100+$~pages,\newline +and intellectual) by using it to discover +masses of invaluable `insider information' about: +\begin{itemize} +\item the latest release of Standard \LaTeX{}; +\item over~200~extension packages; +\item plus related software and systems. +\end{itemize} +For more information on this all new (??\ldots OK,\newline +not \emph{all}, but over 90\%!!), +all accurate (we hope!)\newline +10th~Anniversary Edition, check out\newline + \mbox{\url{http://www.awprofessional.com/titles/0201362996}}. + + +\section{Future maintenance} + +We are currently exploring how best to support the very large and +rapidly growing community of individuals, organisations and +enterprises that depend on the robustness and availability of the +current standard \LaTeX{} distribution. Although we remain firmly\newline +resolved not to make changes in the base distribution (the kernel) of +Standard \LaTeX{}, there is still much that needs doing to maintain +its reliability and utility and to keep up the necessary level of +communication with users and supporters. Also, as with all advanced +software systems, bugs are still turning up occasionally so %\newline +some fixes are still essential. + +One major impediment to providing adequate service levels in this area +is, of course, the difficulties inherent in obtaining the time and +commitment of skilled minds---hence the appeal above to anyone +interested %\newline +in getting involved. + + +\section{LPPL certification} + +There are still some outstanding diplomatic tasks around the +\LaTeX{} Project Public Licence: these include +e.g.,~getting it `OSF certified' and ensuring that it gains +more support and wider use, even in the FSF world\newline +where it has long been tolerated. + + +\section{Use of \eTeX/pdf\TeX} + +We expect that within the next two years, releases of \LaTeX{} will +change modestly in order to run best under an extended \TeX{} engine +that contains the \eTeX{} primitives, e.g., \eTeX{} or pdf\TeX{}. +The details of this possible upgrade need further work so we are not +making a definite announcement yet. + +Although the current release does not \emph{require} \eTeX{} features, +we certainly recommend using an extended \TeX{}, especially if you +need to debug macros. + + +\section{End of `autoload' support} + +As computer systems generally grow in capacity, requirements change +and so we believe that the \package{autoload} variant of \LaTeX{} is +no longer required. Thus, although the code remains it is no longer +supported. We hope this does not cause any problems. + + +\section{New models, new code} + +In the period 1999--2001 we published many results of our work over +the previous decade on the development of new concepts and models +for automated typesetting based on \TeX{} as the underlying platform. +These can be found at \url{http://www.latex-project.org/papers/} +and +\mbox{\url{http://www.latex-project.org/code/experimental/}}. + +Since then a very large proportion of the The Team's efforts have been +diverted to provide the core author team for TLC2, which provides +over 1000 pages of carefully researched and tested documentation of +many aspects of the vast world of \LaTeX{} related software that +was developed over that same time period and that continues +to grow and improve prodigiously. + +Completion of that task \ldots\ until TLC3!! \ldots\ presents the +possibility of getting back to this more exciting development work, +or even to more radical work on non-\TeX{}-based models and +implementations. + +Of course, any such ideas are predicated on our ability to organise +(with you, we hope) an efficient\newline +but responsive maintenance and support system\newline +for Standard \LaTeX{}. + +\end{document} diff --git a/macros/latex-dev/doc/ltnews17.tex b/macros/latex-dev/doc/ltnews17.tex new file mode 100644 index 0000000000..99267429bc --- /dev/null +++ b/macros/latex-dev/doc/ltnews17.tex @@ -0,0 +1,230 @@ +% \iffalse meta-comment +% +% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 +% The LaTeX3 Project and any individual authors listed elsewhere +% in this file. +% +% This file is part of the LaTeX base system. +% ------------------------------------------- +% +% 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 +% 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 file has the LPPL maintenance status "maintained". +% +% The list of all files belonging to the LaTeX base distribution is +% given in the file `manifest.txt'. See also `legal.txt' for additional +% information. +% +% The list of derived (unpacked) files belonging to the distribution +% and covered by LPPL is defined by the unpacking scripts (with +% extension .ins) which are part of the distribution. +% +% \fi +% Filename: ltnews17.tex +% +% This is issue 17 of LaTeX News. + +\documentclass +% [lw35fonts] % uncomment this line to get Palatino + {ltnews}[2004/02/28] + +% \usepackage[T1]{fontenc} + + +\publicationmonth{December} +\publicationyear{2005} +\publicationissue{17} + +\begin{document} + +\maketitle + +% \raisefirstsection + +\section{Project licence news} + +The \LaTeX{} Project Public License has been updated slightly so that +it is now version 1.3c. In the warranty section the +phrase ``unless required by applicable law'' has been reinstated, +having got lost at some point. Also, +it now contains three clarifications: of the difference between +``maintained'' and ``author-maintained''; of the +term ``Base Interpreter''; and when clause 6b and 6d shall not apply. + +Following requests, we now also provide the text of the licence as a +\LaTeX{} document (in the file \texttt{lppl.tex}). This file can be +processed either as a stand-alone document or it can be included +(without any modification) into another \LaTeX{} document, e.g., as an +appendix, using \verb|\input| or \verb|\include|. + + +\section{New guide on font encodings} + +Way back in 1995 work was started on a guide to document the +officially allocated \LaTeX{} font encoding names. However, for one +reason or another this guide (named \textit{\LaTeX{} font encodings}) +was, until now, not added to the distribution. It describes the major +7-bit and 8-bit font encodings used in the \LaTeX{} world and explains +the restrictions required of conforming text font encodings. It also +lists all the `encoding specific commands' (the LICR or \LaTeX{} +Internal Character Representation) for characters supported by the +encodings \texttt{OT1} and \texttt{T1}. + +When the file \texttt{encguide.tex} is processed by \LaTeX{}, it will +attempt to typeset an encoding table for each encoding it describes. +For this to be possible, \LaTeX{} must be able to find \texttt{.tfm} +files for a representative example font for each encoding. If +\LaTeX{} cannot find such a file then a warning is issued and the +corresponding table is omitted. + + +\section{Robust commands in math} + +The font changing commands in text-mode have been robust commands for years, +but the same has not been true for the math versions such as +\verb|\mathbf|. While the math-mode commands worked correctly in +section heads, they could cause problems in other places such as index +entries. With this release, these math-mode commands are now robust in +the same way as their text-mode counterparts. + +%% +\pagebreak +%% + + +\section{Updates of required packages} + +Several of the packages in the \package{tools} bundle have been updated +for this release. + +The \package{xspace} package has some new features. One is an +interface for adding and removing the exceptions it knows about and +another is that it works with active characters. These remove problems +of incompatibility with the \package{babel} system. + +In \textit{\LaTeX\ News~16} we announced that some packages might +begin to take advantage of \eTeX{} extensions on systems where these +are available: and the latest version of \package{xspace} does just +that. Note also that \package{fixltx2e} will make use of the +facilities in \eTeX{} whenever these are present (see below). + +The \package{calc} package has also been given an update with a few +extra commands. +The commands \verb|\maxof| and \verb|\minof|, each with two +brace-delimited arguments, provide the usual numeric $\max$ and $\min$ +operations. The commands \verb|\settototalheight| and +\verb|\totalheightof| work like \verb|\settoheight| and +\verb|\heightof|. There are also some internal improvements to make +\package{calc} work with some more primitive \TeX\ constructs, such as +\verb|\ifcase|. + +The \package{varioref} package has acquired a few more default +strings but there are still a number of languages for +which good strings are still missing. + +The \package{showkeys} package has also been updated slightly to work +with more recent developments in \package{varioref}. Also, it now +provides an easy way to define the look of the printed labels with +the command \verb|\showkeyslabelformat|. + +\section{Work on \LaTeX{} fixes} + +The package known as \package{fixltx2e} has three new additions. A new +command \verb|\textsubscript| has been added as a complement to the +command \verb|\textsuperscript| in the kernel. Secondly, a new form of +\verb|\DeclareMathSizes| that allows all of its arguments to have a +dimension suffix. This means you can now use expressions such as +\verb|\DeclareMathSizes{9.5dd}{9.5dd}{7.4dd}{6.6dd}|. + +The third new +addition is the robust command \verb|\TextOrMath| which takes two +arguments and executes one of them when typesetting in text or math +mode respectively. This command also takes advantage of \eTeX{} +extensions if available; more specifically, +%% +%%\pagebreak +%% +when the \eTeX{} extensions are available, it does not +destroy kerning between previous letters and the text to be typeset. +The command is also used +internally in \package{fixltx2e} to resolve a problem with +\verb|\fnsymbol|. + +Also, further work has been done on reimplementing +the command \verb|\addpenalty|, which is used internally in several +places: we hope it is an improvement! + +\section{The graphics bundle} + +The \package{graphics} bundle now supports the +\package{dvipdfmx} post-processor and Jonathan Kew's XE\TeX\ +program. By support we mean that the graphics packages recognize the +new options \texttt{xetex} and \texttt{dvipdfmx} but we do not +distribute the respective driver files. + +This leads elegantly to a description of the +new policy concerning such driver files in the \package{graphics} bundle. +Most driver files for our graphics packages are maintained by the +developers of the associated post-processor or \TeX\ programs. +The teams developing these packages are working very hard: their rapid +development offers a stark contrast to the current schedule of \LaTeX\ +releases. It is therefore no longer practical +for the \LaTeX\ Team to be responsible for distributing the +latest versions of these driver files. + +Therefore the installation files for \package{graphics} have been +split: there is now \file{graphics.ins} to install the package files and +\file{graphics-drivers.ins} for the driver files (located in +\file{drivers.dtx}). +There is no need +to install all those provided in the file \file{drivers.dtx}. + +Please also note that, as requested by the maintainers of +\package{PStricks}, we have removed the package \package{pstcol} as +current versions of \package{PSTricks} make it obsolete. + +%% +\newpage +%% + + +\section{Future development} + +The title of this section is a little misleading as it actually +describes \emph{current} development. In 1998 the \package{expl3} +bundle of packages was put on \ctan\ to demonstrate a possible \LaTeX3 +programming environment. These packages have been lying dormant for some +time while the \LaTeX\ Project Team were preoccupied by other things +such as developing the experimental packages \package{xor}, +\package{template}, etc., (and also writing that indispensable +and encyclopaedic volume,\\ +The \LaTeX{} Companion -- 2nd edition). + +In October 2004 work on this code base was resumed with the goal of +some day turning it into a kernel for \LaTeX3. This work can now +also make full use of the widely accepted \eTeX\ extensions. Currently +two areas are central to this work. + +\begin{itemize} +\item Extending the + kernel code of \LaTeX3. +\item Converting the experimental packages + such as \package{xor}, \package{template} to use the new + syntax internally. +\end{itemize} + +Beware! Development of +\package{expl3} is happening so fast that the descriptions above might +be out of date when you read this! If you wish to see what's going on +then go to +\url{http://www.latex-project.org/code.html} where you can download + fully working code (we hope!). + +\end{document} + diff --git a/macros/latex-dev/doc/ltnews18.tex b/macros/latex-dev/doc/ltnews18.tex new file mode 100644 index 0000000000..4e6090c02b --- /dev/null +++ b/macros/latex-dev/doc/ltnews18.tex @@ -0,0 +1,51 @@ +% \iffalse meta-comment +% +% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 +% The LaTeX3 Project and any individual authors listed elsewhere +% in this file. +% +% This file is part of the LaTeX base system. +% ------------------------------------------- +% +% 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 +% 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 file has the LPPL maintenance status "maintained". +% +% The list of all files belonging to the LaTeX base distribution is +% given in the file `manifest.txt'. See also `legal.txt' for additional +% information. +% +% The list of derived (unpacked) files belonging to the distribution +% and covered by LPPL is defined by the unpacking scripts (with +% extension .ins) which are part of the distribution. +% +% \fi +% Filename: ltnews18.tex +% +% This is issue 18 of LaTeX News. + +\documentclass + [lw35fonts] % uncomment this line to get Palatino + {ltnews}[2004/02/28] + +% \usepackage[T1]{fontenc} + + +\publicationmonth{December} +\publicationyear{2007} +\publicationissue{18} + +\begin{document} + +\maketitle + +\noindent This news never existed. + +\end{document} + diff --git a/macros/latex-dev/doc/ltnews19.tex b/macros/latex-dev/doc/ltnews19.tex new file mode 100644 index 0000000000..6441449c2a --- /dev/null +++ b/macros/latex-dev/doc/ltnews19.tex @@ -0,0 +1,116 @@ +% \iffalse meta-comment +% +% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 +% The LaTeX3 Project and any individual authors listed elsewhere +% in this file. +% +% This file is part of the LaTeX base system. +% ------------------------------------------- +% +% 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 +% 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 file has the LPPL maintenance status "maintained". +% +% The list of all files belonging to the LaTeX base distribution is +% given in the file `manifest.txt'. See also `legal.txt' for additional +% information. +% +% The list of derived (unpacked) files belonging to the distribution +% and covered by LPPL is defined by the unpacking scripts (with +% extension .ins) which are part of the distribution. +% +% \fi +% Filename: ltnews19.tex +% +% This is issue 19 of LaTeX News. + +\documentclass{ltnews} + +\usepackage[T1]{fontenc} + +\usepackage{lmodern,url} + +\publicationmonth{September} +\publicationyear{2009} + +\publicationissue{19} + +\begin{document} + +\maketitle + +\section{New \LaTeX\ release} + +This issue of \LaTeX~News marks the first release of a new version of +\LaTeXe\ since the publication of The \LaTeX\ Companion in 2005--2006. + +Just in time for \TeX\ Live 2009, this version is a maintenance +release and introduces no new features. A number of small changes have +been made to correct minor bugs in the kernel, slightly extend the Unicode +support, and improve various +aspects of some of the \texttt{tools} packages. + +\section{New code repository} + +Since the last \LaTeX\ release, the entire code base has been moved +to a public \textsc{svn} repository% +\footnote{\url{http://www.latex-project.org/svnroot/latex2e-public/}} +and the entire build architecture re-written. In fact, it has only +been possible for us to consider a new \LaTeX\ release since earlier +this year when the test suite was finally set up with the new system. +In the process, a bug in the \LaTeX\ picture fonts distributed with +\TeX\ Live was discovered, proving that the +tests are working and are still very valuable. + +Now that we can easily generate new packaged versions of the \LaTeXe\ +distribution, we expect to be able to roll out bug fixes in a much +more timely manner than over the last few years. New versions should +be distributed yearly with \TeX\ Live. Having said this, the +maintenance of the \LaTeXe\ kernel is slowing down as the bugs become +fewer and more subtle. Remember that we cannot change any of the +underlying architecture of the kernel or any design decisions of the +standard classes because we must preserve backwards compatibility with +legacy documents at all costs. + +Even new features cannot be added, because any new documents using +them will not compile in systems (such as journal production engines) +that are generally not updated once they've been proven to work as +necessary. + +None of this is to say that we consider \LaTeXe\ to be any less +relevant for document production than in years past: a stable system +is a useful one. +Moreover, the package system continues to provide a flourishing and stable +means +for the development of a wide range of extensions. + +\newpage + +\section{Babel} + +One area of the \LaTeXe\ code base that is still receiving feedback to +be incorporated into the main distribution is the Babel system for +multilingual typesetting. +While the Babel sources have already been added to the \textsc{svn} repository the +integration of the test system for Babel is still outstanding. + + +\section{The future} + +While work on \LaTeXe\ tends to maintenance over active development, +the \LaTeX3 project is +seeing new life. Our goals here are to provide a transition from the +\LaTeXe\ document processing model to one with a more flexible +foundation. Work is continuing in the \textsf{expl3} programming +language and the \textsf{xpackages} for document design. Future +announcements +about \LaTeX3 will be available via the \LaTeX\ Project +website and in TUGboat. + +\end{document} diff --git a/macros/latex-dev/doc/ltnews20.tex b/macros/latex-dev/doc/ltnews20.tex new file mode 100644 index 0000000000..b095411c67 --- /dev/null +++ b/macros/latex-dev/doc/ltnews20.tex @@ -0,0 +1,153 @@ +% \iffalse meta-comment +% +% Copyright 1993--2011 +% The LaTeX3 Project and any individual authors listed elsewhere +% in this file. +% +% This file is part of the LaTeX base system. +% ------------------------------------------- +% +% 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 +% 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 file has the LPPL maintenance status "maintained". +% +% The list of all files belonging to the LaTeX base distribution is +% given in the file `manifest.txt'. See also `legal.txt' for additional +% information. +% +% The list of derived (unpacked) files belonging to the distribution +% and covered by LPPL is defined by the unpacking scripts (with +% extension .ins) which are part of the distribution. +% +% \fi +% Filename: ltnews20.tex +% +% This is issue 20 of LaTeX News. + +\documentclass{ltnews} + +\usepackage[T1]{fontenc} + +\usepackage{lmodern,url} + +\publicationmonth{June} +\publicationyear{2011} + +\publicationissue{20} + +\begin{document} + +\maketitle + +\section{Scheduled \LaTeX\ bug-fix release} + +This issue of \LaTeX~News marks the first bug-fix release of +\LaTeXe\ since shifting to a new build system in 2009. +Provided sufficient changes are made each year, we expect to +repeat such releases once per year to stay in sync with \TeX\ Live. +Due to the excitement of \TeX's $2^5$-th birthday last year, +we missed our window of opportunity to do so for 2010. +This situation has been rectified this year! + +\section{Continued development} + +The \LaTeXe\ program is no longer being actively developed, as any non-negligible changes now could have dramatic backwards compatibility issues with old documents. Similarly, new features cannot be added to the kernel since any new documents written now would then be incompatible with legacy versions of \LaTeX. + +The situation on the package level is quite different though. While most of us have stopped developing packages for \LaTeXe{} there are many contributing developers that continue to enrich \LaTeXe{} by providing or extending add-on packages with new or better functionality. + +However, the \LaTeX\ team certainly recognises that there are improvements to be made to the kernel code; over the last few years we have been working on building, expanding, and solidifying the \textsf{expl3} programming layer for future \LaTeX\ development. We are using \textsf{expl3} to build new interfaces for package development and tools for document design. Progress here is continuing. + +\section{Release notes} + +In addition to a few small documentation fixes, the following changes have been made to the \LaTeXe\ code; in accordance with the philosophy of minimising forwards and backwards compatibility problems, most of these will not be noticeable to the regular \LaTeX\ user. + +\paragraph{Font subsets covered by Latin Modern and \TeX\ Gyre} + +The Latin Modern and \TeX\ Gyre fonts are a modern suite of families based +on the well-known Computer Modern and `PostScript 16' families with many additional +characters for high-quality multilingual typesetting.% +\footnote{% + See their respective TUGboat articles for more information:\\ + \url{http://www.tug.org/TUGboat/tb24-1/jackowski.pdf}\\ + \url{http://www.tug.org/TUGboat/tb27-2/tb87hagen-gyre.pdf}% +} + +Information about their symbol coverage in the \verb|TS1| encoding is now included +in \texttt{textcomp}'s default font definitions. + +% \paragraph{Private conditional switch in italic correction} +% negligible improvement/only useful to LaTeX programmers: not worth documenting I think? + +% \paragraph{Improve formatting in \texttt{doc} for filenames with some punctuation} +% negligible improvement, again? + +\paragraph{Redefinition of \cs{enddocument}} + +Inside the definition of \verb=\end{document}= the \texttt{.aux} file is read back in to resolve cross-references and build the table of contents etc. From 2.09 days this was done using \verb=\input= without any surrounding braces which could lead to some issues in boundary cases, especially if \verb=\input= was redefined by some package. It was therefore changed to use \LaTeXe{}'s internal name for this function. As a result, packages that modify \verb=\enddocument= other than through the officially provided hooks may need to get updated. + +\paragraph{Small improvement with split footnotes in \texttt{ftnright}} + +If in the first column there is more than a full column worth of footnote +material the material will be split resulting in footnotes out of +order. This issue is now at least detected and generates an error but the algorithm used by the package is +unable to gracefully handle it in an automated fashion (some alternatives for resolving the problem if it happens are given in the package documentation). + +\paragraph{Improvement in \texttt{xspace} and font-switching} + +The \texttt{xspace} package provides the command \verb|\xspace| +which attempts to be clever about inserting spaces automatically +after user-defined control sequences. +An important bug fix has been made to this command to correct its +behaviour when used in conjunction with font-switching commands +such as \verb|\emph| and \verb|\textbf|. +Previously, writing +\begin{verbatim} + \newcommand\foo{foo\xspace} + ... \emph{\foo} bar baz + ... \emph{\foo}, bar baz +\end{verbatim} +would result in an extraneous space being inserted after `foo' in +both cases; this has now been corrected. + + +\paragraph{RTL in \texttt{multicol}} + + The 1.7 release of \texttt{multicol} adds support for languages that are typeset + right-to-left. For those languages the order of the columns on the page + also needs to be reversed---something that wasn't possible in earlier releases. + +The new feature is supported through the +commands \verb|\RLmulticolcolumns| (switching to right-to-left typesetting) +and \verb|\LRmulticolcolumns| (switching to left-to-right typesetting) the +latter being the default. + +\paragraph{Improve French \texttt{babel} interaction with \texttt{varioref}} + + Extracting and saving the page number turned out to be a source of subtle + bugs. Initially it was done through an \verb"\edef" with a bunch of +\verb"\expandafter" commands inside. This posed a problem if the page number + itself contained code which needed protection (e.g., pr/4080) so this got + changed in the last release to use \verb"\protected@edef". However, that in turn failed with Babel +(bug report/4093) if the label contained active characters, e.g., a ``:'' in French. So now +we use (after one failed attempt pr/4159) even more \verb"\expandafter" commands and \verb"\romannumeral" trickery to avoid any expansion other + than what is absolutely required---making the code in that space absolutely unreadable. +\begin{verbatim} + \expandafter\def\expandafter#1\expandafter{% + \romannumeral + \expandafter\expandafter\expandafter + \z@ + \expandafter \@cdr + \romannumeral + \expandafter\expandafter\expandafter + \z@ + \csname r@#2\endcsname\@nil}% +\end{verbatim} +Code like this nicely demonstrates the limitations in the programming layer of \LaTeXe{} and the advantages that \textsf{expl3} will offer on this level. + +\end{document} diff --git a/macros/latex-dev/doc/ltnews21.tex b/macros/latex-dev/doc/ltnews21.tex new file mode 100644 index 0000000000..b7c87d6f32 --- /dev/null +++ b/macros/latex-dev/doc/ltnews21.tex @@ -0,0 +1,255 @@ +% \iffalse meta-comment +% +% Copyright 2014 +% The LaTeX3 Project and any individual authors listed elsewhere +% in this file. +% +% This file is part of the LaTeX base system. +% ------------------------------------------- +% +% 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 +% 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 file has the LPPL maintenance status "maintained". +% +% The list of all files belonging to the LaTeX base distribution is +% given in the file `manifest.txt'. See also `legal.txt' for additional +% information. +% +% The list of derived (unpacked) files belonging to the distribution +% and covered by LPPL is defined by the unpacking scripts (with +% extension .ins) which are part of the distribution. +% +% \fi +% Filename: ltnews21.tex +% +% This is issue 21 of LaTeX News. + +\documentclass{ltnews} +\def\ConTeXt{C\kern-.0333emon\-\kern-.0667em\TeX\kern-.0333emt} +\usepackage[T1]{fontenc} + +\usepackage{lmodern,url,hologo} + +\publicationmonth{May} +\publicationyear{2014} + +\publicationissue{21} + +\begin{document} + +\maketitle + +\section{Scheduled \LaTeX\ bug-fix release} + +This issue of \LaTeX~News marks the second bug-fix release of +\LaTeXe\ (standard \LaTeX) since shifting to a new build system in 2009. +Provided sufficient changes are made, we expect to +make such releases yearly or every two years, in sync with \TeX\ Live. + + + +\subsection{Release notes} + +This release makes no changes to the core code in the \LaTeXe\ format +but there are a small number of documentation fixes (not listed +here). In addition several packages in the \textsf{base} and +\textsf{required} areas have been updated as detailed below. + + +This has been done in accordance with the philosophy of minimising +problems in both forwards and backwards compatibility, so most of +these changes should not be noticed by the regular \LaTeX\ user. + +References in the text below of the form ``graphics/3873'' are to +bug reports listed +at:\\ \url{http://latex-project.org/cgi-bin/ltxbugs2html} + + +\let\paragraph\subsubsection + +\paragraph{\textsf{fixltx2e} updates} + + + +There are a number of bugs and faulty design decisions in \LaTeXe{} +that should have been corrected long ago in the kernel code. However, +such corrections cannot be done as this would break backwards +compatibility in the following sense. A large number of documents +exist by now that have worked around the bug or have even made use of +a particular misfeature. Thus changing the kernel code would break +too many existing documents. + +The corrections for these types of bug have therefore been collected together +in a package that can be loaded only when needed; its name is \textsf{fixltx2e}. +For this release we made the following changes to this package: +\begin{itemize} +\item + Misspelled float placement specifiers such as + \verb=\begin{figure}[tv]= instead of \texttt{tb} are silently + ignored by the kernel code. Now we test for such letters and issue + an error message. +\item + \LaTeX's float handling algorithm can get out of sync if you mix + single and double-column floats (as they are placed independently + of each other). This was corrected in \textsf{fixltx2e} a few years ago + but the fix was not perfect as one situation using + \verb=\enlargethispage= generated a low-level \TeX{} error. + This behaviour of the package is now improved. +\end{itemize} + + + + +\paragraph{New \textsf{fltrace} package} + +For years the file \texttt{ltoutput.dtx} contained some hidden code to +trace the detailed behaviour of the float placement algorithm of +\LaTeX. Prompted by questions on StackExchange we now extract this +code into a new \textsf{fltrace} package. To see the float algorithm +in action (or to understand why it decides to place all your floats at +the very end of the document) use +\begin{verbatim} + \usepackage{fltrace} \tracefloats +\end{verbatim} +To stop tracing somewhere in the document use +\verb=\tracefloatsoff= and to see the current value of various float +parameters use \verb=\tracefloatvals=. As the package is identical to +the kernel code with tracing added, it may or may not work if you load any +other package that manipulates that part of the kernel code. In such a +case your best bet is to load \textsf{fltrace} first. + +\paragraph{\textsf{inputenc} package updates} + +The \textsf{inputenc} package allows different input encodings for +\LaTeX\ documents to be specified including the important +\texttt{utf8} option used to specify the Unicode UTF-8 encoding. A +common mistake in documents has been to also include this option when +using the Unicode-based \TeX\ engines \hologo{LuaTeX} and \hologo{XeTeX} +producing strange errors as these engines natively deal with UTF-8 +characters. + +If a document stored in an 8bit encoding is processed by +\hologo{pdfTeX}, it needs the \textsf{inputenc} package to work +correctly. However, if such a document is processed unchanged by +\hologo{LuaTeX} or \hologo{XeTeX}, then accented characters may +silently get dropped from the output. + +The package has been modified so that if used with \hologo{LuaTeX} or +\hologo{XeTeX}, then it just issues a warning if \texttt{utf8} or +\texttt{ascii} is specified, and stops with an error for any other +encoding requested. + + + +One further improvement has been made to the encoding definition files +(\texttt{.def}) used by \textsf{inputenc}: the catcode of \texttt{@} +is now saved and restored when reading them instead of always using +\verb=\makeatother= inside the files (latex/4192). + + + +\paragraph{The tools directory} + +In the past each of the sub-directories in the ``required'' section of +the \LaTeX{} distribution contained a single \texttt{.ins} file to +generate the code files from the source files. We have now +started to provide individual \texttt{.ins} files for each of those +packages that are likely to require updates outside a major +\LaTeX{} release. + +\paragraph{\textsf{multicol} updates} + +Version 1.8 of \textsf{multicol} implements some improvements/fixes +and one extension. In the past the balancing algorithm enlarged the +column height until it found a solution that satisfied all +constraints. If there were insufficient break points then the final +column height could have been much larger than expected and if that +happened near the end of the page it resulted in the text overflowing +into the bottom margin. This situation is now detected and in that +case a normal page is cut and balancing is resumed on the next +page. Some overflow is still allowed and controlled via the parameter +\verb=\maxbalancingoverflow=. + +The use of \verb=\enlargethispage= is now properly supported within +the environment. Finally a new command \verb=\docolaction= was added +to allow the execution of code depending on the column in which the +command is executed. See the documentation for details. + +Bug fixes: the new version fixes both a color leak that could happen +in certain situations and the problem that \texttt{multicols} could +mess up the positioning of \verb=\marginpar=s that followed the +environment. + + +\paragraph{\textsf{tabularx} updates} + +The restrictions on embedding \verb|\tabularx| \verb|\endtabularx| +into the definition of a new environment have been relaxed +slightly. See the package documentation for details. + +\paragraph{\textsf{showkeys} updates} + +The \textsf{showkeys} package has been updated to fix problems if used +at the start of list items, and to work if brace groups (\verb|{| and +\verb|}|) are used in the optional argument of +\verb|\cite|. (tools/4162, tools/4173) + + +\paragraph{\textsf{color} updates} + +The \verb|\nopagecolor| command suggested by Heiko Oberdiek, +available for some years in the \textsf{pdftex} option, has been +added to the core package as suggested in graphics/3873. Currently +this is supported in the driver files for \textsf{dvips} and +\textsf{pdftex}. Patches to support other drivers are welcome. + + \paragraph{\textsf{graphicx} updates} + +The \textsf{graphicx} version of \verb|\rotatebox| now allows +\verb|\par| (and blank lines) in values, to match the change made +to the \textsf{graphics} version some years ago. See graphics/4296. + + +\paragraph{\textsf{keyval} updates} + +All parsing used in the \textsf{keyval} package has been changed +to allow \verb|\par| (and blank lines) in values. +(A second change, to parsing of brace groups +in a construct such as \texttt{key=\{\{\{value\}\}\}}, was reverted in v1.15.) +See graphics/3446. + + + + +\vfill + +\section{Standard \LaTeX\ (\LaTeXe) and \textsf{expl3}} + +The substantial collection of innovative code in \textsf{expl3} +implements a new programming language that has for a while now been +used by some writers of \LaTeXe\ packages. This code has recently +also been made available for use on top of plain \TeX\ or {\ConTeXt}, +largely to support generic packages that are supposed to work with +different flavours of \TeX. These uses in no way affect authors of +\LaTeX\ documents and such \LaTeXe\ packages will continue to work as +advertised by their authors with standard \LaTeX. + +This code base will also become an important foundation for the kernel +of \LaTeX3 and so the new programming language can be described as +`The \LaTeX3 Programming Language'. However, if you see or hear that a +package `uses \LaTeX3' then it remains very unlikely (as yet) to mean +that the package is part of some `new version of \LaTeX'. + +News about the development and use of \textsf{expl3} and about other +developments in the \LaTeX3 code base is reported regularly in the +\LaTeX3~News series (\url{http://latex-project.org/l3news/}), the most +recent issue of which was published in March 2014. + + +\end{document} diff --git a/macros/latex-dev/doc/ltnews22.tex b/macros/latex-dev/doc/ltnews22.tex new file mode 100644 index 0000000000..c574f60568 --- /dev/null +++ b/macros/latex-dev/doc/ltnews22.tex @@ -0,0 +1,244 @@ +% \iffalse meta-comment +% +% Copyright 2015 +% The LaTeX3 Project and any individual authors listed elsewhere +% in this file. +% +% This file is part of the LaTeX base system. +% ------------------------------------------- +% +% 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 +% 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 file has the LPPL maintenance status "maintained". +% +% The list of all files belonging to the LaTeX base distribution is +% given in the file `manifest.txt'. See also `legal.txt' for additional +% information. +% +% The list of derived (unpacked) files belonging to the distribution +% and covered by LPPL is defined by the unpacking scripts (with +% extension .ins) which are part of the distribution. +% +% \fi +% Filename: ltnews22.tex +% +% This is issue 22 of LaTeX News. + +\documentclass{ltnews} +\usepackage[T1]{fontenc} + +\usepackage{lmodern,url,hologo} + +\publicationmonth{January} +\publicationyear{2015} + +\publicationissue{22} + +\begin{document} + +\maketitle + +\section{New \LaTeXe\ bug-fix policy} + +\subsection{Introduction} + +For some years we have supplied bug fixes to the \LaTeXe\ kernel via the +\textsf{fixltx2e} package. This +kept the kernel stable, but at the expense of meaning that most users did not +benefit from bug fixes, and that some compromises +which were made to save space in the +machines of the time are still affecting most users today. + +In this release we have started a new update policy. All the fixes previously +available via \textsf{fixltx2e} are now enabled \emph{by default} in the +format, as are some further extensions for extended \TeX\ engines, \eTeX, +\hologo{XeTeX} and \hologo{LuaTeX}. Compatibility and stability are still +important considerations, and while most users will not notice these +improvements, or will want to benefit from them, a new \textsf{latexrelease} +package is provided that will revert all the changes and re-instate the +definitions from earlier releases. The package can also be used with older +releases to effectively \emph{update} the kernel to be equivalent to this 2015 +release. + +A new document, \textsf{latexchanges}, is distributed with the release +that documents all the changes to documented commands since the 2014 +\LaTeX\ release, and will be updated in future releases if further +changes have been made. + +\subsection{The \textsf{latexrelease} package} + +As noted above a new package is available to manage differences between \LaTeX\ +releases. If you wish to revert all changes back to the definitions as they +were in previous releases you may start your document requesting the \LaTeX{} release from May~2014: +\begin{verbatim} +\RequirePackage[2014/05/01]{latexrelease} +\documentclass{article} +\end{verbatim} +Conversely if you start a large project now and want to protect yourself +against possible future changes, you may start your document +\begin{verbatim} +\RequirePackage[2015/01/01]{latexrelease} +\documentclass{article} +\end{verbatim} +Then the version of \textsf{latexrelease} distributed with any future \LaTeX\ +release will revert any changes made in that format, and revert to the +definitions as they where at the beginning of 2015. + +If you wish to share a document using the latest features with a +user restricted to using an older +format, you may use the form above and make the \textsf{latexrelease} package +available on the older installation. The package will then update the format +definitions as needed to enable the older format to work as if dated on the date +specified in the package option. + +\subsection{The \cs{IncludeInRelease} command} + +The mechanism used in the \textsf{latexrelease} package is available for use in +package code. If in your \textsf{zzz} package you have +\begin{verbatim} +\RequirePackage{latexrelease} +\IncludeInRelease{2015/06/01} + {\zzz}{\zzz definition} + \def\zzz......new code +\EndIncludeInRelease +\IncludeInRelease{0000/00/00} + {\zzz}{\zzz definition} + \def\zzz....original +\EndIncludeInRelease +\end{verbatim} +then in a document using a format dated 2015/06/01 or later, the ``new code'' +will be used, and for documents being processed with an older format, the +``original'' code will be used. Note the format date here may be the original +format date as shown at the start of every \LaTeX\ run, or a format date +specified as a package option to the \textsf{latexrelease} package. + +So if the document has +\begin{verbatim} +\RequirePackage[2014/05/01]{latexrelease} +\documentclass{article} +\usepackage{zzz} +\end{verbatim} +then it will use the \emph{original} definition of \verb|\zzz| even if +processed with the current format, as the format acts as if dated 2014/05/01. + + +\subsection{Limitations of the approach} + +The new concept provides full backward and forward compatibility for +the \LaTeX{} format, i.e., with the help of a current +\textsf{latexrelease} package the kernel can emulate all released +formats (starting with 2014/06/01\footnote{Patching an older format + most likely works too, given that the changes in the past have been + minimal, though this isn't guaranteed and hasn't been tested.}). + + +However, this is not necessarily true for all packages. + Only if a package makes use of the \cs{IncludeInRelease} +functionality will it adjust to the +requested \LaTeX{} release date. Initially this will only be true for +a few selected packages and in general it may not even be advisable for packages +that have their own well-established release cycles and methods. + +Thus, to regenerate a document with 100\,\% compatible behavior +it will still be necessary +to archive it together with all its inputs, for example, by archiving +the base distribution trees (and any modifications made). However, the +fact that a document requests a specific \LaTeX{} release date should +help identifying what release tree to use to achieve perfect accuracy. + + +\section{Updates to the kernel} + +\subsection{Updates incorporated from \textsf{fixltx2e}} + +The detailed list of changes incorporated from \textsf{fixltx2e} is +available in the new \textsf{latexchanges} document that is +distributed with this release. The main changes are that $2$-column +floats are kept in sequence with one column floats, corrections are +made to the \verb|\mark| system to ensure correct page headings in +$2$-column documents, several additional commands are made robust. + +\subsection{\eTeX\ register allocation} + +\LaTeX\ has traditionally used allocation routines inherited from plain \TeX\ +that allocated registers in the range $0$--$255$. Almost all distributions have +for some years used \eTeX\ based formats (or \hologo{XeTeX} or \hologo{LuaTeX}) +which have $2^{15}$ registers of each type ($2^{16}$ in the case of +\hologo{LuaTeX}). The \textsf{etex} package has been available to provided an +allocation mechanism for these extended registers but now the format will by +default allocate in a range suitable for the engine being used. The new +allocation mechanism is different than the \textsf{etex} package mechanism, and +supports \hologo{LuaTeX}'s full range and an allocation mechanism for \LaTeX\ +floats as described below. + +On \eTeX\ based engines, an additional command, \verb|\newmarks| is available +(as with the \textsf{etex} package) that allocates extended \eTeX\ marks, and +similarly if \hologo{XeTeX} is detected a new command +\verb|\newXeTeXintercharclass| is available, this is similar to the command +previously defined in the \texttt{xelatex.ini} file used to build the +\texttt{xelatex} format. + +\subsection{Additional \LaTeX{} float storage} + +\LaTeX's float placement algorithm needs to store floats (figures and tables) +until it finds a suitable page to output them. It allocates $18$ registers for +this storage, but this can often be insufficient. + The contributed \textsf{morefloats} package has +been available to extend this list; however, it also only allocates from the +standard range $0$--$255$ so cannot take advantage of the extended registers. +The new allocation mechanism in this release incorporates a new command +\verb|\extrafloats|. If you get the error: +\mbox{\texttt{Too many unprocessed floats.}} +then you can add (say) \verb|\extrafloats{500}| to the document preamble to +make many more boxes available to hold floats. + + +\subsection{Built-in support for Unicode engines} + +The kernel sources now detect the engine being used and adjust definitions +accordingly, this reduces the need for the ``\texttt{.ini}'' files used to make +the formats to patch definitions defined in \texttt{latex.ltx}. + +As noted above the format now includes extended allocation routines. + +The distribution includes a file \textsf{unicode-letters.def} derived from the +Unicode Consortium's Unicode Character Data files that details the upper and +lower case transformation data for the full Unicode range. This is used to set +the \verb|lccode| and \verb|uccode| values if a Unicode engine is being used, +rather than the values derived from the T1 font encoding which are used with +8-bit engines. + +Finally \verb|\typein| is modified if \hologo{LuaTeX} is detected +such that it works with this engine. + +\section{l3build} + +This release has been tested and built using a new build system implemented in +\textsf{Lua}, intended to be run on the \textsf{texlua} interpreter distributed +with modern \TeX\ distributions. It is already separately available +from CTAN. This replaces earlier build systems (based at various times on +\textsf{make}, \textsf{cons}, and Windows \textsf{bat} files). It allows the +sources to be tested and packaged on a range of platforms (within the team, +OS X, Windows, Linux and Cygwin platforms are used). It also allows the +format to be tested on \hologo{XeTeX} and \hologo{LuaTeX} as well as the +standard \hologo{pdfTeX}/\eTeX\ engines. + +\section{Hyperlinked documentation and TDS zip files} + +As well as updating the build system, the team have looked again at exactly +what gets released to \textsc{ctan}. Taking inspiration from Heiko Oberdiek's +\textsf{latex-tds} bundle, the PDF documentation provided now includes +hyperlinks where appropriate. This has been done without modifying the sources +such that users without \textsf{hyperref} available can still typeset the +documentation using only the core distribution. At the same time, the release +now includes ready-to-install TDS-style zip files. This will be of principal +interest to \TeX\ system maintainers, but end users with older machines who +wish to manually update \LaTeX\ will also benefit. + +\end{document} diff --git a/macros/latex-dev/doc/ltnews23.tex b/macros/latex-dev/doc/ltnews23.tex new file mode 100644 index 0000000000..149bd1a74b --- /dev/null +++ b/macros/latex-dev/doc/ltnews23.tex @@ -0,0 +1,257 @@ +% \iffalse meta-comment +% +% Copyright 2015 +% The LaTeX3 Project and any individual authors listed elsewhere +% in this file. +% +% This file is part of the LaTeX base system. +% ------------------------------------------- +% +% 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 +% 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 file has the LPPL maintenance status "maintained". +% +% The list of all files belonging to the LaTeX base distribution is +% given in the file `manifest.txt'. See also `legal.txt' for additional +% information. +% +% The list of derived (unpacked) files belonging to the distribution +% and covered by LPPL is defined by the unpacking scripts (with +% extension .ins) which are part of the distribution. +% +% \fi +% Filename: ltnews23.tex +% +% This is issue 23 of LaTeX News. + +\documentclass{ltnews} +\usepackage[T1]{fontenc} + +\usepackage{lmodern,url,hologo} + +\makeatletter % -- provide command introduced in new release + % so this typesets with an old format + +% Check we are not in the preamble of a composite document +\def\@tempa{\@latex@error{Can be used only in preamble}\@eha} +\ifx\DeclareTextCommandDefault\@tempa +\else + \DeclareTextCommandDefault\textcommabelow[1] + {\hmode@bgroup\ooalign{\null#1\crcr\hidewidth\raise-.31ex + \hbox{\check@mathfonts\fontsize\ssf@size\z@ + \math@fontsfalse\selectfont,}\hidewidth}\egroup} +\fi +\makeatother + +\publicationmonth{October} +\publicationyear{2015} + +\publicationissue{23} + +\begin{document} + +\maketitle + +\tableofcontents + +\section{Enhanced support for \hologo{LuaTeX}} + +As noted in \LaTeX\ News 22, the 2015/01/01 release of \LaTeX{} +introduced built-in support for extended \TeX\ systems. + +The range of allocated register numbers (for example, for count +registers) is now set according to the underlying engine capabilities +to 256, 32768 or 65536. Additional allocators were also added for the +facilities added by \hologo{eTeX} (\verb|\newmark|) and \hologo{XeTeX} +(\verb|\newXeTeXintercharclass|). At that time, however, the work to +incorporate additional allocators for \hologo{LuaTeX} was not ready for +distribution. + +The main feature of this release is that by default it includes +allocators for \hologo{LuaTeX}-provided features, such as Lua +functions, bytecode registers, catcode tables and Lua callbacks. +Previously these features have been provided by the contributed +\package{luatex} (Heiko Oberdiek) and \package{luatexbase} +(\'{E}lie Roux, + Manuel P\'{e}gouri\'{e}-Gonnard and Philipp Gesang) +packages. However, just as +noted with the \package{etex} package in the previous release, it is +better if allocation is handled by the format to avoid problems with +conflicts between different allocation schemes, or definitions made +before a package-defined allocation scheme is enabled. + +The facilities incorporated into the format with this release, and +described below, are closely modelled on the \package{luatexbase} +package and we thank the authors, and especially \'{E}lie Roux, for +help in arranging this transition. + +The implementation of these \hologo{LuaTeX} features has been +redesigned to match the allocation system introduced in the 2015/01/01 +\LaTeX\ release, and there are some other differences from the previous +\package{luatexbase} package. However, as noted below, +\package{luatexbase} is being updated in line with this \LaTeX\ release +to provide the previous interface as a wrapper around the new +implementation, so we expect the majority of documents using +\package{luatexbase} to work without change. + +\subsection{Names of \hologo{LuaTeX} primitive commands} + +The 2015/01/01 \LaTeX\ release for the first time initialised +\hologo{LuaTeX} in \textsf{latex.ltx} if \hologo{LuaTeX} is being +used. Following the convention used in the contributed +\textsf{lualatex.ini} file used to set up the format for earlier +releases, most \hologo{LuaTeX}-specific primitives were defined with +names prefixed by \texttt{luatex}. This was designed to minimize name +clashes but had the disadvantage that names did not match the +\hologo{LuaTeX} manual, or the names used in other formats, and +produced some awkward command names such as \verb|\luatexluafunction|. +From this release the names are enabled without the \texttt{luatex} +prefix. + +In practice this change should not affect many documents; relatively +few packages access the primitive commands, and many of those are +already set up to work with prefixed or unprefixed names, so that they +work with multiple formats. + +For package writers, if you want to ensure that your code works with +this and earlier releases, use unprefixed names in the package and +ensure that they are defined by using code such as: +\begin{verbatim} +\directlua{tex.enableprimitives("", + tex.extraprimitives( + "omega", "aleph", "luatex"))} +\end{verbatim} +Conversely if your document uses a package relying on prefixed names +then you can add: +\begin{verbatim} +\directlua{tex.enableprimitives("luatex", + tex.extraprimitives( + "omega", "aleph", "luatex"))} +\end{verbatim} +to your document. + +Note the compatibility layer offered by the \package{luatexbase} package +described below makes several commands available under both names. + +As always, this change can be reverted using:\\ +\verb|\RequirePackage[2015/01/01]{latexrelease}|\\ +at the start of the document. + + + +\subsection{\TeX\ commands for allocation in \hologo{LuaTeX}} +For detailed descriptions of the new allocation commands see the +documented sources in \textsf{ltluatex.dtx} or chapter N of +\textsf{source2e}; however, the following new allocation commands are +defined by default in \hologo{LuaTeX}: +\verb|\newattribute|, +\verb|\newcatcodetable|, +\verb|\newluafunction| and +\verb|\newwhatsit|. +In addition, the commands \verb|\setattribute| and +\verb|\unsetattribute| are defined to set and unset Lua attributes +(integer values similar to counters, but attached to nodes). Finally +several catcode tables are predefined: +\verb|\catcodetable@initex|, +\verb|\catcodetable@string|, +\verb|\catcodetable@latex|, +\verb|\catcodetable@atletter|. + +\subsection{Predefined Lua functions} +If used with \hologo{LuaTeX}, \LaTeX\ will initialise a Lua table, +\textsf{luatexbase}, with functions supporting allocation and also +the registering of Lua callback functions. + +\subsection{Support for older releases and plain \TeX} +The \hologo{LuaTeX} allocation functionality made available in this +release is also available in plain \TeX\ and older \LaTeX\ releases +in the files \textsf{ltluatex.tex} and \textsf{ltluatex.lua} which may be +used simply by including the \TeX\ file: \verb|\input{ltluatex}|. +An alternative for old \LaTeX\ releases is to use:\\ +\verb|\RequirePackage[2015/10/01]{latexrelease}|\\ +which will update the kernel to the current release, including +\hologo{LuaTeX} support. + +\subsection{Additional \hologo{LuaTeX} support packages} +In addition to the base \LaTeX\ release two packages have been +contributed to the \textsf{contrib} area on CTAN. The +\package{ctablestack} package offers some commands to help package +writers control the \hologo{LuaTeX} \textsf{catcodetable} +functionality, and the \package{luatexbase} package replaces the +previously available package of the same name, providing a compatible +interface but implemented over the \package{ltluatex} code. + +\section{More Floats and Inserts} +If \hologo{eTeX} is available, the number of registers allocated in +the format to hold floats such as figures is increased from 18 to 52. + +The extended allocation system introduced in 2015/01/01 means that in +most cases it is no longer necessary to load the \package{etex} +package. Many classes and packages that previously loaded this package +no longer do so. Unfortunately in some circumstances where a package +or class previously used the \package{etex} \verb|\reserveinserts| +command, it is possible for a document that previously worked to +generate an error ``no room for a new insert''. In practice this error +can always be avoided by declaring inserts earlier, before the +registers below 256 are all allocated. However, it is better not +to require packages to be re-ordered and in some cases the re-ordering +is complicated due to delayed allocations in \verb|\AtBeginDocument|. + +In this release, a new implementation of +\verb|\newinsert| is used which allocates inserts from the previously +allocated float lists once the classical register allocation has run +out. This allows an extra 52 (or in \hologo{LuaTeX}, 64~thousand) +insert allocations which is more than enough for practical documents +(by default, \LaTeX\ only uses two insert allocations). + +\section{Updated Unicode data} + + +The file \textsf{unicode-letters.def} recording catcodes, upper and +lower case mappings and other properties for Unicode characters has +been regenerated using the data files from Unicode~8.0.0. + +\section{Support for Comma Accent} +The command \verb|\textcommabelow| has been added to the format. +This is mainly used for the Romanian letters +\textcommabelow{S}\textcommabelow{s}\textcommabelow{T}\textcommabelow{t}. +This was requested in latex/4414 in the \LaTeX\ bug tracker. + +\section{Extended \package{inputenc}} +The \texttt{utf8} option for \package{inputenc} has been extended to support +the letters s and t with comma accent, +U+0218\,--\,U+021b. Similarly circumflex w and y U+0174\,--\,U+0177 are defined. +Also U+00a0 and U+00ad are declared by default, and defined to be +\verb|\nobreakspace| and \verb|\-| respectively. + +The error message given on undefined UTF-8 input characters +now displays the Unicode number +in U+\textit{hex} format in addition +to showing the character. + +\section{Pre-release Releases} +The patch level mechanism has been used previously to identify \LaTeX\ +releases that have small patches applied to the main release, without +changing the main format date. + +The mechanism has now been extended to allow identification of +pre-release versions of the software (which may or may not be released +via CTAN) but can be identified with a banner such as\\ +{\catcode`\<=13 \def<{\string<} \catcode`\>=13 \def>{\string>}% +\verb|LaTeX2e <2015/10/01> pre-release-1|}\\ +Internally this is identified as a patch release with a negative patch +level. + +\section{Updates in tools} + +The \package{multicol} package has been updated to fix the interaction +with ``here'' floats that land on the same page as the start or end of +a \textsf{multicols} environment. + +\end{document} diff --git a/macros/latex-dev/doc/ltnews24.tex b/macros/latex-dev/doc/ltnews24.tex new file mode 100644 index 0000000000..573f1e87c8 --- /dev/null +++ b/macros/latex-dev/doc/ltnews24.tex @@ -0,0 +1,263 @@ +% \iffalse meta-comment +% +% Copyright 2015,2016 +% The LaTeX3 Project and any individual authors listed elsewhere +% in this file. +% +% This file is part of the LaTeX base system. +% ------------------------------------------- +% +% 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 +% 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 file has the LPPL maintenance status "maintained". +% +% The list of all files belonging to the LaTeX base distribution is +% given in the file `manifest.txt'. See also `legal.txt' for additional +% information. +% +% The list of derived (unpacked) files belonging to the distribution +% and covered by LPPL is defined by the unpacking scripts (with +% extension .ins) which are part of the distribution. +% +% \fi +% Filename: ltnews24.tex +% +% This is issue 24 of LaTeX News. + +\documentclass{ltnews} +\usepackage[T1]{fontenc} + +\usepackage{lmodern,url,hologo} + +\makeatletter % -- provide command introduced in new release + % so this typesets with an old format + +% Check we are not in the preamble of a composite document +\def\@tempa{\@latex@error{Can be used only in preamble}\@eha} +\ifx\DeclareTextCommandDefault\@tempa +\else + \DeclareTextCommandDefault\textcommabelow[1] + {\hmode@bgroup\ooalign{\null#1\crcr\hidewidth\raise-.31ex + \hbox{\check@mathfonts\fontsize\ssf@size\z@ + \math@fontsfalse\selectfont,}\hidewidth}\egroup} + \DeclareTextCommandDefault\textcommaabove[1]{% + \hmode@bgroup + \ooalign{% + \hidewidth + \raise.7ex\hbox{% + \check@mathfonts\fontsize\ssf@size\z@\math@fontsfalse\selectfont`% + }% + \hidewidth\crcr + \null#1\crcr + }% + \egroup + } +\fi + +\makeatother + +\publicationmonth{February} +\publicationyear{2016} + +\publicationissue{24} + +\begin{document} + +\maketitle + +\tableofcontents + +\section{\hologo{LuaTeX} support} + +This release refines the \hologo{LuaTeX} support introduced in the +2015/10/01 release. A number of patches have been added to improve the +behavior of \package{ltluatex} (thanks largely to code review by Philipp Gesang). +The kernel code has been adjusted to +allow for changes in \hologo{LuaTeX} v0.85--v0.88. Most notably, newer +\hologo{LuaTeX} releases allow more than $16$ write streams and these are now +enabled for use by \verb|\newwrite|, but also the experimental +\texttt{newtoken} Lua library has been renamed back to \texttt{token} +which required small adjustments in the \hologo{LuaTeX} setup. + +The biggest change in \hologo{LuaTeX} v0.85--v0.87 compared to previous +versions is that all the primitives (originally defined in +\hologo{pdfTeX}) dealing with the PDF ``back end'' +are no longer defined, being replaced by a much smaller set of new primitives. +This does not directly affect the core \LaTeX{} +files in this release but has required major changes to the +\texttt{.ini} files used by \TeX{} Live and similar distributions to +set up the format files. These changes in the \hologo{LuaTeX} engine +will affect any packages using these back end commands (packages such +as \package{graphics}, \package{color}, \package{hyperref}, etc.). +Until all contributed packages are updated to the new syntax users may +need to add aliases for the old \hologo{pdfTeX} commands. A new +\package{luapdftexalias} package has been contributed to CTAN (not part of the +core \LaTeX\ release) that may be used for this purpose. + +See also the sections below for related changes in the +\textsf{tools} and \textsf{graphics} bundles. + + +\section{Unicode data} + +As noted in \LaTeX{} News~22, the 2015/01/01 release of \LaTeX{} introduced +built-in support for extended \TeX{} systems. In particular, the kernel now +loads appropriate data from the Unicode Consortium to set \verb|\lccode|, +\verb|\uccode|, \verb|\catcode| and \verb|\sfcode| values in an automated +fashion for the entire Unicode range. + +The initial approach taken by the team was to incorporate the existing model +used by (plain) \hologo{XeTeX} and to pre-process the ``raw'' Unicode data into +a ready-to-use form as \verb|unicode-letters.def|. However, the relationship +between the Unicode Consortium files and \TeX{} data structures is non-trivial and still +being explored. As such, it is preferable to directly parse the original +(\verb|.txt|) files at point of use. The team has therefore ``spun-out'' both +the data and the loading to a new generic package, \package{unicode-data}. This +package makes the original Unicode Consortium data files available in the +\verb|texmf| tree (in \verb|tex/generic/unicode-data|) and provides generic +loaders suitable for reading this data into the plain, \LaTeXe{}, and other, +formats. + +At present, the following data files are included in this new package: +\begin{itemize}\parskip=0pt + \item \verb|CaseFolding.txt| + \item \verb|EastAsianWidth.txt| + \item \verb|LineBreak.txt| + \item \verb|MathClass.txt| + \item \verb|SpecialCasing.txt| + \item \verb|UnicodeData.txt| +\end{itemize} +These files are used either by \LaTeXe{} or by \package{expl3} +(i.e.~they represent the set currently required by the team). The +Unicode Consortium provides various other data files and we would be happy to add +these to the generic package, as it is intended to provide a single place +to collect this material in the \verb|texmf| tree. Such requests can be +mailed to the team as~usual or logged at the package home page: +\url{https://github.com/latex3/unicode-data}. + +The new approach extends use of Unicode data in setting \TeX{} information in +two ways. First, the \verb|\sfcode| of all end-of-quotation/closing punctuation +is now set to $0$ (transparent to \TeX{}). Second, \verb|\Umathcode| values are +now set using \verb|MathClass.txt| rather than setting up only letters (which +was done using an arbitrary plane~$0$/plane~$1$ separation). There are also +minor refinements to the existing code setting, particularly splitting the +concepts of case and letter/non-letter category codes. + +For \hologo{XeTeX}, users should note that \verb|\xtxHanGlue| and +\verb|\xtxHanSpace| are \emph{no longer defined}, that no assignments are made +to \verb|\XeTeXinterchartoks| and that no \verb|\XeTeXintercharclass| data is +loaded into the format. The values which were previously inherited from +the plain \hologo{XeTeX} setup files are \emph{not} suitable for properly +typesetting East Asian text. There are third-party packages addressing this +area well, notably those in the \package{CTeX} bundle. Third-party packages +may need adjustment to load the data themselves; see the \textsf{unicode-data} +package for one possible loader. + +\section{More support for east European accents} + +As noted in \LaTeX{} News~23, comma accent support was added for \texttt{s} and +\texttt{t} in the 2015/10/01 release. In this release a matching +\verb|\textcommaabove| accent has been added for U+0123 (\verb|\c{g}|, +\textcommaabove{g}) which is the lower case of U+0122 (\verb|\c{G}|, +\textcommabelow{G}). In the OT1 and T1 encodings the combinations are +declared as composites with the \verb|\c| command, which matches the +Unicode names ``\textsf{latin (capital|small) letter g with cedilla}'' and +also allows \verb|\MakeUppercase{\c{g}}| to produce \verb|\c{G}|, as +required. In T1 encoding, the composite of \verb|\c| with \texttt{k}, \texttt{l}, +\texttt{n} and \texttt{r} are also +declared to use the comma below accent rather than cedilla to match the +conventional use of these letters. + +The UTF-8 \texttt{inputenc} option \texttt{utf8} has been extended to +support all latin combinations that can be reasonably constructed with a +(single) accent command an a base character for the T1 encoding so +\textcommaabove{g}, \k{u} and similar characters may be directly input +using UTF-8 encoding. + +\section{Changes in Graphics} + +The changes in \hologo{LuaTeX}~v0.87 mean that the \package{color} and +\package{graphics} packages no longer share the \texttt{pdftex.def} file +between \hologo{LuaTeX} and \hologo{pdfTeX}. A separate file +\texttt{luatex.def} (distributed separately) has been produced, and +distributions are encouraged to modify \texttt{graphics.cfg} and +\texttt{color.cfg} configuration files to default to the \texttt{luatex} +option if \hologo{LuaTeX}~v0.87 or later is being used. The team has +contributed suitable \texttt{.cfg} files to CTAN to be used +as models. + +Normally it is best to let the local \texttt{graphics.cfg} +automatically supply the right option depending on the \TeX\ engine +being used; however the \package{color} and \package{graphics} (and so +\package{graphicx}) packages have been extended to have an explicit +\texttt{luatex} option comparable to the existing \texttt{pdftex} and +\texttt{xetex} options. + +The \package{trig} package has been updated so that pre-computed values +such as $\sin(90)$ now expand to digits (\texttt{1} rather than the +internal token \verb|\@one| in this case). This allows them to be used +directly in PDF literal strings. + +\section{Changes in Tools} + +\hologo{LuaTeX} from version v0.87 no longer supports the +\verb|\write18| syntax to access system commands. A new package +\package{shellesc} has been added to \textsf{tools} that defines a new +command \verb|\ShellEscape| that may be used in all \TeX\ variants to +provide a consistent access to system commands. The package also +defines \verb|\write18| in \hologo{LuaTeX} so that it continues to access +system commands as before; see the package documentation for details. + +\section{Improving support for Unicode engines} + +\looseness=-1 +Stability concerns are always paramount when considering any change to +the \LaTeXe{} kernel. At the same time, it is important that the format +remains usable and gives reliable results for users. For the Unicode +\TeX{} engines \hologo{XeTeX} and \hologo{LuaTeX} there are important +differences in behavior from classical ($8$-bit) \TeX{} engines which +mean that identical default behaviors are not appropriate. Over the +past 18 months the team has addressed the most pressing of these +considerations (as detailed above and in \LaTeX{} News~22 and 23), +primarily by integrating existing patches into the kernel. There are, +though, important areas which still need consideration, and which +\emph{may} result in refinements to kernel support in this area in +future releases. + +The default font setup in \LaTeXe{} at present is to use the \texttt{OT1} +encoding. This assumes that hyphenation patterns have been read using +appropriate codes: the \texttt{T1} encoding is assumed. The commonly-used +hyphenation patterns today, \package{hyph-utf8}, are set up in this +way for $8$-bit engines (\hologo{pdfTeX}) but for Unicode engines use +Unicode code points. This means that hyphenation will be incorrect +with Unicode engines unless a Unicode font is loaded. This requires +a concept of a Unicode font encoding, which is currently provided by +the \package{fontspec} package in two versions, \texttt{EU1} and +\texttt{EU2}. The team is working to fully understand what is meant +by a ``Unicode font encoding'', as unlike a classical \TeX{} encoding +it is essentially impossible to know what glyphs will be provided +(though each slot is always defined with the same meaning). There +is also an overlap between this area and ideas of language and writing +system, most obviously in documents featuring mixed scripts (for example +Latin and Cyrillic). + +As well as these font considerations, the team is also exploring +to what extent it is possible to allow existing ($8$-bit) +documents to compile directly with Unicode engines without requiring +changes in the sources. Whether this is truly possible remains an open +question. + +It is important to stress that changes will only be made in this area where +they do \emph{not} affect documents processed with +\hologo{eTeX}/\hologo{pdfTeX} (i.e.~documents which are written for +``classical'' $8$-bit \TeX{} engines). Changes will also be made only where +they clearly address deficiencies in the current setup for Unicode engines +(i.e.~where current behaviors are wrong). + +\end{document} diff --git a/macros/latex-dev/doc/ltnews25.tex b/macros/latex-dev/doc/ltnews25.tex new file mode 100644 index 0000000000..e32187e702 --- /dev/null +++ b/macros/latex-dev/doc/ltnews25.tex @@ -0,0 +1,137 @@ +% \iffalse meta-comment +% +% Copyright 2016 +% The LaTeX3 Project and any individual authors listed elsewhere +% in this file. +% +% This file is part of the LaTeX base system. +% ------------------------------------------- +% +% 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 +% 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 file has the LPPL maintenance status "maintained". +% +% The list of all files belonging to the LaTeX base distribution is +% given in the file `manifest.txt'. See also `legal.txt' for additional +% information. +% +% The list of derived (unpacked) files belonging to the distribution +% and covered by LPPL is defined by the unpacking scripts (with +% extension .ins) which are part of the distribution. +% +% \fi +% Filename: ltnews25.tex +% +% This is issue 25 of LaTeX News. + +\documentclass{ltnews} +\usepackage[T1]{fontenc} + +\usepackage{lmodern,url,hologo} + + +\publicationmonth{March} +\publicationyear{2016} + +\publicationissue{25} + +\begin{document} + +\maketitle + +\section{Lua\TeX} +This \LaTeX\ release sees several internal changes designed to ensure +that the system is still usable with Lua\TeX\ versions greater than +0.80, which have introduced many changes into the engine, most notably +the removal or renaming of most of the primitive commands introduced by +pdf\TeX. Also the lists of Lua callbacks handled by the callback +allocation mechanism has been updated to match the callbacks defined +in Lua\TeX\ version 0.90. + +These changes have also required updates in \textsf{tools} +and \textsf{amsmath} as described below. + +This is the first release of \LaTeX\ for which the test suite reports +no failures when used with Lua\TeX. + +\section{Documentation checksums} +The \package{doc} package has always provided two mechanisms that were +mainly intended to guard against file truncation or corruption when +files were commonly distributed by email through unreliable mail +gateways: a Character Table of the ASCII character set could be +inserted (and checked) and a ``checksum'' (count of the number of +backslashes in the code sections) could be checked. These features +are not really needed with modern distribution mechanisms and can be a +distraction when reading the source code and so have been removed. The +\package{doc} package has been updated so that if you use a +\verb|\CheckSum| command then, as before, the number is checked; +however, if you omit the command then no error or warning is given. + + +\section{Updates to \package{inputenc}} + +The UTF-8 support in \package{inputenc} has been further extended with +support for non-breaking hyphens and more dashes. + +\section{Updates in Tools} + +The \package{varioref} package has been updated with improved +documentation of multi\-lingual support, and avoiding unnecessary warnings in +some cases with \verb|\reftextfaraway|. + +The \package{tabularx} package's handling of \verb|\endtabularx| in +environment definitions has been fixed to again match its documentation. + +The \package{bm} package has been updated as required by the changes +to \verb|\mathchardef| in Lua\TeX. + + +\section{amsmath} + +Since the launch of \LaTeXe\ in 1993, the \textsf{amsmath} bundle has +been part of the \emph{required} packages in the core \LaTeX\ +distribution, with bug reports handled by the \LaTeX\ bug database at +\url{https://latex-project.org/bugs-upload.html}. + +The \textsf{amsmath} packages and the \textsf{amscls} classes have +been maintained by the American Mathematical Society. + +With this release a new arrangement has been agreed between the +American Mathematical Society and the \LaTeX3 project. The \LaTeX3 +project will take over maintenance of the \textsf{amsmath} bundle, +with the American Mathematical Society retaining maintenance of +\textsf{amscls}. + +The recommended installation of these files in the \TeX\ directory +structure remains unchanged as \path|tex/latex/amsmath| and +\path|tex/latex/amscls| respectively. + +This release of \package{amsmath} includes several updates so that +\package{amsmath} does not generate errors when math is used with +Lua\TeX\ v0.87+, which has changes to \verb|\mathchardef| that are +incompatible with the previous version of \package{amsmath}. It also +improves \verb|\dots| handling so that \verb|\long| macros are +correctly handled (for example, \verb|\dots \Rightarrow| now +uses centered dots), as well as commands expanding to character tokens +(for example, \verb|\times \dots \times| will use centered dots with +\verb|\times| defined as in the \package{unicode-math} package). + +\section{Related updates} +In addition to the updates in the core \LaTeX\ release, some files in +the CTAN ``contrib'' area have also been updated. Notably there have +been further updates to the \textsf{unicode-data} files; also, the +files required to build plain and \LaTeX\ formats have now been +submitted to CTAN as \textsf{tex-ini-files}. The +addition of a new \texttt{luatex} option for \textsf{graphics}-related +packages (\textsf{luatex-def} on CTAN) has required updates to the +configuration files to select a +default option and these have similarly been uploaded to CTAN as +\textsf{graphics-cfg}. (Previously these files were maintained +directly in the \TeX\ Live repository, and were not available on CTAN.) +\end{document} \ No newline at end of file diff --git a/macros/latex-dev/doc/ltnews26.tex b/macros/latex-dev/doc/ltnews26.tex new file mode 100644 index 0000000000..3dc40ffb73 --- /dev/null +++ b/macros/latex-dev/doc/ltnews26.tex @@ -0,0 +1,239 @@ +% \iffalse meta-comment +% +% Copyright 2017 +% The LaTeX3 Project and any individual authors listed elsewhere +% in this file. +% +% This file is part of the LaTeX base system. +% ------------------------------------------- +% +% 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 +% 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 file has the LPPL maintenance status "maintained". +% +% The list of all files belonging to the LaTeX base distribution is +% given in the file `manifest.txt'. See also `legal.txt' for additional +% information. +% +% The list of derived (unpacked) files belonging to the distribution +% and covered by LPPL is defined by the unpacking scripts (with +% extension .ins) which are part of the distribution. +% +% \fi +% Filename: ltnews26.tex +% +% This is issue 26 of LaTeX News. + +\documentclass{ltnews} +\usepackage[T1]{fontenc} + +\usepackage{lmodern,url,hologo} + +\publicationmonth{January} +\publicationyear{2017} + +\publicationissue{26} + +\begin{document} + +\maketitle +\tableofcontents + +\setlength\rightskip{0pt plus 3em} +\section{\eTeX{}} + +In \LaTeX{} News~16 (December 2003) the team announced +\begin{quotation} +We expect that within the next two years, releases of \LaTeX{} will +change modestly in order to run best under an extended \TeX{} engine +that contains the \eTeX{} primitives, e.g., \eTeX{} or pdf\TeX{}. +\end{quotation} +and also said +\begin{quotation} +Although the current release does not \emph{require} \eTeX{} features, we +certainly recommend using an extended \TeX{}, especially if you need to debug +macros. +\end{quotation} + +For many years the team have worked on the basis that users will have \eTeX{} +available but had not revisited the above statements formally. As of the +January 2017 release of \LaTeXe{}, \eTeX{} is \emph{required} to build the +format, and attempting to build a format without the extensions will fail. + +Practically, modern \TeX{} distributions provide the extensions in all engines +other than the ``pure'' Knuth \texttt{tex}, and indeed parts of the +format-building process already require \eTeX{}, most notably some of the UTF-8 +hyphenation patterns. As such, there should be no noticeable effect on users of +this change. + +The team expect to make wider use of \eTeX{} within the kernel in future; +details will be announced where they impact on end users in a visible way. + +\section{Default encodings in \hologo{XeLaTeX} and \hologo{LuaLaTeX}} +The default encoding in \LaTeX\ has always been the original +128-character encoding \texttt{OT1}. For Unicode based \TeX\ engines, this +is not really suitable, and is especially problematic with +\hologo{XeLaTeX} as in the major distributions this is built with +Unicode based hyphenation patterns in the format. In practice this has +not been a major problem as documents use the contributed +\textsf{fontspec} package in order to switch to a +Unicode encoded font. + +In this release we are adding \texttt{TU} as a new supported +encoding in addition to the previously supported encodings such as \texttt{OT1} +and \texttt{T1}. This denotes a Unicode based font encoding. It is essentially +the same as the \texttt{TU} encoding that has been on trial with the +experimental \texttt{tuenc} option to \textsf{fontspec} for the past +year. + +The \hologo{XeLaTeX} and \hologo{LuaLaTeX} formats will now default +to \texttt{TU} encoding and \texttt{lmr} (Latin Modern) family. In the +case of \hologo{LuaLaTeX} the contributed \textsf{luaotfload} Lua +module will be loaded at the start of each run to enable the loading +of OpenType fonts. + +The \textsf{fontspec} package is being adjusted in a companion release +to recognise the new encoding default arrangements. + +Note that in practice no font supports the full Unicode range, and so +\texttt{TU} encoded fonts, unlike fonts specified for \texttt{T1}, may be +expected to be incomplete in various ways. In the current release the file +\texttt{tuenc.def} that implements the \texttt{TU} encoding-specific commands +has made some basic assumptions for (for example) default handling of +accent commands, and the set of command names is derived from the +command names used for the UTF-8 support in the \textsf{inputenc} package, +restricted roughly to the character ranges classically provided by +the \texttt{T1} and \texttt{TS1} encodings, but is part of a longer term plan +seen over recent releases to increase support for Unicode based \TeX\ engines +into the core \LaTeX\ support. + + + +If for any reason you need to process a document with the previous +default \texttt{OT1} encoding, you may switch encoding in the usual ways, for +example +\begin{verbatim} +\usepackage[OT1]{fontenc} +\end{verbatim} +or you may roll back all the changes for this release by starting the +document with +\begin{verbatim} +\RequirePackage[2016/12/31]{latexrelease} +\end{verbatim} + +\section{\cs{showhyphens} in \hologo{XeLaTeX}} +Due to the way \hologo{XeLaTeX} interfaces to font libraries, the +standard definition of \cs{showhyphens} does not work. A variant +definition has been available in the contributed \textsf{xltxtra} +package, however a (slightly different) definition for \cs{showhyphens} +is now included in \hologo{XeLaTeX} by default. As usual +this change will be undone if an earlier +release is specified using the \textsf{latexrelease} package. + +\section{The \textsf{fixltx2e} package} +As described in \LaTeX{} News~22, the \textsf{fixltx2e} package has become +obsolete with the new update policy. Since 2015 it has just made a +warning and exited. In this release we have re-introduced all +the code from the original fixes in the 2014 \LaTeX\ but guarded by +\verb|\IncludeInRelease{2015/01/01}|. +So for current releases \textsf{fixltx2e} still just displays a warning +but for old releases, whether that is an old format, or a format with +the version date reset via the \textsf{latexrelease} package, the +fixes in the original \textsf{fixltx2e} will be applied. + +This improves the ability to run old documents in a way that is compatible +with contemporary formats. If you have a 2014 document that used +\verb|\usepackage{fixltx2e}| and you add +\verb|\RequirePackage[2014/01/01]{latexrelease}| and process it with the +current format then \textsf{latexrelease} will undo most changes made +since 2014, but now when the document includes \textsf{fixltx2e} it +will act like a 2014 version of the package and apply the code fixes, +not just give a warning that the package is obsolete. + +\section{The \textsf{latexbug} package} + +As explained in more detail +at the \LaTeX\ Project + website\footnote{\url{https://www.latex-project.org/bugs/}} +a new package, \textsf{latexbug}, has been produced to help produce +test files to accompany bug reports on the core \LaTeX\ distribution. +This is being published separately to CTAN at the same time as this +release. By using the \textsf{latexbug} package you can easily check +that the packages involved in the test are all part of the core +release. The \LaTeX\ project cannot handle bug reports on contributed +packages, which should be directed to the package maintainer as given +in the package documentation. + +\section{Updates to \textsf{amsmath}} +The \textsf{amsmath} package has two updates at this release. +\begin{itemize} +\item The spacing to the left of the \texttt{aligned} and + \texttt{gathered} environments has been fixed: the spurious thin + space is no longer added by default. Package options control this + to revert to the original behaviour where required; see the + \textsf{amsldoc} guide for further details. +\item The large delimiters around generalised fractions (for example + in the \cs{binom} construct) did not work in previous releases if + using \hologo{LuaTeX} or \hologo{XeTeX} with OpenType math fonts. This is + related to the lack of specific metrics for this use in the OpenType Math + table. In principle \hologo{LuaTeX} has two additional named metrics + to control the delimiters but these are not initialised by default, + and in \hologo{XeTeX} it does not seem possible to make them work at all. + So for Unicode \TeX\ systems, a new implementation of + \cs{genfrac} is used at this release that uses \verb|\left\right| + internally but parameterised to give spacing as close to the + original as possible. The implementation in (pdf)\TeX\ is + unaffected. +\end{itemize} + +\section{Updates to \textsf{tools}} +The \textsf{array} package has been updated to fix a longstanding but +previously unreported issue with unwanted interactions between tables +in the page head or foot and the body of the page, as reported in +\href{http://www.latex-project.org/cgi-bin/ltxbugs2html?pr=tools/4488}{PR + tools/4488}. +There is also an update to the \hologo{LuaTeX} support in \textsf{bm}. + +\section{An addendum to the release changes in 2015: page breaks and vertical spacing} + +In 2015 we announced the introduction of the roll-back\slash +roll-forward concept to manage bug fixes and additions to core +\LaTeX{} in a manageable way. We also announced at that time +that we now incorporate all fixes from \textsf{fixltx2e} into the +kernel (as the old mechanism produced problems instead of improving +the situation). Refer to +\href{https://www.latex-project.org/news/latex2e-news/ltnews22.pdf}{\texttt{ltnews22.pdf}} +for details. + +One of the fixes from \textsf{fixltx2e} was for a glaring bug in +\cs{addvspace} that was originally detected in the mid-nineties and +back then added to the \textsf{fixltx2e} support package. In certain +situations \cs{addvspace} would result in a page/column break below +the baseline of the last line. As a result documents using +\cs{flushbottom} would show a clear misalignment (even more prominent +when typesetting in two-column mode). + +Starting with release 2015/01/01 this is now finally corrected already +in the kernel and not only in \textsf{fixltx2e}. In nearly all +circumstances this will either make no difference to existing +documents, or it will locally improve the visual appearance of that +document without changing anything on other pages. However, by the +nature of the change it is also possible that there are further +non-local changes to the page breaks due to the different break +positions introduced by the fix. + +Thus, for documents that have been written before 2015 and that should +be preserved unchanged at all costs you may have to add +\begin{verbatim} +\RequirePackage[2014/01/01]{latexrelease} +\end{verbatim} +at the top of the document, to roll back the format to a date before +the policy change. + +\end{document} diff --git a/macros/latex-dev/doc/ltnews27.tex b/macros/latex-dev/doc/ltnews27.tex new file mode 100644 index 0000000000..93281c1912 --- /dev/null +++ b/macros/latex-dev/doc/ltnews27.tex @@ -0,0 +1,135 @@ +% \iffalse meta-comment +% +% Copyright 2017 +% The LaTeX3 Project and any individual authors listed elsewhere +% in this file. +% +% This file is part of the LaTeX base system. +% ------------------------------------------- +% +% 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 +% 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 file has the LPPL maintenance status "maintained". +% +% The list of all files belonging to the LaTeX base distribution is +% given in the file `manifest.txt'. See also `legal.txt' for additional +% information. +% +% The list of derived (unpacked) files belonging to the distribution +% and covered by LPPL is defined by the unpacking scripts (with +% extension .ins) which are part of the distribution. +% +% \fi +% Filename: ltnews27.tex +% +% This is issue 27 of LaTeX News. + +\documentclass{ltnews} +\usepackage[T1]{fontenc} + +\usepackage{lmodern,url,hologo} + +\publicationmonth{April} +\publicationyear{2017} + +\publicationissue{27} + +\begin{document} + +\maketitle +\tableofcontents + +\setlength\rightskip{0pt plus 3em} + +\section{ISO 8601 Date format} +Since before the first releases of \LaTeXe, \LaTeX\ has used a date +format in the form \textsc{yyyy/mm/dd}. This has many advantages over more +conventional formats, as it is easy to sort and avoids the unfortunate +ambiguity between different communities as to whether 01/02/2017 is the +1st of February or 2nd of January. + +However there is another date format, formalised by the +International Standard ISO~8601. The basic format defined by this +standard is functionally equivalent to the \LaTeX\ format, but using +\texttt{-} rather than \texttt{/}. This date format is now supported +in many Operating Systems and applications +(for example the \verb|date --iso-8601| command in Linux and similar systems). + +From this release, \LaTeX\ will accept ISO format date strings in the +date argument of \verb|\ProvidesPackage|, \verb|\usepackage|, etc. +Currently we recommend that you do not use this format in any packages +that need to work with older \LaTeX\ releases; +the \textsf{latexrelease} package may be used with older releases to + add this functionality. This change is handled in a special way by + \textsf{latexrelease}: The package always adds support for ISO dates +whatever format date is requested; this is required so that the +necessary date comparisons may be made. + +The new functionality can be seen in the startup banner which +advertises \texttt{LaTeX2e <2017-04-15>}. + +\section{Further TU encoding improvements} +The 2017/01/01 release saw the introduction of the new TU encoding for +specifying Unicode fonts with \hologo{LuaTeX} and +\hologo{XeTeX}. There were a number of small corrections and additions +in the patch releases updating 2017/01/01, and a further addition in +this release, notably extended support for the dot-under accent, +\verb|\d|. + + +\section{Disabling hyphenation} +The existing \LaTeX\ code for \verb|\verb| and \verb|verbatim| had some +issues when used with fonts that were not loaded with hyphenation +disabled via setting \verb|\hyphenchar| to $-1$. In this release these +verbatim environments use a \verb|\language| setting, +\verb|\l@nohyphenation|, that has no hyphenation patterns associated. + +The format ensures that a language has been allocated with this name. +For most users this will in fact be no change as the standard +\textsf{babel} language has for a long time allocated a language with +this name. + +In order that page breaks in \texttt{verbatim} do not influence the +language used in the page head and foot, the format now normalises the +language used in the output routine to a default language as described +below. + +\section{Discretionary hyphenation} +The \LaTeX\ definition of \verb|\-| has been adjusted so that it will +insert the current font's \verb|\hyphenchar|, as would the +\TeX\ primitive. A comment in \textsf{source2e} has given +this new definition since the first releases of \LaTeXe, and in this +release we finally acted upon this comment. Previously \verb|\-| +always inserted a \texttt{-} at a break point even if a different +character would be used for automatic hyphenation with the current font. + +\section{Default document language} + +A new integer parameter \verb|\document@default@language| is +introduced; this is initialised to $-1$ but is set at +\verb|\begin{document}| to the language in force at that time if it + has not been set by preamble code. This is very similar to the + handling of the default color, and is used in a similar way to + normalise the settings for page head and foot as described above. +Users should not normally need to set this explicitly but it is expected that +language packages such as \textsf{babel} may set this if the default +behaviour is not suitable. + +\section{Line spacing in parboxes} +Inside a \verb|\parbox| +\LaTeX\ normalises the baseline spacing. However it has not +previously reset \verb|\lineskiplimit|. This meant that +lines of a paragraph that have ascenders or descenders could be set +with \emph{closer} line spacing than lines without. This can easily +happen if you use a \verb|\parbox| in an AMS alignment, as they use a +relatively large value of \verb|\lineskiplimit|. +As usual, the \textsf{latexrelease} package may be used to +force the older behavior. + +\end{document} diff --git a/macros/latex-dev/doc/ltnews28.tex b/macros/latex-dev/doc/ltnews28.tex new file mode 100644 index 0000000000..92c087e6b0 --- /dev/null +++ b/macros/latex-dev/doc/ltnews28.tex @@ -0,0 +1,365 @@ +% \iffalse meta-comment +% +% Copyright 2017-2018 +% The LaTeX3 Project and any individual authors listed elsewhere +% in this file. +% +% This file is part of the LaTeX base system. +% ------------------------------------------- +% +% 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 +% 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 file has the LPPL maintenance status "maintained". +% +% The list of all files belonging to the LaTeX base distribution is +% given in the file `manifest.txt'. See also `legal.txt' for additional +% information. +% +% The list of derived (unpacked) files belonging to the distribution +% and covered by LPPL is defined by the unpacking scripts (with +% extension .ins) which are part of the distribution. +% +% \fi +% Filename: ltnews28.tex +% +% This is issue 28 of LaTeX News. + +\documentclass{ltnews} +\usepackage[T1]{fontenc} + +\usepackage{lmodern,url,hologo} + +\providecommand\acro[1]{\textsc{#1}} +\providecommand\meta[1]{$\langle$\textit{#1}$\rangle$} + + +\publicationmonth{April} +\publicationyear{2018} + +\publicationissue{28} + +\begin{document} + +\maketitle +\tableofcontents + +\setlength\rightskip{0pt plus 3em} + +\section{A new home for \LaTeXe{} sources} + +In the past the development version of the \LaTeXe{} source files has +been managed in a Subversion source control system with read access +for the public. This way it was possible to download in an emergency +the latest version even before it was released to CTAN and made its +way into the various distributions. + +We have recently changed this setup and now manage the sources using +Git and placed the master sources on GitHub at +\begin{quote} +\url{https://github.com/latex3/latex2e} +\end{quote} +where we already store the sources +for \pkg{expl3} and other work. As before, direct write access is restricted +to \LaTeX{} Project Team members, but everything is publicly accessible +including the ability to download, clone (using Git) or checkout +(using SVN). More details are given in~\cite{Mittelbach:TB39-1}. + +\section{Bug reports for core \LaTeXe{}} + +For more than two decades we used GNATS, an open source bug tracking +system developed by the FSF. While that has served us well in the past +it started to show its age more and more. So as part of this move we +also decided to finally retire the old \LaTeX{} bug database and replace +it with the standard ``Issue Tracker'' available at Github. + +The requirements and the workflow for reporting a bug in the core +\LaTeX{} software is documented at +\begin{quote} +\url{https://www.latex-project.org/bugs/} +\end{quote} +and with further details also discussed in~\cite{Mittelbach:TB39-1}. + + +\section{UTF-8: the new default input encoding} + +The first \TeX{} implementations only supported reading 7-bit +\acro{ascii} files---any accented or otherwise ``special'' character +had to be entered using commands, if it could be represented at +all. For example to obtain an ``\"a'' one would enter \verb=\"a=, and to +typeset a ``\ss'' the command \verb=\ss=. Furthermore fonts at that +time had 128 glyphs inside, holding the \acro{ascii} characters, some +accents to build composite glyphs from a letter and an accent, and a +few special symbols such as parentheses, etc. + +With 8-bit \TeX{} engines such as \hologo{pdfTeX} this situation changed +somewhat: it was now possible to process 8-bit files, i.e., files that +could encode 256 different characters. However, 256 is still a fairly +small number and with this limitation it is only possible to encode a +few languages and for other languages one would need to change the +encoding (i.e., interpret the character positions 0--255 in a +different way). The first code points 0--127 were essentially normed +(corresponding to \acro{ascii}) while the second half 128--255 would +vary by holding different accented characters to support a certain set +of languages. + +Each computer used one of these encodings when storing or interpreting +files and as long as two computers used the same encoding it was +(easily) possible to exchange files between them and have them +interpreted and processed correctly. + +But different computers may have used different encodings and given +that a computer file is simply a sequence of bytes with no indication for +which encoding is intended, chaos could easily happen and has +happened. For example, the German word ``Gr\"o\ss e'' (height) entered on a +German keyboard could show up as ``Gr\v T\`ae'' on a different +computer using a different encoding by default. + +So in summmary the situation wasn't at all good and it was clear in +the early nineties that \LaTeXe{} (that was being developed to provide +a \LaTeX{} version usable across the world) had to provide a solution +to this issue. + +The \LaTeXe{} answer was the introduction of the \package{inputenc} +package~\cite{Mittelbach:Brno95} through which it is possible to +provide support for multiple encodings. It also allows to correctly +process a file written in one encoding on a computer using a different +encoding and even supports documents where the encoding changes +midway. + +Since the first release of \LaTeXe{} in 1994, \LaTeX{} documents that +used any characters outside \acro{ascii} in the source (i.e. any +characters in the range of 128--255) were supposed to load +\package{inputenc} and specify in which file encoding they were +written and stored. +% +If the \package{inputenc} package was not loaded then \LaTeX{} used a +``raw'' encoding which essentially took each byte from the input file +and typeset the glyph that happened to be in that position in the +current font---something that sometimes produces the right result but +often enough will not. + +In 1992 Ken Thompson and Rob Pike developed the UTF-8 encoding scheme +which enables the encoding of all Unicode characters within 8-bit sequences. +Over time this encoding has gradually taken over the world, +replacing the legacy 8-bit encodings used before. These days all major +computer operating systems use UTF-8 to store their files and it +requires some effort to explicitly store files in one of the legacy +encodings. + +As a result, whenever \LaTeX{} users want to use any accented +characters from their keyboard (instead of resorting to \verb=\"a= and +the like) they always have to use +\begin{verbatim} + \usepackage[utf8]{inputenc} +\end{verbatim} +in the preamble of their documents as otherwise \LaTeX{} will produce +gibberish. + +\subsection{The new default} + +With this release, the default encoding for \LaTeX\ files has been +changed from the ``fall through raw'' encoding to UTF-8 if used with +classic \TeX\ or \hologo{pdfTeX}. The implementation is essentially +the same as the existing UTF-8 support from +\verb|\usepackage[utf8]{inputenc}|. + +The \hologo{LuaTeX} and \hologo{XeTeX} engines always supported the +UTF-8 encoding as their native (and only) input encoding, so with +these engines \package{inputenc} was always a no-op. + +This means that with new documents one can assume UTF-8 input and it +is no longer required to always specify +\verb|\usepackage[utf8]{inputenc}|. But if this line is present it +will not hurt either. + + +\subsection{Compatibility} + +For most existing documents this change will be transparent: +\begin{itemize} +\item documents using only \acro{ascii} in the input file and + accessing accented characters via commands; +\item documents that specified the encoding of their file via an + option to the \package{inputenc} package and then used 8-bit + characters in that encoding; +\item documents that already had been stored in UTF-8 (whether or not + specifying this via \package{inputenc}). +\end{itemize} +Only documents that have been stored in a legacy encoding and used +accented letters from the keyboard \emph{without} loading +\package{inputenc} (relying on the similarities between the input used +and the T1 font encoding) are affected. + +These documents will now generate an error that they contain invalid +UTF-8 sequences. However, such documents may be easily processed by +adding the new command \verb|\UseRawInputEncoding| as the first line +of the file. This will re-instate the previous ``raw'' encoding +default. + +\verb|\UseRawInputEncoding| may also be used on the command line to +process existing files without requiring the file to be edited +\begin{verbatim} + pdflatex '\UseRawInputEncoding \input' file +\end{verbatim} +will process the file using the previous default encoding. + +Possible alternatives are reencoding the file to UTF-8 using a tool +(such as recode or iconv or an editor) or adding the line +\begin{flushleft} +\verb= \usepackage[=\meta{encoding}\verb=]{inputenc}= +\end{flushleft} +to the preamble specifying the \meta{encoding} that fits the file +encoding. In many cases this will be \texttt{latin1} or +\texttt{cp1252}. For other encoding names and their meaning see the +\package{inputenc} documentation. + +As usual, this change may also be reverted via the more general +\package{latexrelease} package mechanism, by speciying a release date +earlier than this release. + + +\subsection{BOM: byte order mark handling} + +When using Unicode the first bytes of a file may be a, so called, BOM +character (byte order mark) to indicate the byte oder used in the +file. While this is not required with UTF-8 encoded files (where the +byte order is known) it is nevertheless allowed by the standard and +some editors add that byte sequence to the beginning of a file. In the +past such files would have generated a ``Missing begin document'' +error or displayed strange characters when loaded at a later stage. + +With the addition of UTF-8 support to the kernel it is now possible to +identify and ignore such BOMs characters even before +\verb=\documentclass= so that these issues will no longer be showing +up. + + + +\section[A general rollback concept] + {A general rollback concept for packages and classes} + + In 2015 a rollback concept for the \LaTeX{} kernel was introduced. + Providing this feature allowed us to make corrections to the + software (which more or less didn't happen for nearly two decades) + while continuing to maintain backward compatibility to the highest + degree. + + In this release we have now extended this concept to + the world of packages and classes which was not covered + initially. As the classes and the extension packages have different + requirements compared to the kernel, the approach is different (and + simplified). This should make it easy for package developers to + apply it to their packages and authors to use when necessary. + + The documentation of this new feature is given in an article + submitted to TUGboat and also available from our + website~\cite{Mittelbach:TB39-2}. + + +\section[Integration of \pkg{remreset} and \pkg{chngcntr} packages] + {Integration of \pkg{remreset} and \pkg{chngcntr} packages + into the kernel} + +With the optional argument to \cs{newcounter} \LaTeX{} offers to +automatically reset counters when some counter is stepped, e.g., +stepping a \texttt{chapter} counter resets the \texttt{section} +counter (and recursively all other heading counters). However, what +was until now missing was a way to undo such a link between counters +or to link two counters after they have been defined. + +This can be now be done with \cs{counterwithin} and \cs{counterwithout}, +respectively. In the past one had to load the \pkg{chngcntr} package +for this. For the programming level we also added +\cs{@removefromreset} as the counterpart of the already existing +\cs{@addtoreset} command. Up to now this was offered by the +\pkg{remreset} package. + +\section{Testing for undefined commands} +\LaTeX\ packages often use a test \verb|\@ifundefined| to test if a command +is defined. Unfortunately this had the side effect of \emph{defining} +the command to \verb|\relax| in the case that it had no definition. + The new release uses a modified definition +(using extra testing possibilities available in \hologo{eTeX}. The new definition +is more natural, however code that was relying on the side effect of the +command being tested being defined if it was previously undefined may have to add +\verb|\let\|\meta{command}\verb|\relax|. + + +\section{Changes to packages in the tools category} + +\subsection{\LaTeX{} table columns with fixed widths} + +Frank published a short paper in +TUGboat~\cite{Mittelbach:TB38-2-213} on producing tables that have +columns with fixed widths. The outlined approach using column +specifiers ``\texttt{w}'' and ``\texttt{W}'' has now been integrated +into the \pkg{array} package. + +\subsection{Obscure overprinting with \pkg{multicol} fixed} + +A rather peculiar bug was reported on StackExchange for +\pkg{multicol}. If the column/page breaking was fully controlled by +the user (through \cs{columnbreak}) instead of letting the environment +do its job and if then more \cs{columnbreak} commands showed up on the +last page then the balancing algorithm was thrown off track. +As a result some parts of the columns did overprint each other. + +The fix required a redesign of the output routines used by +\pkg{multicol} and while it ``should'' be transparent in other cases +(and all tests in the regession test suite came out fine) there is the +off-chance that code that hooked into internals of \pkg{multicol} +needs adjustment. + + +\section{Changes to packages in the amsmath category} + +With this release of \LaTeX{} a few minor issues with \pkg{amsmath} +have been corrected. + +\subsection{Updated user's guide} + +Furthermore, \texttt{amsldoc.pdf}, the AMS user's +guide for the \pkg{amsmath} package~\cite{amsldoc}, has been updated +from version~2.0 to~2.1 to incorporate changes and corrections made +between 2016 and 2018. + + +\begin{thebibliography}{9} + +\bibitem{Mittelbach:TB39-1} Frank Mittelbach: + \emph{New rules for reporting bugs in the \LaTeX{} core software}. + In: TUGboat, 39\#1, 2018. + \url{https://www.latex-project.org/publications/} + +\bibitem{Mittelbach:Brno95} Frank Mittelbach: + \emph{\LaTeXe{} Encoding Interface --- Purpose, concepts, and + Open Problems}. + Talk given in Brno June 1995. + \url{https://www.latex-project.org/publications/} + +\bibitem{Mittelbach:TB39-2} Frank Mittelbach: + \emph{A rollback concept for packages and classes}. + Submitted to TUGboat. + \url{https://www.latex-project.org/publications/} + +\bibitem{Mittelbach:TB38-2-213} Frank Mittelbach: + \emph{\LaTeX{} table columns with fixed widths}. + In: TUGboat, 38\#2, 2017. + \url{https://www.latex-project.org/publications/} + +\bibitem{amsldoc} American Mathematical Society and The \LaTeX3 Project: + \emph{User's Guide for the \texttt{amsmath} package} (Version 2.1). + April 2018. + Available from + \url{https://www.ctan.org} + and distributed as part of every \LaTeX{} distribution. + +\end{thebibliography} + +\end{document} diff --git a/macros/latex-dev/doc/ltnews29.tex b/macros/latex-dev/doc/ltnews29.tex new file mode 100644 index 0000000000..1cc856aaed --- /dev/null +++ b/macros/latex-dev/doc/ltnews29.tex @@ -0,0 +1,526 @@ +% \iffalse meta-comment +% +% Copyright 2018 +% The LaTeX3 Project and any individual authors listed elsewhere +% in this file. +% +% This file is part of the LaTeX base system. +% ------------------------------------------- +% +% 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 +% 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 file has the LPPL maintenance status "maintained". +% +% The list of all files belonging to the LaTeX base distribution is +% given in the file `manifest.txt'. See also `legal.txt' for additional +% information. +% +% The list of derived (unpacked) files belonging to the distribution +% and covered by LPPL is defined by the unpacking scripts (with +% extension .ins) which are part of the distribution. +% +% \fi +% Filename: ltnews29.tex +% +% This is issue 29 of LaTeX News. + +\documentclass{ltnews} +\usepackage[T1]{fontenc} + +\usepackage{lmodern,url,hologo} + +\usepackage{csquotes} + +\providecommand\acro[1]{\textsc{#1}} +\providecommand\meta[1]{$\langle$\textit{#1}$\rangle$} + + +\providecommand\XeTeX{\hologo{XeTeX}} +\providecommand\LuaTeX{\hologo{LuaTeX}} +\providecommand\pdfTeX{\hologo{pdfTeX}} + +\newcommand\githubissue[2][]{\ifhmode\unskip\fi + \quad\penalty500\strut\nobreak\hfill + \mbox{\small\slshape(% + \href{https://github.com/latex3/latex2e/issues/\getfirstgithubissue#2 \relax}% + {github issue#1 #2}% + )}% + \par} + +% simple solution right now (just link to the first issue if there are more) +\def\getfirstgithubissue#1 #2\relax{#1} + +\newcommand\sxissue[1]{\ifhmode\unskip\fi + \quad\penalty500\strut\nobreak\hfill + \mbox{\small\slshape(\url{https://tex.stackexchange.com/#1})}\par} + +\let\cls\pkg +\newcommand\env[1]{\texttt{#1}} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\iffalse % only for TUB production +\usepackage{graphicx} +\makeatletter +% Xe\TeX{} requires reflecting the first E, hence we complain if the +% graphics package is not present. (For plain documents, this can be +% loaded via Eplain.) Also, at Barbara's suggestion, if the current +% font is slanted, we rotate by 180 instead of reflecting so there is at +% least a chance to look ok. (The magic values here seem more or less +% ok for \texttt{cmsl} and \texttt{cmti}.) +% +% \begin{macrocode} +\def\tubreflect#1{% + \@ifundefined{reflectbox}{% + \TBerror{A graphics package must be loaded for \string\XeTeX}% + }{% + \ifdim \fontdimen1\font>0pt + \raise 1.6ex \hbox{\kern.1em\rotatebox{180}{#1}}\kern-.1em + \else + \reflectbox{#1}% + \fi + }% +} +\def\tubhideheight#1{\setbox0=\hbox{#1}\ht0=0pt \dp0=0pt \box0 } +\def\XekernbeforeE{-.125em} +\def\XekernafterE{-.1667em} +\DeclareRobustCommand{\Xe}{\leavevmode + \tubhideheight{\hbox{X% + \setbox0=\hbox{\TeX}\setbox1=\hbox{E}% + \ifdim \fontdimen1\font>0pt \def\XekernbeforeE{0em}\fi + \lower\dp0\hbox{\raise\dp1\hbox{\kern\XekernbeforeE\tubreflect{E}}}% + \kern\XekernafterE}}} +\def\XeTeX{\Xe\TeX} +\def\XeLaTeX{\Xe{\kern.11em \LaTeX}} +\fi +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\publicationmonth{December} +\publicationyear{2018} + +\publicationissue{29} + +\begin{document} + +%\addtolength\textheight{4.2pc} % only for TUB + +\maketitle +\tableofcontents + +\setlength\rightskip{0pt plus 3em} + +\bigskip + +\section{Introduction} + +The December 2018 release of \LaTeX{} is a maintenance release in +which we have fixed a few bugs in the software: some are old, some +newer, and they are mostly rather obscure. + +\section[Bug reports for core \LaTeXe{} and packages] + {Bug reports for core \LaTeXe{} and packages maintained by the Project Team} + +In Spring 2018 we established a new issue tracking system +(Github issues at \url{https://github.com/latex3/latex2e/issues}) for both +the \LaTeX{} core and the packages maintained by the +\LaTeX{} Project Team, with an updated procedure for how to report a +bug or problem. + +Initial experience with this system is good, with people who report +problems following the guidelines and including helpful working +examples to show the problem---thanks for doing this. + +The detailed requirements and the workflow for reporting a bug in the +core \LaTeX{} software is documented at +\begin{quote} +\url{https://www.latex-project.org/bugs/} +\end{quote} +with further details and discussion in~\cite{29:Mittelbach:TB39-1}. + + +\section{Changes to the \LaTeX{} kernel} + +\subsection{UTF-8:\ updates to the default input encoding} + +In the April 2018 release of \LaTeX{} we changed the default encoding +from 7-bit \acro{ascii} to \acro{utf}-8 when using classic \TeX\ or +\hologo{pdfTeX}; see \textit{\LaTeX{} News~28}~\cite{29:ltnews28} for +details. + +Now, after half a year of experience with +this new default, +we have +made a small number of adjustments to further improve the user experience. +These include: +\begin{itemize} +\item + Some improvements when displaying error messages about \acro{utf}-8 + characters that have not been set up for use with \LaTeX{}, + or are invalid for some other reason; +% +\githubissue[s]{60, 62 and 63} +% +\item + The addition of a number of previously missing declarations for + characters that are in fact available with the default fonts, e.g., + \cs{j} \enquote{\j} (0237), \cs{SS} \enquote{\SS} (1E9E), + \verb=\k{}= \enquote{\k{ }} (02DB) and \verb=\.{}= \enquote{\.{ }} + (02D9); +\item + Correcting the names for \cs{guillemetleft} + \enquote{\guillemotleft} and \cs{guillemetright} + \enquote{\guillemotright} in all encoding files. These correct + names are in addition to the old (but wrong) Adobe names: Adobe + mistakenly called them Guillemot, which is a sea bird. +% + \githubissue{65} +% +\item + Added \cs{Hwithstroke} (\enquote{\Hwithstroke}) and \cs{hwithstroke} + (\enquote{\hwithstroke}) necessary for typesetting Maltese. +% + \sxissue{q/460110} +\end{itemize} + + + +\subsection{Fixed \cs{verb*} and friends in \texorpdfstring{\XeTeX}{XeTeX} and \LuaTeX{}} + + +The original \cs{verb*} and \texttt{verbatim*} in \LaTeX{} were coded +under the assumption that the position of the space character (i.e., +\acro{ascii} 32) in a typewriter font contains a visible space glyph +``\verb*= =''. This is correct for \pdfTeX{} with the most used font +encodings \texttt{OT1} and \texttt{T1}. However, this unfortunately +does not work for Unicode engines using the \texttt{TU} encoding since +the space character slot (\acro{ascii} 32) then usually contains a real +(normal) space, which has the effect that \cs{verb*} produces the same +results as \cs{verb}. + +The \cs{verb*} code now always uses the newly introduced command +\cs{verbvisiblespace} to produce the visible space character and this +command will get appropriate definitions for use with the different +engines. With \pdfTeX{} it will simply use \cs{asciispace}, which is +a posh name for ``select character 32 in the current font'', but with +Unicode engines the default definition is +\begin{verbatim} + \DeclareRobustCommand\verbvisiblespace + {\leavevmode + {\usefont{OT1}{cmtt}{m}{n}\asciispace}} +\end{verbatim} +which uses the visible space from the font Computer Modern Typewriter, +regardless of the currently chosen typewriter font. Internally the +code ensures that the character used has exactly the same width as the +other characters in the current (monospaced) font; thus, for example, +code displays line up properly. + +It is possible to redefine this command to select your own character, +for example +\begin{verbatim} + \DeclareRobustCommand\verbvisiblespace + {\textvisiblespace} +\end{verbatim} +will select the the ``official'' visible space character of the +current font. This may look like the natural default, but it wasn't +chosen as our default because many fonts just don't have that Unicode +character, or they have one with a strange shape. +% +\githubissue[s]{69 and 70} + + +\subsection{Error message corrected} +Trying to redefine an undefined command could in a few cases generate +an error message with a missing space, e.g., +\verb=\renewcommand\1{...}= gave +\begin{verbatim} + LaTeX Error: \1undefined. +\end{verbatim} +This is now fixed. +% +\githubissue{41} + + +\subsection{Fixed fatal link error with \pkg{hyperref}} + +If an \cs{href} link text gets broken across pages, \pdfTeX{} and +\LuaTeX{} will generate a fatal error unless both parts of the link +are internally at the same boxing level. In two-column mode that was +not the case if one of the pages had spanning top floats. This has now +been changed so that the error is avoided. +% +\githubissue{94} + + +\subsection{Avoid page breaks caused by invisible commands} + +Commands like \cs{label} or \cs{index} could generate a potential page +break in places where a page break was otherwise prohibited, e.g., +when used between two consecutive headings. This has now been +corrected. If for some reason you really want a break and you relied +on this faulty behavior, you can always add one using \cs{pagebreak}, +with or without an optional argument. +% +\githubissue{81} + + + +\subsection{Prevent spurious spaces when reading table of contents data} + +When table of contents data is read in from a \texttt{.toc} file, the +new-line character at the end of each line is converted by \TeX{} to a +space. In normal processing this is harmless (as \TeX{} is doing this +input reading whilst in vertical mode and each line in the file +represents a single line (paragraph) in the table of contents. If, +however, this is done in horizontal mode, which is sometimes the case, +then these spaces will appear in the output. If you then omit some of +the input lines (e.g., because you do not display \acro{toc} data below a +certain level), then these spaces accumulate in the typeset output and +you get surprising, and unwanted, gaps inside the text. + +The new code now adds a \texttt{\%} sign at the end of problematic +lines in the \texttt{.toc} file so that \TeX{} will not generate such +spaces that may survive to spoil the printed result. As some third +party packages have augmented or changed the core \LaTeX{} +functionality in that area (for example, by adding additional +arguments to the commands in \acro{toc} files) the code uses a conservative +approach and the \texttt{\%} signs are added only when certain +conditions are met. Therefore some packages might require updates if +they want to benefit from this correction, especially if they +unconditionally overwrite \LaTeX{}'s \cs{addcontentsline} definition. +% +\githubissue{73} + + +\subsection{Prevent protrusion in table of contents lines} + +In \TeX{}'s internal processing model, +paragraph data is one of the +major data structures. As a result, +many things are internally modeled +as paragraphs even if they are not conceptually +``text paragraphs'' in +the traditional sense. +In a few cases this has some surprising effects +that are not always +for the better. One example is +standard \acro{toc} entries, +where you have +heading data followed by some dot leaders and a page +number at the right, produced, for example, from this: +\begin{quote} + \contentsline {subsection}{Error message corrected}{2}{section*.7} +\end{quote} +The space reserved for the page number is of a fixed width, so that +the dots always end in the same place. Well, they did end in the same +place until the advent of protrusion support in the \TeX{} engines. +Now, with the \pkg{microtype} package loaded, it is possible that the +page number will protrude slightly into the margin (even though it’s +typeset inside a box) and as a result this page number box gets +shifted. With enough bad luck this can get you another dot in the +line, sticking out like the proverbial sore thumb, as exhibited in the +question on StackExchange that triggered the correction. + +\LaTeX{} now takes care that there will be no protrusion happening on +such lines, even if it is generally enabled for the whole document. +% +\sxissue{q/172785} + + + +\subsection{Start L-R mode for \cs{thinspace} and friends} + +In \LaTeX{}, commands that are intended only for paragraph (L-R) mode +are generally careful to start paragraph mode if necessary; thus they +can be used at the start of a paragraph without surprising and +unwanted consequences. This important requirement had been overlooked +for a few horizontal spacing commands, such as \cs{thinspace} +(a.k.a.\ ``\cs{,}''), and for some other support commands such as +\cs{smash} or \cs{phantom}. Thus they ended up adding vertical space +when used at the beginning of a paragraph or, in the case of +\cs{smash}, creating a paragraph of their own. This has now been +corrected, and a corresponding update has been made to the +\pkg{amsmath} package, in which these commands are also defined. +% +\githubissue[s]{49 and 50} + + + +\subsection{Guarding \cs{pfill} in \pkg{doc}} + +For presenting index entries pointing to +code fragments and the like, +the \pkg{doc} package has a \cs{pfill} command that +generates within the index a line of dots leading from +the command name to the page or code line numbers. +If necessary it would automatically split the entry +over two lines. That worked well enough for a quarter century, but we +discovered recently that it is broken inside +the \cls{ltugboat} class, +where it sometimes produces +bad spacing within continuation lines. + +The reason turned out to be a redefinition of the \LaTeX{} command +\cs{nobreakspace} (\verb=~=) inside the class \cls{ltugboat}, which +removed any preceding space (and thus unfortunately also removed the +dots on the continuation line). While one can argue that this is a +questionable redefinition (if only done by a single class and not generally), +it has been in the class so long that changing it would +certainly break older documents. So instead we now guard against that +removal of space. +% +\githubissue[s]{25 and 75} + + + + + +\section{Changes to packages in the \pkg{tools} category} + +\subsection{Sometimes the \pkg{trace} package turned off too much} + +The \pkg{trace} package is a useful little tool for tracing macro +execution: it hides certain lengthy and typically uninteresting +expansions resulting from font changes and similar activities. +However, it had the problem that it also reset other tracing settings +such as \cs{showoutput} in such situations, so that you couldn't use +\cs{showoutput} in the preamble to get symbolic output of all the +pages in the document. This has now been corrected. + + + + +\subsection{Update to \pkg{xr}} + +The \pkg{xr} package has been updated so that the code that reads the +\texttt{.aux} file has been made more robust. It now correctly +ignores conditionals (added by \pkg{hyperref} and other packages) +rather than generating low level parsing errors. +\sxissue{a/452321} + + +\subsection{Column data for \env{multicols*} sometimes vanished} + +In certain situations involving \env{multicols*}, when there are more +explicit \cs{columnbreak} requests than there are columns on the +current page, data could vanish due to the removal of an internal +penalty marking the end of the environment. This has been corrected by +explicitly reinserting that penalty if necessary. +% +\githubissue{53} + +\subsection{Extension to \cs{docolaction} in \pkg{multicol}} + +The \cs{docolaction} command can be used to carry out actions +depending on the column you are currently in, i.e., first, any inner +one (if more than two) or last. However, if the action generates text +then there is the question: is this text part of the current column or +the one after? That is, on the next run, do we test before or after it, +to determine in which column we are? + +This is now resolved as follows: if you use \cs{docolaction*} any +generated text by the chosen action is considered to be after the test +point. But if you use the command without the star then all the material +it generates will be placed before the test point to determine the +current column, i.e., the text will become part of the current column +and may affect the test result on the next run. + + + +\subsection{Prevent color leak in \pkg{array}} + +In some cases the color used inside a \env{tabular} cell could ``leak +out'' into the surrounding text. This has been corrected. +% +\githubissue{72} + +\subsection{Support fragile commands in \texttt{array} or \texttt{tabular} column templates} + +The preamble specifiers \texttt{p}, \texttt{m} and \texttt{b} each receives +a user supplied argument: the width of the paragraph column. Normally +that is something harmless, like a length or a simple length +expression. But in more complicated settings involving the \pkg{calc} +package it could break with a low-level error message. This has now +been corrected. +% +\sxissue{q/459285} + + + +\section{Changes to packages in the amsmath category} + +The changes in the kernel made for \cs{thinspace}, \cs{smash}, +etc.\ (see above) have been reflected in the \pkg{amsmath} package +code, so that loading this package doesn't revert them. +% +\githubissue[s]{49 and 50} + + + + + +\section{Website updates} + +\subsection{Publications area reorganized and extended} + +To help readers to find relevant information in more convenient and +easy ways, the area of the website covering publications by the +\LaTeX{} Project Team was reorganized and extended (many more +abstracts added). We now provide the articles, talks and supplementary +data structured both by year and also by major +topics~\cite{29:site-pub}. Feel free to take a look. + +\subsection{Japanese translations of the user's guide} + +Yukitoshi Fujimura has kindly translated +into Japanese two documents that are +distributed with standard \LaTeX{}. +These are: +\begin{itemize} +\item + \LaTeXe{} for authors; +\item + User's Guide for the \pkg{amsmath}~Package~\cite{29:amsldoc}. +\end{itemize} +They can be found on the website documentation page~\cite{29:site-doc}. +You will now also find there a typeset version of the full \LaTeXe{} +source code (with index etc.\@) and a number of other goodies. + + + + +\begin{thebibliography}{9} + +\bibitem{29:Mittelbach:TB39-1} Frank Mittelbach: + \emph{New rules for reporting bugs in the \LaTeX{} core software}. + In: TUGboat, 39\#1, 2018. + \url{https://latex-project.org/publications/} + +\bibitem{29:ltnews28} + \emph{\LaTeX{} News, Issue 28}. + In: TUGboat, 39\#1, 2018.\\ + \rlap{\url{https://latex-project.org/news/latex2e-news/}} + +\bibitem{29:site-doc} + \emph{\LaTeX{} documentation on the \LaTeX{} Project Website}.\\ + \url{https://latex-project.org/documentation/} + +\bibitem{29:site-pub} + \emph{\LaTeX{} Project publications on the \LaTeX{} Project Website}.\\ + \url{https://latex-project.org/publications/} + +\bibitem{29:amsldoc} American Mathematical Society and The \LaTeX3 Project: + \emph{User's Guide for the \texttt{amsmath} Package} (Version 2.1). + April 2018. + Available from + \url{https://www.ctan.org} + and distributed as part of every \LaTeX{} distribution. + +\end{thebibliography} + +\end{document} + diff --git a/macros/latex-dev/doc/ltnews30.tex b/macros/latex-dev/doc/ltnews30.tex new file mode 100644 index 0000000000..7b4b282cc9 --- /dev/null +++ b/macros/latex-dev/doc/ltnews30.tex @@ -0,0 +1,297 @@ +% \iffalse meta-comment +% +% Copyright 2019 +% The LaTeX3 Project and any individual authors listed elsewhere +% in this file. +% +% This file is part of the LaTeX base system. +% ------------------------------------------- +% +% 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 +% 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 file has the LPPL maintenance status "maintained". +% +% The list of all files belonging to the LaTeX base distribution is +% given in the file `manifest.txt'. See also `legal.txt' for additional +% information. +% +% The list of derived (unpacked) files belonging to the distribution +% and covered by LPPL is defined by the unpacking scripts (with +% extension .ins) which are part of the distribution. +% +% \fi +% Filename: ltnews30.tex +% +% This is issue 30 of LaTeX News. + +\documentclass{ltnews} +\usepackage[T1]{fontenc} + +\usepackage{lmodern,url,hologo} + +\usepackage{csquotes} + +\providecommand\acro[1]{\textsc{#1}} +\providecommand\meta[1]{$\langle$\textit{#1}$\rangle$} + + +\providecommand\XeTeX{\hologo{XeTeX}} +\providecommand\LuaTeX{\hologo{LuaTeX}} +\providecommand\pdfTeX{\hologo{pdfTeX}} + +\providecommand\githubissue[2][]{\ifhmode\unskip\fi + \quad\penalty500\strut\nobreak\hfill + \mbox{\small\slshape(% + \href{https://github.com/latex3/latex2e/issues/\getfirstgithubissue#2 \relax}% + {github issue#1 #2}% + )}% + \par} + +% simple solution right now (just link to the first issue if there are more) +\def\getfirstgithubissue#1 #2\relax{#1} + +\providecommand\sxissue[1]{\ifhmode\unskip\fi + \quad\penalty500\strut\nobreak\hfill + \mbox{\small\slshape(\url{https://tex.stackexchange.com/#1})}\par} + +\providecommand\gnatsissue[2]{\ifhmode\unskip\fi + \quad\penalty500\strut\nobreak\hfill + \mbox{\small\slshape(% + \href{https://www.latex-project.org/cgi-bin/ltxbugs2html?pr=#1\%2F#2}% + {gnats issue #1/#2}% + )}% + \par} + +\let\cls\pkg +\providecommand\env[1]{\texttt{#1}} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\iffalse % only for TUB production +\usepackage{graphicx} +\makeatletter +% Xe\TeX{} requires reflecting the first E, hence we complain if the +% graphics package is not present. (For plain documents, this can be +% loaded via Eplain.) Also, at Barbara's suggestion, if the current +% font is slanted, we rotate by 180 instead of reflecting so there is at +% least a chance to look ok. (The magic values here seem more or less +% ok for \texttt{cmsl} and \texttt{cmti}.) +% +% \begin{macrocode} +\def\tubreflect#1{% + \@ifundefined{reflectbox}{% + \TBerror{A graphics package must be loaded for \string\XeTeX}% + }{% + \ifdim \fontdimen1\font>0pt + \raise 1.6ex \hbox{\kern.1em\rotatebox{180}{#1}}\kern-.1em + \else + \reflectbox{#1}% + \fi + }% +} +\def\tubhideheight#1{\setbox0=\hbox{#1}\ht0=0pt \dp0=0pt \box0 } +\def\XekernbeforeE{-.125em} +\def\XekernafterE{-.1667em} +\DeclareRobustCommand{\Xe}{\leavevmode + \tubhideheight{\hbox{X% + \setbox0=\hbox{\TeX}\setbox1=\hbox{E}% + \ifdim \fontdimen1\font>0pt \def\XekernbeforeE{0em}\fi + \lower\dp0\hbox{\raise\dp1\hbox{\kern\XekernbeforeE\tubreflect{E}}}% + \kern\XekernafterE}}} +\def\XeTeX{\Xe\TeX} +\def\XeLaTeX{\Xe{\kern.11em \LaTeX}} +\fi +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\publicationmonth{Pre-release Version --- unfinished} +\publicationyear{2019} + +\publicationissue{30} + +\begin{document} + +%\addtolength\textheight{4.2pc} % only for TUB + +\maketitle +\tableofcontents + +\setlength\rightskip{0pt plus 3em} + +\bigskip + +\section{Introduction} + +This document is under construction \ldots + + +\section{Improving Unicode handling in \pdfTeX{}} + +The perhaps most important improvement in this release is an even +better support for UTF-8 characters when using \pdfTeX{}.\footnote{The + Japanese engines e-p\TeX{} and e-up\TeX{} can't use these features + yet as they don't support the primitive \cs{ifincsname}. Work is + under way to resolve this in the engines.} + +In Unicode engines any Unicode character (that is not acting as a +command, i.e., is \enquote{active}) can be used as part of the +\cs{label}/\cs{ref} mechanism or can be displayed in a message or +written to a file. In 8-bit engines, however, this was severely +restricted, essentially you had to limit yourself to using +\acro{ascii} letters, digits and a few punctuation symbols. With the +new release most of these restrictions have been removed and you now +can write labels such as +\begin{verbatim} + \label{eq:größer} +\end{verbatim} +or use accented characters, etc.\ as part of a \cs{typeout} message. +The only requirement remaining is that only those UTF-8 characters +that are also available for typesetting can be used, i.e., only those +which which adequate font support is loaded. Otherwise you will get an +error message stating that a particular Unicode character is not set +up for use with \LaTeX{}. + +What is not possible with an 8-bit engine such as \pdfTeX{} is to use +characters other than \acro{ascii} letters as part of a command +name. This is due to the fact that all other characters in such +engines are not single character tokens, but in fact consist of a +sequence of bytes and this is not supported in command names. + +\section{Improving file name handling in \pdfTeX{}} + +A related change is that file names used as part of \cs{input}, \cs{includegraphics}, etc.\ can now contain Unicode characters as well as spaces. In this case even characters that can't be typeset because of missing font support can be used. + + + + +\section{Other changes to the \LaTeX{} kernel} + + +\subsection{Guard against \cs{unskip} at the start of a tabular cell} + +If a \env{tabular} or \env{array} cell started with command that +issued an \cs{unskip} as its first action centering the column got +broken because the space on the left got removed. This got corrected +by adding a minuscule additional space after the stretching space that +could be safely removed in such a case without being noticeable. + +This change was also applied in the \pkg{array} package. + +\githubissue{102} + + +\subsection{Fixes to Unicode table data} + +\texttt{U+012F} which is \enquote{i with ogonek} should produce an +\enquote{i} and not a\enquote{dotless i}. This has been corrected. + +\githubissue{122} + +The Unicode slots \texttt{27E8} and \texttt{27E9} have been mapped to +\cs{textlangle} and \cs{textrangle} which is the recommended mapping. + +\githubissue{110} + +When doing cut-and-paste from other documents f-ligatures might show +up as Unicode characters. In the past those got rejected. We now +translate them back to individual characters so that they get +accepted. If supported by the font (which is normally the case) they +are then reconstructed as ligatures and thus come out as +desired. Otherwise they will come out as individual characters which +is fine too. + +\githubissue{154} + + +\subsection{Improve \cs{InputIfFileExists}'s handling of file names} + +In rare circumstances it was possible that \cs{InputIfFileExists} +would work incorrectly, e.g., a construction such as +\begin{verbatim} +\InputIfFileExists{foo}{\input{bar}}{} +\end{verbatim} +Would not load the files \texttt{foo.tex} and \texttt{bar.tex} but +would load \texttt{foo.tex} twice. This has been corrected. + +\githubissue{109} + + +\subsection{Improve wording of a warning message} + +\emph{write} + +\githubissue{107} + + +\subsection{Avoid \cs{DeclareErrorFont} side effects} + +\emph{write} + +\gnatsissue{latex}{4399} + + + +\subsection{\pkg{nfssfont}: Generate a font table as the default action} + +With the small file \texttt{nfssfont.tex} it is possible to produce +font tables and other font tests in the style set up by Don Knuth. As +in nearly all cases producing a font table is the desired action this +action has been made the default so that one can simply hit enter +instead of having to write \verb=\table\bye=. + + + + + + +\section{Changes to packages in the \pkg{tools} category} + +\subsection{\pkg{multicol}: Introduce \texttt{minrows} counter for balancing} + +When there are only a few lines of text on a page at the end of a +\env{multicols} environment balancing them looks rather odd, e.g., if +you then end up with three columns each containing a single line. This +can now be controlled through the counter \texttt{minrows} (default is +1) which requires at least that many lines in the first column during +balancing. Thus, if you set it to \texttt{2} one would get a +distribution of \texttt{2+1+0} lines and if set it to three, the result +would have been \texttt{3+0+0} instead of the default \texttt{1+1+1}. + +What is most appropriate really depends on the circumstances, but this +now gives you the tools to make local or global adjustments. + + + +\section{Changes to packages in the \pkg{amsmath} category} + +\subsection{\pkg{amsmath}: Introduce \texttt{overunderset} command} + +\emph{describe} + + + +\section{Documentation updates} + +\subsection{High-lighting the standard NFSS codes for series} + +\emph{describe} + + +\begin{thebibliography}{9} + +\bibitem{29:site-doc} + \emph{\LaTeX{} documentation on the \LaTeX{} Project Website}.\\ + \url{https://latex-project.org/documentation/} + +\bibitem{29:site-pub} + \emph{\LaTeX{} Project publications on the \LaTeX{} Project Website}.\\ + \url{https://latex-project.org/publications/} + +\end{thebibliography} + +\end{document} + diff --git a/macros/latex-dev/doc/ltx3info.pdf b/macros/latex-dev/doc/ltx3info.pdf new file mode 100644 index 0000000000..2f80af9747 Binary files /dev/null and b/macros/latex-dev/doc/ltx3info.pdf differ diff --git a/macros/latex-dev/doc/ltx3info.tex b/macros/latex-dev/doc/ltx3info.tex new file mode 100644 index 0000000000..e0aabafba4 --- /dev/null +++ b/macros/latex-dev/doc/ltx3info.tex @@ -0,0 +1,474 @@ +% \iffalse meta-comment +% +% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 +% The LaTeX3 Project and any individual authors listed elsewhere +% in this file. +% +% This file is part of the LaTeX base system. +% ------------------------------------------- +% +% 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 +% 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 file has the LPPL maintenance status "maintained". +% +% The list of all files belonging to the LaTeX base distribution is +% given in the file `manifest.txt'. See also `legal.txt' for additional +% information. +% +% The list of derived (unpacked) files belonging to the distribution +% and covered by LPPL is defined by the unpacking scripts (with +% extension .ins) which are part of the distribution. +% +% \fi +\documentclass[a4paper]{article} + +% Commands and environments: + +\newcommand{\eg}{e.g.~} +\newcommand{\ie}{i.e.~} + + +\newenvironment{citations}{% + \list{}{% + \renewcommand{\makelabel}[1]{\normalfont\itshape ##1}% + }% +}{% + \endlist +} + +% Some logos: + +\newcommand{\NFSS}{NFSS} + +\newcommand{\LaTeXNews}{\LaTeX~News} + +\newcommand{\AW}{Addison Wesley} + +\newcommand{\SGML}{{\sc SGML}} +\newcommand{\DSSSL}{{\sc DSSSL}} +\newcommand{\HTML}{{\sc HTML}} +\newcommand{\XML}{{\sc XML}} +\newcommand{\PDF}{{\sc PDF}} + +\newcommand{\PS}{{\sc Post\-Script}} + +\newcommand{\AmSTeX}{$\mathcal A$\lower.4ex\hbox{$\!\mathcal + M\!$}$\mathcal S$-\TeX} +\newcommand{\AmSLaTeX}{$\mathcal A$\lower.4ex\hbox{$\!\mathcal + M\!$}$\mathcal S$-\LaTeX} +\newcommand{\MF}{{\sc Meta\-font}} + +% sections + +\setcounter{secnumdepth}{-2} + +% Front matter: + +\title{\Large The \LaTeX3 Project} + +\author{\copyright 1995--1999 \ +Frank Mittelbach and +Chris Rowley} + +\date{12 January 1999} + +\begin{document} + +\thispagestyle{empty} + +\maketitle + +\begin{abstract} + This article describes the motivation, achievements and future of + the \LaTeX3 Project, which was established to produce a new version + of \LaTeX{}, the widely-used and highly-acclaimed document + preparation system. It also describes how you can help us to + achieve our aims.\\[2pt] + \textbf{For Archive maintainers, Authors, Publishers and + Distributors:}\\ + The project team request that, whenever possible, you include this + article in any of the following: + \begin{itemize} + \item Books about \TeX{} and \LaTeX{}. + \item Instructions for authors on using \LaTeX{}. + \item The printed documentation of CD-ROM collections that contain + \LaTeX. + \item On-line collections that include a significant proportion of + documents encoded in \LaTeX. +\end{itemize} +\end{abstract} + +\section{Outline} + +The purposes of the \LaTeX3 system can be summarized thus: it will +greatly increase the range of documents which can be processed; and it +will provide a flexible interface for typographic designers to easily +specify the formatting of a class of documents. + +The \LaTeX3 Project Team is a small group of volunteers whose aim is +to produce this major new document processing system based on the +principles pioneered by Leslie Lamport in the current \LaTeX. + +The major visible work of the team before 1997 was the development of +the current \emph{standard} version of \LaTeX{}. This was first +released in 1994 and has since then been actively maintained and +enhanced by extensions to that core system. They will continue to +develop and maintain this system, releasing updated versions every six +months and recording these activities in the \LaTeX{} bugs database +(see below). + +Although \LaTeX{} may be distributed freely, the production and +maintenance of the system does require expenditure of reasonably large +sums of money. The \LaTeX3 Project Fund has therefore been set up to +channel money into this work. We know that some users are +aware of this fund as they have already contributed to it---many +thanks to all of them! If you want to know more about how you can +help the project, see Page \pageref{fund}---and thanks in advance for +your generosity in the future. + + +\section{Background} + +With \TeX{}, Knuth designed a formatting system that is able to +produce a large range of documents typeset to extremely high quality +standards. For various reasons (\eg quality, portability, stability +and availability) \TeX{} spread very rapidly and can nowadays be best +described as a world-wide de facto standard for high quality +typesetting. Its use is particularly common in specialized areas, such +as technical documents of various kinds, and for multi-lingual +requirements. + +The \TeX{} system is fully programmable. This allows the development +of high-level user interfaces whose input is processed by \TeX{}'s +interpreter to produce low-level typesetting instructions; these are +input to \TeX{}'s typesetting engine which outputs the format of each +page in a device-independent page-description language. The \LaTeX{} +system is such an interface; it was designed to support the needs of +long documents such as textbooks and manuals. It separates content and +form as much as possible by providing the user with a generic (\ie +logical rather than visual) mark-up interface; this is combined with +style sheets which specify the formatting. + +Recent years have shown that the concepts and approach of \LaTeX{} are +now widely accepted. Indeed, \LaTeX{} has become the standard method +of communicating and publishing documents in many academic +disciplines. This has led to many publishers accepting \LaTeX{} +source for articles and books; and the American Mathematical Society +now provides a \LaTeX{} package making the features of \AmSTeX{} +available to all users of \LaTeX{}. Its use has also spread into many +other commercial and industrial environments, where the technical +qualities of \TeX{} together with the concepts of \LaTeX{} are +considered a powerful combination of great importance to such areas as +corporate documentation and publishing. This has also extended to +on-line publishing using, for example, \PDF{} output incorporating +hypertext and other active areas. + +With the spreading use of \SGML{}-compliant systems (\eg Web-based +publishing using \HTML{} or \XML{}) \TeX{} again is a common choice as +the formatting engine for high quality typeset output: a widely used +such system is {\em The Publisher\/} from ArborText, whilst a more +recent development is the object-oriented document editor Grif. The +latter is used for document processing in a wide range of industrial +applications; it has also been adopted by the Euromath consortium as +the basis of their mathematician's workbench, one of the most advanced +of the emerging project-oriented user environments. Typeset output +from \SGML{}-coded documents in these systems is obtained by +translation into \LaTeX{}, which will therefore soon also be a natural +choice for the output of \DSSSL-compliant systems. + +Because a typical \SGML{} Document Type Definition (DTD) uses concepts +similar to those of \LaTeX{}, the formatting is often implemented by +simply mapping document elements to \LaTeX{} constructs rather than +directly to `raw \TeX'. +This enables the +sophisticated analytical techniques built into the \LaTeX{} +software to be exploited; and it avoids the need to program in \TeX{}. + +\section{Motivation} + +This increase in the range of applications of \LaTeX{} has highlighted +certain limitations of the current system, both for authors of +documents and for designers of formatting styles. + +In addition to the need to extend the variety of classes of document +which can be processed by \LaTeX{}, substantial enhancements are +necessary in, at least, the following areas: + \begin{itemize} + \item + the command syntax (attributes, short references, etc); + \item + the layout specification interface (style design); + \item + the level of robustness (error recovery, omitted tags); + \item + the extendibility (package interface); + \item + the layout specification of tabular material; + \item + the specification and inclusion of graphical material; + \item + the positioning of floating material, and other aspects of page + layout; + \item + the requirements of hypertext systems. + \end{itemize} + + Further analysis of these deficiencies has shown that some of the + problems are to be found in \LaTeX{}'s internal concepts and design. + This project to produce a new version therefore involves thorough + research into the challenges posed by new applications and by the use + of \LaTeX{} as a formatter for a wide range of documents, \eg \SGML{} + documents; on-line \PDF{} documents with hypertext links. + + This will result in a major re-implementation of large parts of the + system. Some of the results of such rethinking of the fundamentals + are already available in Standard \LaTeX{}, notably in the following + areas: + +\begin{itemize} +\item Font declaration and selection; +\item Font and glyph handling within mathematical formulas; +\item Handling multiple font glyph encodings within a document; +\item Allowing multiple input character encodings within a document; +\item A uniform interface for graphics inclusion; +\item Support for coloured text; +\item Building and interfacing new classes and extension packages. +\end{itemize} + + +\section{Description} + +The strengths of the present version of \LaTeX{} are +as follows: + \begin{itemize} + \item excellent standard of typesetting for text, technical +formulas\\ +and tabular material; + \item separation of generic mark-up from visual formatting; + \item ease of use for authors; + \item portability of documents over a wide range of platforms; + \item adaptability to many languages; + \item widespread and free availability; + \item reliable support and maintenance by the \LaTeX3 project team. + \end{itemize} + These will be preserved and in many cases greatly enhanced by the new + version which is being developed to fulfill the following requirements. + \begin{itemize} + \item + It will provide a syntax that allows highly automated translation + from popular \SGML{} DTDs into \LaTeX{} document classes (these + will be provided as standard with the new version). + + The syntax of the new \LaTeX{} user-interface will, for example, + support the \SGML{} concepts of `entity', `attribute' and `short + reference' in such a way that these can be directly linked to the + corresponding \SGML{} features. + + \item + It will support hypertext links and other features required for + on-line structured documents using, for example, \HTML{} and \XML{}. + +\item + It will provide a straightforward style-designer interface to support + both the specification of a wide variety of typographic requirements + and the linking of entities in the generic mark-up of a document to + the desired formatting. These two parts of the design process will + be clearly separated so that it is possible to specify different + layouts for the same DTD. + + The language and syntax of this interface will be as natural as + possible for a typographic designer. As a result, this language + could easily be interfaced to a visually-oriented, menu-driven + specification system. + + This interface will also support \DSSSL{} specifications and + style-sheet concepts such as those used with \HTML{} and \XML{}. + + \item + It will provide an enhanced user-interface that allows expression of + the typesetting requirements from a large range of subject areas. Some + examples are listed here. + + \begin{itemize} + \item The requirements of technical documentation (\eg offset layout,\\ + change bars, etc). + \item The requirements of academic publishing in the humanities\\ + (critical text editions, etc). + \item The requirements of structural formulas in chemistry. + \item Advanced use of the mathematical-typesetting features of \TeX{}. + \item The integration of graphical features, such as shading, + within text. + \item the integration of hypertext and other links in on-line + documents using systems such as \HTML{}, \XML{} and \PDF{}. + + \end{itemize} + + Special care will be taken to ensure that this interface is + extensible: this will be achieved by use of modular designs. + + + \item + It will provide a more robust author-interface. For example, + artificial restrictions on the nesting of commands will be removed. + Error handling will be improved by adding + a more effective, interactive help system. + + \item + It will provide access to arbitrary fonts from any family (such as + the \PS{} and TrueType fonts) including a wide range of fonts for + multi-lingual documents and the specialist glyphs required by + documents in various technical and academic areas. + + \item + The new interfaces will be documented in detail and the + system will provide extensive catalogues of examples, carefully + designed to make the learning time for new users (both designers and + authors) as short as possible. + + \item + The code itself will be thoroughly documented and it will be + designed on modular principles. Thus the system will be easy to + maintain and to enhance. +\end{itemize} + +The resulting new \LaTeX{} will, like the present version, be usable +with any standard \TeX{} system (or whatever replaces it) and so will +be freely available on a wide range of platforms. + + +\section{\LaTeX{} documentation} + +\begingroup +\setlength{\parindent}{0pt} + +A complete description of Standard \LaTeX{} can be found in: +\begin{citations} +\item[\LaTeX: A Document Preparation System] + Leslie Lamport,\\ \AW, 2nd ed, 1994. +\item[The \LaTeX{} Companion] + Mittelbach, Goossens with Braams, Carlisle and Rowley,\\ \AW, 2nd ed, 2004. +\end{citations} + +A recent addition to the publications closely associated with the +project is: +\begin{citations} +\item[The \LaTeX{} Graphics Companion] + Goossens, Mittelbach and Rahtz,\\ \AW, 1997. +\end{citations} + +This \LaTeX{} distribution comes with documentation on several aspects +of of the system. The newer features of the system are described in +the following documents: +\begin{citations} +\item[\LaTeXe{} for authors] + describes the new features of \LaTeX{} documents, + in the file \texttt{usrguide.tex}; +\item[\LaTeXe{} for class and package writers] + describes how to produce \LaTeX{} classes and packages, + in the file \texttt{clsguide.tex}; +\item[\LaTeXe{} font selection] + describes the new features of \LaTeX{} fonts for + class and package writers, + in the file \texttt{fntguide.tex}. +\end{citations} + +For further contacts and sources of information on \TeX{} and +\LaTeX{}, see the addresses on Page~\pageref{contacts}. + +\endgroup +\pagebreak + + +\section{The \LaTeX3 Project Fund} +\label{fund} + +Although \LaTeX{} may be distributed freely, the production and +maintenance of the system does require expenditure of reasonably large +sums of money. There are many necessities that need substantial +financing: examples are new or enhanced computing equipment and travel +to team meetings (the volunteers come from many different countries, +so getting together occasionally is a non-trivial exercise). + +This is why we are appealing to you for contributions to the fund. +Any sum will be much appreciated; the amount need not be large as +small contributions add up to very useful amounts. Contributions of +suitable equipment and software will also be of great value. This +appeal is both to you as an individual author and to you as a member +of a group or as an employee: please encourage your department or your +employer to contribute towards sustaining our work. + +We should like to see funded projects that make considerable use of +\LaTeX{} (\eg conferences and research teams who use it to publish +their work, and electronic research archives using it) include +contributions to this fund in their budgets. %% e-print systems + +We are also asking commercial organisations to assess the benefits +they gain from using, or distributing, a well-supported \LaTeX{} and +to make appropriate contributions to the fund in order that we can +continue to maintain and improve the product. If you work for, or do +business with, such an organisation, please bring to the attention of +the relevant people the existence and needs of the project. + +In particular, we ask that all the large number of organisations and +businesses that distribute \LaTeX{}, within other software or as part +of a CD-ROM collection, should consider pricing all products containing +\LaTeX{} at a level that enables them to make regular donations to the +fund from the profit on these items. We also ask all authors and +publishers of books about \LaTeX{} to consider donating part of the +royalties to the fund. + +Contributions should be sent to one of the following addresses: +\begin{quote}\small\label{addrs} + \TeX{} Users Group, P.O. Box 2311, Portland, OR~97208-2311 USA\\ + Fax:~+1~503~223~3960 \ Email: \texttt{tug@tug.org} + + \noindent + UK TUG, 1 Eymore Close, Selly Oak, Birmingham B29~4LB UK\\ + Fax: +44 121 476 2159 \ Email: \texttt{uktug-enquiries@tex.ac.uk} +\end{quote} + +Cheques should be payable to the user group (TUG or UKTUG) and be +clearly marked as contributions to the \LaTeX3 fund. +Many thanks to all of you who have contributed in the past and thanks +in advance for your generosity in the future. + +\section{Contacts and information} +\label{contacts} + +In addition to the sources mentioned above, \LaTeX{} has its home page +on the World Wide Web at: +\begin{verbatim} + http://www.latex-project.org/ +\end{verbatim} +This page describes \LaTeX{} and the \LaTeX3 project, and contains +pointers to other \LaTeX{} resources, such as the user guides, the +\TeX{} Frequently Asked Questions, and the \LaTeX{} bugs database. + +More general information, including contacts for local User Groups, +can be accessed via: +\begin{verbatim} + http://www.tug.org/ +\end{verbatim} + +The electronic home of anything \TeX-related is the Comprehensive +\TeX{} Archive Network (CTAN). This is a network of cooperating ftp +sites, with over a gigabyte of \TeX{} material: +\begin{verbatim} + ftp://cam.ctan.org/tex-archive/ + ftp://dante.ctan.org/tex-archive/ + ftp://tug.ctan.org/tex-archive/ +\end{verbatim} + +For more information, see the \LaTeX{} home page. + + +\end{document} + + + diff --git a/macros/latex-dev/doc/modguide.pdf b/macros/latex-dev/doc/modguide.pdf new file mode 100644 index 0000000000..4079173f4d Binary files /dev/null and b/macros/latex-dev/doc/modguide.pdf differ diff --git a/macros/latex-dev/doc/modguide.tex b/macros/latex-dev/doc/modguide.tex new file mode 100644 index 0000000000..147fec7878 --- /dev/null +++ b/macros/latex-dev/doc/modguide.tex @@ -0,0 +1,412 @@ +% \iffalse meta-comment +% +% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 +% The LaTeX3 Project and any individual authors listed elsewhere +% in this file. +% +% This file is part of the LaTeX base system. +% ------------------------------------------- +% +% 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 +% 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 file has the LPPL maintenance status "maintained". +% +% The list of all files belonging to the LaTeX base distribution is +% given in the file `manifest.txt'. See also `legal.txt' for additional +% information. +% +% The list of derived (unpacked) files belonging to the distribution +% and covered by LPPL is defined by the unpacking scripts (with +% extension .ins) which are part of the distribution. +% +% \fi +% Filename: modguide.tex + +\NeedsTeXFormat{LaTeX2e}[1995/12/01] + +\documentclass{ltxguide}[1995/11/28] + +\newcommand{\reasonsection}[1]{\subsubsection*{\it #1}} + +\newcommand{\nstex}{\textsf{NS-TeX}} + +\setcounter{secnumdepth}{-1} + +\title{Modifying \LaTeX} + +\author{\copyright~Copyright 1995, \LaTeX3 Project Team.\\ + All rights reserved.} + +\date{12 December 1995} + +\begin{document} + +\maketitle + +\tableofcontents + +\begin{abstract} + This document was produced in response to suggestions that the + modification and distribution conditions for the files constituting + the New Standard \LaTeX{} system should be similar to those implied + by Version~2 of the \textsc{GNU} General Public Licence, as + published by the Free Software Foundation. +\end{abstract} + +\section{Introduction} +\label{sec:intro} + +This article describes the principles underlying our policy on +distribution and modification of the files comprising the \LaTeX{} +system. It has been produced as a result of detailed discussions of +the issues involved in the support and maintenance of a widely +distributed document processing system used by diverse people for many +applications. These discussions have involved users, maintainers of +installations that support \LaTeX{} and various types of organisations +that distribute it. The discussions are continuing and we hope that +the ideas in this article will make a useful contribution to the +debate. + +Our aim is that \LaTeX{} should be a system which can be trusted by +users of all types to fulfill their needs. Such a system must be +stable and well-maintained. This implies that it must be reasonably +easy to maintain (otherwise it will simply not get maintained at +all). So here is a summary of our basic philosophy: +\begin{quote} + We believe that the freedom to rely on a widely-used standard for + document interchange and formatting is as important as the freedom to + experiment with the contents of files. + + We are therefore adopting a policy similar to that which Donald + Knuth applies to modifications of the underlying \TeX{} system: that + certain files, together with their names, are part of the system and + therefore the contents of these files should not be changed unless + the following conditions are met: + \begin{itemize} + \item they are clearly marked as being no longer part of the + standard system; + \item the name of the file is changed. + \end{itemize} +\end{quote} + + +\section{The system} +\label{sec:sys} + +In developing this philosophy, and the consequent limitations on how +modifications of the system should be carried out, we were heavily +influenced by the following facts concerning the current widespread +and wide-ranging uses of the \LaTeX{} system. +\begin{enumerate} +\item \LaTeX{} is not just a document processing system; + it also defines a language for document exchange. + +\item The standard document class files, and some other files, also + define a particular formatting of a document. + +\item The packages that we maintain define a particular document + interface and, in some cases, particular formatting of parts of a + document. + +\item The interfaces between different parts of the \LaTeX{} system + are very complex and it is therefore very difficult to check that a + change to one file does not affect the functionality of both that + file and also other parts of the system not obviously connected to + the file that has been changed. +\end{enumerate} + +This leads us to the general principle that: +\begin{quote} + with certain special exceptions, if you change the contents of a + file then the changed version should have a different file name. +\end{quote} + +We certainly do not wish to prevent people from experimenting with the +code in different ways and adapting it to their purposes. However, we +are concerned that any distribution of modifications to the code +should be very clearly identified as not being a part of the standard +distribution. The exact wording and form of the distribution +conditions is thus something that is flexible, but only within the +constraint of keeping \LaTeX{} as a standardised, reliable product for +the purposes described above: the exchange and formatting of +documents. + + +\section{Some examples} +\label{sec:expl} + +Here we elaborate the arguments that have led us to the above +conclusion. + + +\reasonsection{Separate development considered harmful!} +\label{sec:ja} + +In many fields, the use of \LaTeX{} as a language for communication +is just as important as its capacity for fine typesetting; this is a +very important consideration for a large population of authors, +journal editors, archivists, etc. + +Related to this issue of portability is the fact that the file names +are part of the end-user syntax. + +As a real example, the \LaTeX{} `tools' collection contains the +package `array.sty'. A new user-level feature was added to this file +at the end of 1994 and a document using this feature can contain the +line: +\begin{verbatim} + \usepackage{array}[1994/10/16] +\end{verbatim} + +By supplying the optional argument, the document author is indicating +that a version of the file \texttt{array.sty} dated no earlier than +that date is required to run this document without error. + +This feature would be totally worthless if we were to allow an +alternative version of the array package to be distributed under the +same name since it would mean that there would be in circulation files +of a later date, but without the new feature. If the document +were processed using this `alternative array' then it would certainly +produce `undefined command' errors and would probably not be +processable at all. + + +\reasonsection{What's in a file-name?} +\label{sec:jb} + +In a pure markup language, such as SGML, it is reasonably clear that +control over the final presentation lies with the receiver of a +document and not with the author. + +However, the way that \LaTeX{} is often used in practice means that +most people (at least when using the standard classes and packages) +expect the formatting to be preserved when they send the document to +another site. + +For example, suppose, as is still the most common use of \LaTeX{} in +publishing, you produce a document for `camera-ready-copy' using the +class `article' and that you carefully tune the formatting by, for +example, adding some explicit line breaks etc, to ensure that it fits +the 8 page limit set by the editor a journal or proceedings. + +It then gets sent to the editor or a referee who, without anyone +knowing, has a non-standard version of the class file `article' and so +it then runs to 9 pages. The consequence of this will, at the least, +be a lot of wasted time whilst everyone involved works out what has +gone wrong; it will probably also lead to everyone blaming each other +for something which was in fact caused by a misguided distribution +policy. + +It should also be noted that, for most people, the version of the +class file `article' that gets used is decided by a site maintainer +or the compilers of a CD-ROM distribution. To most users, +the symbols \texttt{a\,r\,t\,i\,c\,l\,e} in: +\begin{verbatim} + \documentclass{article} +\end{verbatim} +are just as much part of \LaTeX{}'s syntax as are the symbols +\texttt{1\,2\,p\,t} in: +\begin{verbatim} + \hspace{12pt} +\end{verbatim} +Thus they should both define a standard formatting rather than +sometimes producing 1 more page or a 5pt larger space. + +Users rely on the fact that the command (or menu item) `LaTeX' +produces a completely standard \LaTeX, including the fact that +`article' is the `standard article'. They would not be at all happy +if the person who installed and maintains \LaTeX{} for them were +allowed to customise `article' every second day so as (in her or his +opinion) to improve the layout; or because another user wanted to write +a document in a different language or typeset one with different fonts. + +\reasonsection{\TeX{} itself} +\label{sec:tex} + +We have modelled our policies on those of the \TeX{} system since this +has for some time now been widely acknowledged as a very stable and +high quality typesetting system. + +The distribution policy set up by Donald Knuth for \TeX{} has the +following features: +\begin{itemize} +\item There is a clearly specified method for changing parts of the + software by the use of `change files'. +\item Although arbitrary changes are allowed, the resulting program + can be called \TeX{} only if its functionality is precisely the same + as that of \TeX{} (i.e.~neither less nor more) in all important + areas. +\item There are many files in the system that cannot be changed at all + (without changing the name): examples are the file + \texttt{plain.tex} and the files associated with fonts, including + the Metafont source files. +\end{itemize} + + +\reasonsection{Maintaining complexity} +\label{sec:compl} + +Our experience of maintaining \LaTeX{} has shown us just how complex +are the interactions between different parts of the system. + +We have therefore, with lots of help from the bug reports you send in, +developed a large suite of test files which we run to check the +effects of every change we make. A non-negligible percentage of these +test runs give unexpected results and hence show up some unexpected +dependency in the system. + + +\section{Some assurances} +\label{sec:conc} + +We are certainly not attempting to stop people reformatting \LaTeX{} +documents in any way they wish. There are many ways of customising +incoming documents to your personal style that do not involve changing +the contents of \LaTeX{}'s standard files; indeed, this freedom is one +of the system's many advantages. +The simplest way to achieve this is to replace +\begin{quote} +\verb|\documentclass{article}|\quad by\quad +\verb|\documentclass{myart}| +\end{quote} + +Nor do we wish to discourage the production of new packages improving +on the functionality or implementation of those we distribute. All we +ask is that, in the best interests of all \LaTeX{} users, you give +your superbly improved class or package file some other name. + +\section{Configuration possibilities} +\label{sec:conposs} + +The standard \LaTeX{} system format can be configured in several ways +to suit the needs and resources of an installation. For example, the +loading of fonts and font tables can be customised to match the font +shapes, families and encodings normally used in text mode. Also, by +producing the appropriate font definition files, the font tables +themselves can be set up to take advantage of the available fonts and +sizes. The loading of hyphenation patterns can be adjusted to cover +the languages used; this has to be done as part of making the format +since this is the only stage at which patterns can be loaded. + +A complete list of these configuration possibilities can be found in +the distributed guide \emph{Configuration options for} \LaTeXe{} +(\texttt{cfgguide.tex}). However, as it says there, the number of +configuration possibilities is strictly limited; we hope that having +read this far you will appreciate the reasons for this decision. One +consequence of this is that there is no provision for a general +purpose configuration file, or for adding extra code just before the +|\dump| of the format file. + +This was a deliberate decision and we hope that everyone (yes, that +includes you!) will support its intent. Otherwise there will be a +rapid return to the very situation, of several incompatible versions +of \LaTeX~2.09, that originally prompted us to produce \LaTeXe{}: the +new, and \emph{only}, `Standard \LaTeX'. This will make \LaTeX{} +unmaintainable and, hence, unmaintained (by us, at least). + +\begin{quote} + Therefore you should not misuse the configuration files or other + parts of the distribution to produce non-standard versions of + \LaTeX{}. +\end{quote} + +Some of the allowed configurations can result in a system that can produce +documents that are no longer `formatting compatible'; for example, the +use of different default fonts will most likely produce different line +and page breaks. If you do produce a system that is configured in +such a way that it is not `formatting compatible' then you should +consider carefully the needs of users who need to create portable +documents. A good way to provide for their needs is to make +available, in addition, a standard form of \LaTeX{} without any +`formatting incompatible' customisations. + + +\section{Modification conditions} +\label{sec:modcon} + +It is possible that you need to produce a document processing system +based on standard \LaTeX{} but with functionality that cannot be +implemented by using the approved configuration files and complying +with the restriction on the code that is allowed in them. In other +words, you may need a system which is sufficiently distinct from +Standard \LaTeX{} that it is not feasible to do this simply by using +the configuration options we provide or by producing new classes and +packages. + +If you do produce such a system then, for the reasons described +above, you should ensure that your system is clearly distinguished +from Standard \LaTeX{} in every possible way, including the following. + + +\begin{enumerate} +\item + Give your system a distinguished name, such as \nstex, which clearly + distinguishes it from \LaTeX{}. + +\item + Ensure that it contains no file with a name the same as that of + a file in the standard distribution but with different contents. + (If this is not possible then you must: + \begin{itemize} + \item + ensure that files from the non-\LaTeX{} system cannot be + accidentally accessed whilst using a standard \LaTeX{}; + \item ensure that each file from the non-\LaTeX{} system clearly + identifies itself as a non-\LaTeX{} file on the terminal and in the + log file.) + \end{itemize} + +\item + Ensure that the method used to run your system is clearly +\label{mcon:command} + distinct from that used to run Standard \LaTeX; e.g.~by using a + command name or menu entry that is clearly not \texttt{latex} + (or \texttt{LaTeX} etc). + +\item + Ensure that, when a file is being processed by your system, the + use of non-standard \LaTeX{} is clearly proclaimed to the user by + whatever means is appropriate. + +\item Ensure that what is written at the beginning of the log file + clearly shows that your system has been used, and that it is + not Standard \LaTeX{}. + See the file \texttt{cfgguide.tex} for how to achieve this. + +\item + Clearly explain to users that bug reports concerning your + system should not be sent to the maintainers of Standard + \LaTeX{}. +\end{enumerate} + +\subsection*{Note to system administrators} + +If you install a non-standard (modified) version of \LaTeX{} on a +multi-user site then please, in addition, install Standard \LaTeX{} +and observe the conditions enumerated above, particularly +\ref{mcon:command}. + + +\section{What do you think?} +\label{sec:you} + +We are interested in your views on the issues raised in this document. +The best way to let us know what you think, and to discuss your ideas +with others, is to join the \texttt{LaTeX-L} mailing list and send your +comments there. +To subscribe to this list, mail to: +\begin{verbatim} + listserv@urz.uni-heidelberg.de +\end{verbatim} +the following one line message: +\begin{verbatim} + subscribe LATEX-L <your-first-name> <your-second-name> +\end{verbatim} + +\end{document} diff --git a/macros/latex-dev/doc/usrguide.pdf b/macros/latex-dev/doc/usrguide.pdf new file mode 100644 index 0000000000..d19c69139e Binary files /dev/null and b/macros/latex-dev/doc/usrguide.pdf differ diff --git a/macros/latex-dev/doc/usrguide.tex b/macros/latex-dev/doc/usrguide.tex new file mode 100644 index 0000000000..df02c20293 --- /dev/null +++ b/macros/latex-dev/doc/usrguide.tex @@ -0,0 +1,1817 @@ +% \iffalse meta-comment +% +% Copyright 1993-2019 +% The LaTeX3 Project and any individual authors listed elsewhere +% in this file. +% +% This file is part of the LaTeX base system. +% ------------------------------------------- +% +% 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 +% 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 file has the LPPL maintenance status "maintained". +% +% The list of all files belonging to the LaTeX base distribution is +% given in the file `manifest.txt'. See also `legal.txt' for additional +% information. +% +% The list of derived (unpacked) files belonging to the distribution +% and covered by LPPL is defined by the unpacking scripts (with +% extension .ins) which are part of the distribution. +% +% \fi +% Filename: usrguide.tex + +\NeedsTeXFormat{LaTeX2e}[1995/12/01] + +\documentclass{ltxguide}[2001/05/28] + +\title{\LaTeXe~for authors} + +\author{\copyright~Copyright 1995--2019, \LaTeX3 Project Team.\\ + All rights reserved.} + +\date{27 January 2019} + + +\begin{document} + +\maketitle + +\tableofcontents + +\section{Introduction} + +Welcome to \LaTeXe, the new standard version of the \LaTeX{} Document +Preparation System. + +This document describes how to take advantage of the new features of +\LaTeX, and how to process your old \LaTeX{} documents with +\LaTeXe. However, this document is only a brief introduction to the +new facilities and is intended for authors who are already familiar +with the old version of \LaTeX{}. It is \emph{not} a reference manual +for \LaTeXe{} nor is it a complete introduction to \LaTeX. + +It is somewhat of an historical document now, since \LaTeXe{} came into +existence in 1994. + +\subsection[\LaTeXe---The new \LaTeX~release] + {\LaTeXe---The new \LaTeX~release\\ (well, for more than 10 years now)} + +The previous version of \LaTeX{} was known as \LaTeX~2.09. Over the +years many extensions have been developed for \LaTeX. This is, of +course, a sure sign of its continuing popularity but it has had one +unfortunate result: incompatible \LaTeX{} formats came into use at +different sites. This included `standard \LaTeX~2.09', \LaTeX{} built +with the \emph{New Font Selection Scheme}~(\NFSS), \SLiTeX, \AmSLaTeX, +and so on. Thus, to process documents from various places, a site +maintainer was forced to keep multiple versions of the \LaTeX{} +program. In addition, when looking at a source file it was not always +clear for which format the document was written. + +To put an end to this unsatisfactory situation, \LaTeXe{} has been +produced; it brings all such extensions back under a single format and +thus prevents the proliferation of mutually incompatible dialects of +\LaTeX~2.09. With \LaTeXe{} the `new font selection scheme' is +standard and, for example, \textsf{amsmath} (formerly the \AmSLaTeX{} +format) or \textsf{slides} (formerly the \SLiTeX{} format) are simply +extensions, which may be loaded by documents using the same base format. + +The introduction of a new release also made it possible to add a small +number of often-requested features and to make the task of writing +packages and classes simpler. + +\subsection{\LaTeX3---The long-term future of \LaTeX} +\label{Sec:ltx3} + +\LaTeXe{} is the consolidation step in a comprehensive +reimplementation of the \LaTeX{} system. The next major release of +\LaTeX{} will be \LaTeX3, which will include a radical overhaul of the +document designers' and package writers' interface to \LaTeX. + +\LaTeX3 is a long-term research project but, until it is completed, +the project team are committed to the active maintenance of \LaTeXe{}. +Thus the experience gained from the production and maintenance of +\LaTeXe{} will be a major influence on the design of \LaTeX3. +A brief description of the project can be found in the document +|ltx3info.tex|. + +If you would like to support the project then you are welcome to send +donations to the \LaTeX3 Project Fund; this has been set up to help +the research team by financing various expenses associated with this +voluntary work of maintaining the current \LaTeX{} and developing +\LaTeX3. + +The fund is administered by The \TeX{} Users Group and by various +local user groups. Information about making donations and joining +these groups is available from: +\begin{quote}\small\label{addrs} + \texttt{http://www.tug.org/lugs.html} +\end{quote} + +The \LaTeX3{} project has its home page +on the World Wide Web at: +\begin{verbatim} + http://www.latex-project.org/ +\end{verbatim} +This page describes \LaTeX{} and the \LaTeX3 project, and contains +pointers to other \LaTeX{} resources, such as the user guides, the +\TeX{} Frequently Asked Questions, and the \LaTeX{} bugs database. + +Older articles covering aspects of the \LaTeX3 project are also +available for anonymous ftp from the Comprehensive \TeX{} Archive, in +the directory: +\begin{verbatim} + ctan:info/ltx3pub +\end{verbatim} +The file |ltx3pub.bib| in that directory contains an abstract of each +of the files. + +\subsection{Overview} + +This document contains an overview of the new structure and features +of \LaTeX. It is \emph{not} a self-contained document, as it contains +only the features of \LaTeX{} which have changed since version 2.09. +You should read this document in conjunction with an introduction to +\LaTeX{}. + +\begin{description} + +\item[Section~\ref{Sec:class+packages}] + contains an overview of the new structure of + \LaTeX{} documents. It describes how classes and packages work and + how class and package options can be used. It lists the standard + packages and classes which come with \LaTeX. + +\item[Section~\ref{Sec:commands}] describes the new commands available + to authors in \LaTeXe. + +\item[Section~\ref{Sec:209}] shows how to process old \LaTeX{} + documents with \LaTeXe. + +\item[Section~\ref{Sec:problems}] contains advice on dealing with + problems you may encounter in running \LaTeXe. + It lists some error messages which are new in \LaTeXe{} and + it describes some of the more common problems and how to cure them, + or where to find further information. + +\end{description} + +\subsection{Further information} + +For a general introduction to \LaTeX, including the new features of +\LaTeXe, you should read \emph{\LaTeXbook} +by Leslie Lamport~\cite{A-W:LLa94}. + +A more detailed description of the new features of \LaTeX, including an +overview of more than 200 packages and nearly 1000 ready to run examples, is +to be found in \emph{\LaTeXcomp second edition} by Frank Mittelbach and +Michel Goossens~\cite{A-W:MG2004}. + +Packages and programs for producing and manipulating graphics are +discussed at length in \emph{\LaTeXGcomp} by Michel Goossens, +Sebastian Rahtz and Frank Mittelbach~\cite{A-W:GRM97}. + +Solutions for publishing with \LaTeX{} on the World Wide Web are given +in \emph{\LaTeXWcomp} by Michel Goossens and Sebastian +Rahtz~\cite{A-W:GR99}. + +For more information about the many new \LaTeX{} packages you should +read the package documentation, which should be available from the +same source as your copy of \LaTeX. + +There are a number of documentation files which accompany every copy +of \LaTeX. A copy of \emph{\LaTeX{} News} will come out with each +six-monthly release of \LaTeX; it will be found in the files +|ltnews*.tex|. The class- and package-writer's guide \emph{\clsguide} +describes the new \LaTeX{} features for writers of document classes +and packages; it is in |clsguide.tex|. The guide \emph{\fntguide} +describes the \LaTeX{} font selection scheme for class- and +package-writers; it is in |fntguide.tex|. Support for Cyrillic languages +in \LaTeX{} is described in \emph{\cyrguide}. + +The documented source code (from the files used to produce the kernel +format via |latex.ltx|) is now available as +\emph{The \LaTeXe\ Sources}. ] +This very large document also includes an index of +\LaTeX{} commands. It can be typeset from the \LaTeX{} file +|source2e.tex| in the |base| directory, using the source files and +the class file |ltxdoc.cls| from this directory. + +For more information about \TeX{} and \LaTeX{}, please contact your +local \TeX{} Users Group, or the international \TeX{} Users Group (see +page \pageref{addrs}). + + +\section{Classes and packages} +\label{Sec:class+packages} + +This section describes the new structure of \LaTeX{} documents and the +new types of file: \emph{classes} and \emph{packages}. + +\subsection{What are classes and packages?} + +The main difference between \LaTeX~2.09 and \LaTeXe{} is in the +commands before |\begin{document}|. + +In \LaTeX~2.09, documents had \emph{styles}, +such as \textsf{article} or \textsf{book}, and \emph{options}, +such as \textsf{twoside} or \textsf{epsfig}. +These were indicated by the |\documentstyle| command: +\begin{quote} + |\documentstyle|\oarg{options}\arg{style} +\end{quote} +For example, to specify a two-sided article with encapsulated +PostScript figures, you said: +\begin{verbatim} + \documentstyle[twoside,epsfig]{article} +\end{verbatim} +However, there were two different types of document style option: +\emph{built-in options} such as |twoside|; and \emph{packages} such as +|epsfig.sty|. These were very different, since any \LaTeX{} document +style could use the \textsf{epsfig} package but only document styles +which declared the \textsf{twoside} option could use that option. + +To avoid this confusion, \LaTeXe{} differentiates between built-in +options and packages. These are given by the new |\documentclass| and +|\usepackage| commands: +\begin{quote} + |\documentclass|\oarg{options}\arg{class} \\ + |\usepackage|\oarg{options}\arg{packages} +\end{quote} +For example, to specify a two-sided article with encapsulated +PostScript figures, you now write: +\begin{verbatim} + \documentclass[twoside]{article} + \usepackage{epsfig} +\end{verbatim} +You can load more than one package with a single |\usepackage| +command; for example, rather than writing: +\begin{verbatim} + \usepackage{epsfig} + \usepackage{multicol} +\end{verbatim} +you can specify: +\begin{verbatim} + \usepackage{epsfig,multicol} +\end{verbatim} +Note that \LaTeXe{} still understands the \LaTeX~2.09 |\documentstyle| +command. This command causes \LaTeXe{} to enter \emph{\LaTeX~2.09 +compatibility mode}, which is described in Section~\ref{Sec:209}. + +You should not, however, use the |\documentstyle| command for new +documents because this compatibility mode is very slow and the new +features of \LaTeXe{} are not available in this mode. + +To help differentiate between classes and packages, document classes +now end with |.cls| rather than |.sty|. Packages still end with +|.sty|, since most \LaTeX~2.09 packages work well with \LaTeXe. + +\subsection{Class and package options} + +In \LaTeX~2.09, only document styles could have options such as +|twoside| or |draft|. In \LaTeXe{}, both classes and packages are +allowed to have options. For example, to specify a two-sided article +with graphics using the |dvips| driver, you write: + +\begin{verbatim} + \documentclass[twoside]{article} + \usepackage[dvips]{graphics} +\end{verbatim} +It is possible for packages to share common options. For example, +you could, in addition, load the \textsf{color} package by specifying: +\begin{verbatim} + \documentclass[twoside]{article} + \usepackage[dvips]{graphics} + \usepackage[dvips]{color} +\end{verbatim} +But because |\usepackage| allows more than one package to be listed, +this can be shortened to: +\begin{verbatim} + \documentclass[twoside]{article} + \usepackage[dvips]{graphics,color} +\end{verbatim} +In addition, packages will also use each option given to +the |\documentclass| command (if they know what to do with it), so you +could also write: +\begin{verbatim} + \documentclass[twoside,dvips]{article} + \usepackage{graphics,color} +\end{verbatim} +Class and package options are covered in more detail in +\emph{\LaTeXcomp} and in \emph{\clsguide}. + +\subsection{Standard classes} + +The following classes are distributed with \LaTeX: +\begin{description} + +\item[article] The |article| class described in \emph{\LaTeXbook}. +\item[book] The |book| class described in \emph{\LaTeXbook}. +\item[report] The |report| class described in \emph{\LaTeXbook}. +\item[letter] The |letter| class described in \emph{\LaTeXbook}. +\item[slides] The |slides| class described in \emph{\LaTeXbook}, + formerly \SLiTeX. +\item[proc] A document class for proceedings, based on |article|. + Formerly the |proc| package. +\item[ltxdoc] The document class for documenting the \LaTeX{} + program, based on |article|. +\item[ltxguide] The document class for \emph{\usrguide} and + \emph{\clsguide}, based on |article|. The document you are reading + now uses the |ltxguide| class. The layout for this class is likely + to change in future releases of \LaTeX. +\item[ltnews] The document class for the \emph{\LaTeX{} News} + information sheet, based on |article|. The layout for this class + is likely to change in future releases of \LaTeX. +\item[minimal] +\NEWfeature{1995/12/01} + This class is the bare minimum (3 lines) that is needed in a + \LaTeX\ class file. It just sets the text width and height, and + defines |\normalsize|. It is principally intended for debugging + and testing \LaTeX\ code in situations where you do not need to + load a `full' class such as |article|. If, however, you are + designing a completely new class that is aimed for documents with + structure radically different from the structure supplied by the + article class, then it may make sense to use this as a base and add + to it code implementing the required structure, rather than + starting from |article| and modifying the code there. +\end{description} + +\subsection{Standard packages} +\label{Sec:st-pack} + +The following packages are distributed with \LaTeX: +\begin{description} +\item[alltt] +\NEWfeature{1994/12/01} + This package provides the |alltt| environment, which is like + the |verbatim| environment except that |\|, |{|, and |}| + have their usual meanings. It is described in |alltt.dtx| and + \emph{\LaTeXbook}. +\item[doc] This is the basic package for typesetting the documentation + of \LaTeX{} programs. It is described in |doc.dtx| and in + \emph{\LaTeXcomp}. +\item[exscale] This provides scaled versions of the math extension + font. It is described in |exscale.dtx| and \emph{\LaTeXcomp}. + \item[fontenc] This is used to specify which font encoding \LaTeX{} + should use. It is described in |ltoutenc.dtx|. +\item[graphpap] +\NEWfeature{1994/12/01} + This package defines the |\graphpaper| command; this + can be used in a |picture| environment. +\item[ifthen] Provides commands of the form `if\dots then do\dots + otherwise do\dots'. + It is described in |ifthen.dtx| and \emph{\LaTeXcomp}. +\item[inputenc] +\NEWfeature{1994/12/01} + This is used to specify which input encoding \LaTeX{} should use. + It is described in |inputenc.dtx|. +\item[latexsym] \LaTeXe{} no longer loads the \LaTeX{} symbol font by + default. To access it, you should use the |latexsym| package. It + is described in |latexsym.dtx| and in \emph{\LaTeXcomp}; see also + Section~\ref{Sec:problems}. + \item[makeidx] This provides commands for producing indexes. It is + described in \emph{\LaTeXbook} and in \emph{\LaTeXcomp}. + \item[newlfont] This is used to emulate the font commands of + \LaTeX~2.09 with the New Font Selection Scheme. It is described in + \emph{\LaTeXcomp}. + \item[oldlfont] This is used to emulate the font commands of + \LaTeX~2.09. It is described in \emph{\LaTeXcomp}. + \item[showidx] + This causes the argument of each |\index| command to + be printed on the page where it occurs. + It is described in \emph{\LaTeXbook}. + \item[syntonly] This is used to process a document without + typesetting it. It is described in |syntonly.dtx| and in + \emph{\LaTeXcomp}. + \item[tracefnt] This allows you to control how much information about + \LaTeX's font loading is displayed. It is described in + \emph{\LaTeXcomp}. +\end{description} + +\subsection{Related software} + +\NEWdescription{1998/12/01} +The following software should be available from the same distributor +as your copy of \LaTeXe. You should obtain at least the +\textsf{graphics} and \textsf{tools} collections in order to have all +the files described in \emph{\LaTeXbook}. The |amsmath| package (part +of \textsf{amslatex} and formerly known as |amstex|) +and \textsf{babel} are also mentioned in the list +of `standard packages' in section C.5.2 of that book. +\begin{description} +\item[amslatex] Advanced mathematical typesetting from the American + Mathematical Society. This includes the |amsmath| package; it + provides many commands for typesetting mathematical formulas of + higher complexity. It is produced and supported by the American + Mathematical Society and it is described in \emph{\LaTeXcomp}. +\item[babel] This package and related files support typesetting in + many languages. It is described in \emph{\LaTeXcomp}. +\item[cyrillic] +\NEWfeature{1998/12/01} + Everything you need (except the fonts themselves) for + typesetting with Cyrillic fonts. +\item[graphics] This includes the |graphics| package which + provides support for the inclusion and transformation of graphics, + including files produced by other software. Also included, is the + |color| package which provides support for typesetting in colour. + Both these packages are described in \emph{\LaTeXbook}. +\item[psnfss] Everything you need (except the fonts themselves) for + typesetting with a large range of Type~1 (PostScript) fonts. +\item[tools] Miscellaneous packages written by the \LaTeX3 + project team. +\end{description} +These packages come with documentation and each of them is also +described in at least one of the books \emph{\LaTeXcomp} and +\emph{\LaTeXbook}. + +\subsubsection{Tools} + +This collection of packages includes, at least, the following (some +files may have slightly different names on certain systems): + +\begin{description} +\item[array] + Extended versions of the environments |array|, |tabular| + and |tabular*|, with many extra features. +\item[calc] +\NEWfeature{1996/12/01} + Enables the use of certain algebraic notation when specifying + values for lengths and counters. +\item[dcolumn] + Alignment on `decimal points' in tabular entries. Requires the + |array| package. +\item[delarray] + Adds `large delimiters' around arrays. Requires |array|. +\item[hhline] + Finer control over horizontal rules in tables. Requires |array|. +\item[longtable] + Multi-page tables. (Does not require |array|, but it uses the + extended features if both are loaded.) +\item[tabularx] + Defines a |tabularx| environment that is similar to |tabular*| + but it modifies the column widths, rather than the inter-column + space, to achieve the desired table width. +\item[afterpage] + Place text after the current page. +\item[bm] + Access bold math symbols. +\item[enumerate] + Extended version of the |enumerate| environment. +\item[fontsmpl] + Package and test file for producing `font samples'. +\item[ftnright] + Place all footnotes in the right-hand column in two-column mode. +\item[indentfirst] + Indent the first paragraph of sections, etc. +\item[layout] + Show the page layout defined by the current document class. +\item[multicol] + Typeset text in columns, with the length of the columns + `balanced'. +\item[rawfonts] + Preload fonts using the old internal font names of \LaTeX~2.09. + See Section~\ref{Sec:oldinternals}. +\item[somedefs] + Selective handling of package options. (Used by the rawfonts + package.) +\item[showkeys] + Prints the `keys' used by |\label|, |\ref|, |\cite| etc.; useful + whilst drafting. +\item[theorem] + Flexible declaration of `theorem-like' environments. +\item[varioref] + `Smart' handling of page references. +\item[verbatim] + Flexible extension of the verbatim environment. +\item[xr] + Cross reference other `external' documents. +\item[xspace] + `Smart space' command that helps you to avoid the common mistake + of missing spaces after command names. +\end{description} + + +\section{Commands} +\label{Sec:commands} + +This section describes the new commands available in \LaTeXe. +They are covered in more detail in \emph{\LaTeXbook} and in +\emph{\LaTeXcomp}. + +\subsection{Initial commands} + +Initial commands can appear only before the |\documentclass| +line. + +\begin{decl} +|\begin{filecontents}| \arg{file-name} \\ + \m{file-contents} \\ +|\end{filecontents}| +\end{decl} + +The |filecontents| environment is intended for bundling within a +single document file the contents of packages, options, or other +files. When the document file is run through \LaTeXe{} the body of +this environment is written verbatim (preceded by a comment line) to a +file whose name is given as the environment's only argument. However, +if that file already exists then nothing happens except for an +information message. + +Only normal ASCII text characters (7-bit visible text) should be +included in a |filecontents| environment. Anything else, such as tab +characters, form-feeds or 8-bit characters, should not be included in a +|filecontents| environment. + +Tabs and form feeds produce a warning, explaining that they are turned +into spaces or blank lines, respectively. +What happens to 8-bit characters depends on the \TeX{} installation and +is in general unpredictable. + +The |filecontents| environment is used for including \LaTeX{} files. +For other plain text files (such as Encapsulated PostScript files), +you should use the |filecontents*| environment which does not add a +comment line. + +These environments are allowed only before |\documentclass|. This +ensures that any packages that have been bundled in the document are +present when needed. + +\subsection{Preamble commands} +\label{Sec:pre} + +The changes to the preamble commands are intentionally designed to make +\LaTeXe{} documents look clearly different from old documents. The +commands should be used only before |\begin{document}|. + +\begin{decl} +|\documentclass| \oarg{option-list} \arg{class-name} + \oarg{release-date} +\end{decl} + +This command replaces the +\LaTeX~2.09 command |\documentstyle|. + +There must be exactly one |\documentclass| command in a document; and +it must come after the |filecontents| environments, if any, but before +any other commands. + +The \m{option-list} is a list of options, each of which may modify the +formatting of elements which are defined in the \m{class-name} file, +as well as those in all following |\usepackage| commands (see +below). + +The optional argument \m{release-date} can be used to specify the +earliest desired release date of the class file; it should contain a +date in the format \textsc{yyyy/mm/dd}. If a version of the class +older than this date is found, a warning is issued. + +For example, to specify a two-column article, using a version of +|article.cls| released after June 1994, you specify: +\begin{verbatim} + \documentclass[twocolumn]{article}[1994/06/01] +\end{verbatim} + +\begin{decl} +|\documentstyle| \oarg{option-list} \arg{class-name} +\end{decl} + +This command is still supported for compatibility with old files. It +is essentially the same as |\documentclass| except that it invokes +\emph{\LaTeX~2.09 compatibility mode}. It also causes any options in +the \m{option-list} that are not processed by the class file to be +loaded as packages after the class has been loaded. See +Section~\ref{Sec:209} for more details on \LaTeX~2.09 compatibility +mode. + +\begin{decl} +|\usepackage| \oarg{option-list} \arg{package-name} \oarg{release-date} +\end{decl} + +Any number of |\usepackage| commands is allowed. Each package file +(as denoted by \m{package-name}) defines new elements (or modifies +those defined in the class file loaded by the \m{class-name} argument +of the |\documentclass| command). A package file thus extends the +range of documents which can be processed. + +The \m{option-list} argument can contain a list of options, each of +which can modify the formatting of elements which are defined in this +\m{package-name} file. + +As above, \m{release-date} can contain the earliest desired release +date of the package file in the format \textsc{yyyy/mm/dd}; if an +older version of the package is found, a warning is issued. + +For example, to load the |graphics| package for the |dvips| driver, +using a version of |graphics.sty| released after June 1994, you write: +\begin{verbatim} + \usepackage[dvips]{graphics}[1994/06/01] +\end{verbatim} +Each package is loaded only once. If the same package is requested +more than once, nothing happens in the second or following attempt +unless the package has been requested with options that were not given +in the original |\usepackage|. If such extra options are specified +then an error message is produced. See Section~\ref{Sec:problems} how +to resolve this problem. + +As well as processing the options given in the \m{option-list} of the +|\usepackage| command, each package processes the +\m{option-list} of the |\documentclass| command as well. This +means that any option which should be processed by every package (to +be precise, by every package that specifies an action for it) can be +specified just once, in the |\documentclass| command, rather than +being repeated for each package that needs it. + +\begin{decl} +|\listfiles| +\end{decl} + +If this command is placed in the preamble then a list of the files +read in (as a result of processing the document) will be displayed +on the terminal (and in the log file) at the end of the run. Where +possible, a short description will also be produced. + +\NEWdescription{1995/12/01} +\emph{Warning}: this command will list only files which were read +using \LaTeX{} commands such as |\input|\arg{file} or +|\include|\arg{file}. If the file was read using the primitive \TeX{} +syntax |\input |\emph{file} (without |{ }| braces around the file name) +then it will not be listed; failure to use the \LaTeX{} form with the +braces can cause more severe problems, possibly leading to overwriting +important files, so \textbf{always put in the braces}. + + +\begin{decl} +|\setcounter{errorcontextlines}| \arg{num} +\end{decl} + +\TeX~3 introduced a new primitive |\errorcontextlines| which controls +the format of error messages. \LaTeXe\ provides an interface to this +through the standard |\setcounter| command. As most \LaTeX\ users do +not want to see the internal definitions of \LaTeX\ commands each time +they make an error, \LaTeXe{} sets this to $-1$ by default. + +\subsection{Document structure} + +The |book| document class introduces new commands to indicate +document structure. +\begin{decl} +|\frontmatter| \\ |\mainmatter| \\ |\backmatter| +\end{decl} +These commands indicate the beginning of the front matter (title page, +table of contents and prefaces), main matter (main text) and back +matter (bibliography, indexes and colophon). + +\subsection{Definitions} + +In \LaTeX, commands can have both mandatory and optional arguments, +for example in: +\begin{verbatim} + \documentclass[11pt]{article} +\end{verbatim} +the |11pt| argument is optional, whereas the |article| class name is +mandatory. + +In \LaTeX~2.09 users could define commands with arguments, but these +had to be mandatory arguments. With \LaTeXe, users can now define +commands and environments which also have one optional argument. + +\begin{decl} +|\newcommand| \arg{cmd} \oarg{num} \oarg{default} \arg{definition} \\ +|\newcommand*| \arg{cmd} \oarg{num} \oarg{default} \arg{definition} \\ +|\renewcommand| \arg{cmd} \oarg{num} \oarg{default} \arg{definition} \\ +|\renewcommand*| \arg{cmd} \oarg{num} \oarg{default} \arg{definition} +\end{decl} + +These commands have a new, second, optional argument; this is used for +defining commands which themselves take one optional argument. This +new argument is best introduced by means of a simple (and hence not +very practical) example: +\begin{verbatim} + \newcommand{\example}[2][YYY]{Mandatory arg: #2; + Optional arg: #1.} +\end{verbatim} +This defines |\example| to be a command with two arguments, referred +to as |#1| and |#2| in the \arg{definition}---nothing new so far. But +by adding a second optional argument to this |\newcommand| (the +|[YYY]|) the first argument (|#1|) of the newly defined command +|\example| is made optional with its default value being |YYY|. + +Thus the usage of |\example| is either: +\begin{verbatim} + \example{BBB} +\end{verbatim} +which prints: +\begin{quote} + Mandatory arg: BBB; + Optional arg: YYY. +\end{quote} +or: +\begin{verbatim} + \example[XXX]{AAA} +\end{verbatim} +which prints: +\begin{quote} + Mandatory arg: AAA; + Optional arg: XXX. +\end{quote} + +The default value of the optional argument is \texttt{YYY}. +This value is specified as the \oarg{default} argument of the +|\newcommand| that created |\example|. + +As another more useful example, the definition: +\begin{verbatim} + \newcommand{\seq}[2][n]{\lbrace #2_{0},\ldots,\,#2_{#1} \rbrace} +\end{verbatim} +means that the input |$\seq{a}$| produces +the formula $\lbrace a_{0},\ldots,\,a_{n} \rbrace$, +whereas the input |$\seq[k]{x}$| produces the formula +$\lbrace x_{0},\ldots,\,x_{k} \rbrace$. + +In summary, the command: +\begin{quote} + |\newcommand| \arg{cmd} \oarg{num} \oarg{default} \arg{definition} +\end{quote} +defines \m{cmd} to be a command with \m{num} arguments, the first of +which is optional and has default value \m{default}. + +Note that there can only be one optional argument but, as before, +there can be up to nine arguments in total. + +\begin{decl} +|\newenvironment| + \arg{cmd} \oarg{num} \oarg{default} \arg{beg-def} \arg{end-def} \\ +|\newenvironment*| + \arg{cmd} \oarg{num} \oarg{default} \arg{beg-def} \arg{end-def} \\ +|\renewenvironment| + \arg{cmd} \oarg{num} \oarg{default} \arg{beg-def} \arg{end-def} \\ +|\renewenvironment*| + \arg{cmd} \oarg{num} \oarg{default} \arg{beg-def} \arg{end-def} +\end{decl} + +\LaTeXe\ also supports the creation of environments that have one +optional argument. Thus the syntax of these two commands has +been extended in the same way as that of |\newcommand|. + +\begin{decl} +|\providecommand| \arg{cmd} \oarg{num} \oarg{default} \arg{definition} \\ +|\providecommand*| \arg{cmd} \oarg{num} \oarg{default} \arg{definition} +\end{decl} + +This takes the same arguments as |\newcommand|. If \m{cmd} is already +defined then the existing definition is kept; but if it is currently +undefined then the effect of |\providecommand| is to define \m{cmd} +just as if |\newcommand| had been used. + +\NEWfeature{1994/12/01} + All the above five `defining commands' now have \texttt{*}-forms that + are usually the better form to use when defining commands with + arguments, unless any of these arguments is intended to contain + whole paragraphs of text. Moreover, if you ever do find yourself + needing to use the non-star form then you should ask whether + that argument would not better be treated as the contents of a + suitably defined environment. + +\NEWfeature{1995/12/01} + The commands produced by the above five `defining commands' are + now robust. + +\subsection{Boxes} + +These next three commands for making LR-boxes all existed in +\LaTeX~2.09. They have been enhanced in two ways. + +\begin{decl} +|\makebox| \oarg{width} \oarg{pos} \arg{text} \\ +|\framebox| \oarg{width} \oarg{pos} \arg{text} \\ +|\savebox| \arg{cmd} \oarg{width} \oarg{pos} \arg{text} +\end{decl} + +One small but far-reaching change for \LaTeXe\ is that, within the +\m{width} argument only, four special lengths can be used. These are +all dimensions of the box that would be produced by using simply +|\mbox|\arg{text}: +\begin{itemize} +\item [] |\height|\quad its height above the baseline; +\item [] |\depth|\quad its depth below the baseline; +\item [] |\totalheight|\quad the sum of |\height| and |\depth|; +\item [] |\width|\quad its width. +\end{itemize} +Thus, to put `hello' in the centre of a box of twice its natural +width, you would use: +\begin{verbatim} + \makebox[2\width]{hello} +\end{verbatim} +Or you could put \textit{f} into a square box, like +this: + \framebox{\makebox[\totalheight]{\itshape f\/}} +\begin{verbatim} + \framebox{\makebox[\totalheight]{\itshape f\/}} +\end{verbatim} +Note that it is the total width of the framed box, including the +frame, which is set to |\totalheight|. + +The other change is a new possibility for \m{pos}: |s| has been added +to |l| and |r|. If \m{pos} is |s| then the text is stretched the full +length of the box, making use of any `rubber lengths' (including any +inter-word spaces) in the contents of the box. If no such `rubber +length' is present, an `underfull box' will probably be produced. + +\begin{decl} +|\parbox| \oarg{pos} \oarg{height} \oarg{inner-pos} \arg{width} + \arg{text} \\ +|\begin{minipage}| + \oarg{pos} \oarg{height} \oarg{inner-pos} \arg{width}\\ +\m{text}\\ +|\end{minipage}| +\end{decl} + +As for the box commands above, |\height|, |\width|, etc.~may be used +in the \oarg{height} argument to denote the natural dimensions of the +box. + +The \m{inner-pos} argument is new in \LaTeXe. It is the vertical +equivalent to the \m{pos} argument for |\makebox|, etc, determining +the position of \m{text} within the box. The \m{inner-pos} may be any +one of |t|, |b|, |c|, or |s|, denoting top, bottom, centered, or +`stretched' alignment respectively. When the \m{inner-pos} argument +is not specified, \LaTeX\ gives it same value as \m{pos} (this could be +the latter's default value). + + +\begin{decl} +|\begin{lrbox}| \arg{cmd}\\ +\m{text}\\ +|\end{lrbox}| +\end{decl} + +This is an environment which does not directly print anything. +Its effect is to save the typeset \m{text} in the bin \m{cmd}. Thus +it is like |\sbox| \arg{cmd} \arg{text}, except that any white space +before or after the contents \m{text} is ignored. + +This is very useful as it enables both the |\verb| command and the +\texttt{verbatim} environment to be used within \m{text}. + +It also makes it possible to define, for example, a `framed box' +environment. This is done by first using this environment to save +some text in a bin \m{cmd} and then calling +|\fbox{\usebox{|\m{cmd}|}}|. + +The following example defines an environment, called |fmpage|, that is +a framed version of |minipage|. +\begin{verbatim} + \newsavebox{\fmbox} + \newenvironment{fmpage}[1] + {\begin{lrbox}{\fmbox}\begin{minipage}{#1}} + {\end{minipage}\end{lrbox}\fbox{\usebox{\fmbox}}} +\end{verbatim} + + +\subsection{Measuring things} + +The first of these next commands was in \LaTeX~2.09. The two new +commands are the obvious analogues. + +\begin{decl} +|\settowidth| \arg{length-cmd} \arg{lr text} \\ +|\settoheight| \arg{length-cmd} \arg{lr text} \\ +|\settodepth| \arg{length-cmd} \arg{lr text} +\end{decl} + +\subsection{Line endings} + +\NEWdescription{1994/12/01} +The command |\\|, which is used to indicate a line-end in various +places, is now a robust command when used within arguments such as +section titles. + +Also, because it is often necessary to distinguish which type of line +is to be ended, we have introduced the following new command; it +has the same argument syntax as that of |\\|. +\begin{decl}[1994/12/01] +|\tabularnewline| \oarg{vertical-space} +\end{decl} +One example of its use is when the text in the last +column of a |tabular| environment is set with |\raggedright|; then +|\tabularnewline| can be used to indicate the end of a row of the +|tabular|, whilst |\\| will indicate the end of a line of text in a +paragraph within the column. This command can be used in the |array| +environment as well as |tabular|, and also the extended versions of +these environments offered by the \textsf{array} and \textsf{longtable} +packages in the tools collection. + +\subsection{Controlling page breaks} + +Sometimes it is necessary, for a final version of a document, to +`help' \LaTeX\ break the pages in the best way. \LaTeX~2.09 had a +variety of commands for this situation: |\clearpage|, |\pagebreak| +etc. \LaTeXe\ provides, in addition, commands which can produce +longer pages as well as shorter ones. + + +\begin{decl} +|\enlargethispage| \arg{size} \\ +|\enlargethispage*| \arg{size} +\end{decl} + +These commands increase the height of a page (from its normal value of +|\textheight|) by the specified amount \m{size}, a rigid length. This +change affects \emph{only} the current page. + +This can be used, for example, to allow an extra line to be fitted +onto the page or, with a negative length, to produce a page +shorter than normal. + +The star form also shrinks any vertical white space on the page as +much as possible, so as to fit the maximum amount of text on the +page. + +\NEWdescription{1995/12/01} +These commands do not change the position of the footer text; thus, if +a page is lengthened too far, the main text may overprint the footer. + +\subsection{Floats} + +There is a new command, |\suppressfloats|, and a new `float +specifier'. These will enable people to gain better +control of \LaTeX's float placement algorithm. + +\begin{decl} +|\suppressfloats| \oarg{placement} +\end{decl} + +This command stops any further floating environments from being placed +on the current page. With an optional argument, which should be either +|t| or |b| (not both), this restriction applies only to putting +further floats at the top or at the bottom. Any floats which would +normally be placed on this page are placed on the next page instead. + +\begin{decl} +The extra float location specifier: \ \texttt{!} +\end{decl} + +This can be used, along with at least one of \texttt{h}, \texttt{t}, +\texttt{b} and \texttt{p}, in the location optional argument of a +float. + +If a \texttt{!} is present then, just for this particular float, +whenever it is processed by the float mechanism the following are +ignored: +\begin{itemize} +\item all restrictions on the number of floats which can appear; +\item all explicit restrictions on the amount of space on a text page +which may be occupied by floats or must be occupied by text. +\end{itemize} +The mechanism will, however, still attempt to ensure that pages are +not overfull and that floats of the same type are printed in the +correct order. + +Note that its presence has no effect on the production of float pages. + +A \texttt{!} specifier overrides the effect of any |\suppressfloats| +command for this particular float. + +\subsection{Font changing: text} + +The font selection scheme used in \LaTeXe{} differs a lot from that +used in \LaTeX~2.09. In this section, we give a brief description of +the new commands. A more detailed description with examples is given +in \emph{\LaTeXcomp}, and the interface for class- and package-writers +is described in \emph{\fntguide}. + +\begin{decl} +|\normalfont|\\ +|\rmfamily|\\ +|\sffamily|\\ +|\ttfamily|\\ +|\mdseries|\\ +|\bfseries|\\ +|\upshape|\\ +|\itshape|\\ +|\slshape|\\ +|\scshape| +\end{decl} + +These are font commands whose use is the same as the commands |\rm|, +|\bf|, etc. The difference is that each command changes just one +attribute of the font (the attribute changed is part of the name). +One result of this is that, for example, |\bfseries\itshape| produces +both a change of series and a change of shape, to give a bold italic +font. + +\begin{decl} +|\textnormal|\arg{text}\\ +|\textrm|\arg{text}\\ +|\textsf|\arg{text}\\ +|\texttt|\arg{text}\\ +|\textmd|\arg{text}\\ +|\textbf|\arg{text}\\ +|\textup|\arg{text}\\ +|\textit|\arg{text}\\ +|\textsl|\arg{text}\\ +|\textsc|\arg{text}\\ +|\emph|\arg{text} +\end{decl} + +These are one-argument commands; they take as an argument the +text which is to be typeset in the particular font. They also +automatically insert italic corrections where appropriate; if you do +not like the result, you can add an italic correction with |\/| or +remove it with |\nocorr|. The |\nocorr| should always be the first or +last thing within the \arg{text} argument. + +\subsection{Font changing: math} + +Most of the fonts used within math mode do not need to be explicitly +invoked; but to use letters from a range of fonts, the following +class of commands is provided. + +\begin{decl} +|\mathrm| \arg{letters}\\ +|\mathnormal| \arg{letters}\\ +|\mathcal| \arg{letters}\\ +|\mathbf| \arg{letters}\\ +|\mathsf| \arg{letters}\\ +|\mathtt| \arg{letters}\\ +|\mathit| \arg{letters} +\end{decl} + +These are also one-argument commands which take as an argument the +letters which are to be typeset in the particular font. The argument +is processed in math mode so spaces within it will be ignored. Only +letters, digits and accents have their font changed, for example +|$\mathbf{\tilde A \times 1}$| produces $\mathbf{\tilde A \times 1}$. + +\subsection{Ensuring math mode} + +\begin{decl} +|\ensuremath| \arg{math commands} +\end{decl} + +In \LaTeX~2.09, if you wanted a command to work both in math mode and +in text mode, the suggested method was to define something like: +\begin{verbatim} + \newcommand{\Gp}{\mbox{$G_p$}} +\end{verbatim} +Unfortunately, the |\mbox| stops |\Gp| changing size correctly in (for +instance) subscripts or a fraction. + +In \LaTeXe{} you can define it thus: +\begin{verbatim} + \newcommand{\Gp}{\ensuremath{G_p}} +\end{verbatim} +Now |\Gp| will work correctly in all contexts. + +This is because the |\ensuremath| does nothing, producing simply +|G_p|, when |\Gp| is used within math mode; but it ensures that math +mode is entered (and exited) as required when |\Gp| is used in text +mode. + + +\subsection{Setting text superscripts} + +\begin{decl} +|\textsuperscript| \arg{text} +\end{decl} + +\NEWfeature{1995/06/01} In \LaTeX~2.09 textual superscripts such as +footnote markers were produced by internally entering math mode and +typesetting the number as a math superscript. This normally looked +fine since the digits in math fonts are the same as those in text +fonts when Computer Modern fonts are used. But when a different +document font (such as Times) is selected, the results look rather +strange. For this reason the command |\textsuperscript| has been +introduced which typesets its argument in the current text font, in a +superscript position and in the correct size. + +\subsection{Text commands: all encodings} + +\NEWdescription{1994/12/01} + One of the main differences between \LaTeXe{} and \LaTeX~2.09 is + that \LaTeXe{} can deal with fonts in arbitrary \emph{encodings}. + (A font encoding is the sequence of characters in the font---for + example a Cyrillic font would have a different encoding from a Greek + font.) + + The two major font encodings that are used for Latin languages such + as English or German are |OT1| (Donald Knuth's 7-bit encoding, which + has been used during most of \TeX's lifetime) and |T1| (the new + 8-bit `Cork' encoding). + + \LaTeX~2.09 only supported the |OT1| encoding, whereas \LaTeXe{} has + support for both |OT1| and |T1| built-in. The next section will + cover the new commands which are available if you have |T1|-encoded + fonts. This section describes new commands which are available in + all encodings. + + Most of these commands provide characters which were available in + \LaTeX~2.09 already. For example |\textemdash| gives an `em dash', + which was available in \LaTeX~2.09 by typing |---|. However, some + fonts (for example a Greek font) may not have the |---| ligature, + but you will still be able to access an em dash by typing + |\textemdash|. + +\begin{decl}[1994/12/01] + |\r{<text>}| +\end{decl} + This command gives a `ring' accent, for example `\r{o}' can be typed + |\r{o}|. + +\begin{decl}[1994/12/01] + |\SS| +\end{decl} + This command produces a German `SS', that is a capital `\ss'. This + letter can hyphenate differently from `SS', so is needed for entering + all-caps German. + +\begin{decl}[1994/12/01] + |\textcircled{<text>}| +\end{decl} + This command is used to build `circled characters' such as + |\copyright|. For example |\textcircled{a}| produces + \textcircled{a}. + +\begin{decl}[1994/12/01] + |\textcompwordmark| +\end{decl} + This command is used to separate letters which would normally + ligature. For example `f\textcompwordmark i' is produced with + |f\textcompwordmark i|. Note that the `f' and `i' have not + ligatured to produce `fi'. This is rarely useful in English + (`shelf\textcompwordmark ful' is a rare example of where it might be + used) but is used in languages such as German. + +\begin{decl}[1994/12/01] + |\textvisiblespace| +\end{decl} + This command produces a `visible space' character + `\textvisiblespace'. This is sometimes used in computer listings, + for example `type \textsf{hello\textvisiblespace world}'. + +\begin{decl}[1994/12/01] + |\textemdash| + |\textendash| + |\textexclamdown| + |\textquestiondown| \\ + |\textquotedblleft| + |\textquotedblright| + |\textquoteleft| + |\textquoteright| +\end{decl} + These commands produce characters which would otherwise be + accessed via ligatures: + \begin{center} + \begin{tabular}{ccl} + \emph{ligature} & \emph{character} & \emph{command} \\ + |---| & --- & |\textemdash| \\ + |--| & -- & |\textendash| \\ + |!`| & !` & |\textexclamdown| \\ + |?`| & ?` & |\textquestiondown| \\ + |``| & `` & |\textquotedblleft| \\ + |''| & '' & |\textquotedblright| \\ + |`| & ` & |\textquoteleft| \\ + |'| & ' & |\textquoteright| + \end{tabular} + \end{center} + The reason for making these characters directly accessible is so + that they will work in encodings which do not have these characters. + +\begin{decl}[1994/12/01] + |\textbullet| + |\textperiodcentered| +\end{decl} + These commands allow access to characters which were previously only + available in math mode: + \begin{center} + \begin{tabular}{lcl} + \emph{math command} & \emph{character} & \emph{text command} \\ + |\bullet| & $\bullet$ & |\textbullet| \\ + |\cdot| & $\cdot$ & |\textperiodcentered| + \end{tabular} + \end{center} + +\begin{decl}[1995/12/01] + |\textbackslash| + |\textbar| + |\textless| + |\textgreater| +\end{decl} + These commands allow access to ASCII characters which were + only available in verbatim or math mode: + \begin{center} + \begin{tabular}{lcl} + \emph{math command} & \emph{character} & \emph{text command} \\ + |\backslash| & $\backslash$ & |\textbackslash| \\ + |\mid| & $\mid$ & |\textbar| \\ + |<<| & $<$ & |\textless| \\ + |>>| & $>$ & |\textgreater| + \end{tabular} + \end{center} + +\begin{decl}[1995/12/01] + |\textasciicircum| + |\textasciitilde| +\end{decl} + These commands allow access to ASCII characters which were + previously only available in verbatim: + \begin{center} + \begin{tabular}{cl} + \emph{verbatim} & \emph{text command} \\ + |^| & |\textasciicircum| \\ + |~| & |\textasciitilde| + \end{tabular} + \end{center} + +\begin{decl}[1995/12/01] + |\textregistered| + |\texttrademark| +\end{decl} + These commands provide the `registered trademark' (R) and + `trademark' (TM) symbols. + +\subsection{Text commands: the T1 encoding} + +\NEWdescription{1994/12/01} + The |OT1| font encoding is fine for typesetting in English, but has + problems when typesetting other languages. The |T1| encoding solves + some of these problems, by providing extra characters (such as `eth' + and `thorn'), and it allows words containing accented letters to be + hyphenated (as long as you have a package like |babel| which allows + for non-American hyphenation). + + This section describes the commands you can use if you have the |T1| + fonts. To use them, you need to get the `ec fonts', or the + |T1|-encoded PostScript fonts, as used by \textsf{psnfss}. + All these fonts are + available by anonymous ftp in the Comprehensive \TeX{} Archive, and + are also available on the CD-ROMs \emph{4all \TeX} and + \emph{\TeX{} Live} (both available from the \TeX{} Users Group). + + You can then select the |T1| fonts by saying: +\begin{verbatim} + \usepackage[T1]{fontenc} +\end{verbatim} + This will allow you to use the commands in this section. + + \emph{Note:} Since this document must be processable on any site + running an up-to-date \LaTeX, it does not contain any characters + that are present only in |T1|-encoded fonts. This means that this + document cannot show you what these glyphs look like! If you want + to see them then run \LaTeX{} on the document |fontsmpl| and + respond `|cmr|' when it prompts you for a family name. + +\begin{decl}[1994/12/01] + |\k{<text>}| +\end{decl} + This command produces an `ogonek' accent. + +\begin{decl}[1994/12/01] + |\DH| + |\DJ| + |\NG| + |\TH| + |\dh| + |\dj| + |\ng| + |\th| +\end{decl} + These commands produce characters `eth', `dbar', `eng', and `thorn'. + +\begin{decl}[1994/12/01] + |\guillemotleft| + |\guillemotright| + |\guilsinglleft| + |\guilsinglright| \\ + |\quotedblbase| + |\quotesinglbase| + |\textquotedbl| +\end{decl} + % A local hack (could be improved): + \newcommand{\fauxguillemet}[1]{$\vcenter{\hbox{$\scriptscriptstyle#1$}}$} + These commands produce various sorts of quotation mark. + Rough representations of them are: + \fauxguillemet\ll a\fauxguillemet\gg{} + \fauxguillemet<a\fauxguillemet> + ,\kern -0.1em,\kern 0.05em a\kern -0.05em`` + ,\kern 0.05em a\kern -0.05em` and |"|a|"|. + +\NEWdescription{2001/06/01} + There are therefore some extra short-form ligatures available for + use in documents that will only be used with |T1|-encoded fonts. + + The guillemets |\guillemotleft| and |\guillemotright|% + \footnote{We apologise once again for maintaining Adobe's + enormous solipsism~(sic) of confusing a diving bird with + punctuation marks!} + can be obtained by typing |<<<<| and |>>>>| and |\quotedblbase| + by typing |,,|\,. + + Also, unlike the unexpected results with + |OT1|-encoded fonts, |<<| and |>>| will produce \textless{} and + \textgreater{}. + + Note also that the single character |"| will no longer produce '' + but rather |\textquotedbl|. + +\subsection{Logos} + +\begin{decl} +|\LaTeX|\\ +|\LaTeXe| +\end{decl} + +|\LaTeX| (producing `\LaTeX') is still the `main' logo command, +but if you need to refer to the new features, you can write +|\LaTeXe| (producing `\LaTeXe'). + +\subsection{Picture commands} + +\begin{decl} + |\qbezier[<N>](<AX>,<AY>)(<BX>,<BY>)(<CX>,<CY>)| \\ + | \bezier{<N>}(<AX>,<AY>)(<BX>,<BY>)(<CX>,<CY>)| +\end{decl} +The |\qbezier| command can be used in |picture| mode to draw a +quadratic Bezier curve from position |(<AX>,<AY>)| to |(<CX>,<CY>)| with +control point |(<BX>,<BY>)|. The optional argument \m{N} gives the +number of points on the curve. + +For example, the diagram: +\begin{center} + \begin{picture}(50,50) + \thicklines + \qbezier(0,0)(0,50)(50,50) + \qbezier[20](0,0)(50,0)(50,50) + \thinlines + \put(0,0){\line(1,1){50}} + \end{picture} +\end{center} +is drawn with: +\begin{verbatim} + \begin{picture}(50,50) + \thicklines + \qbezier(0,0)(0,50)(50,50) + \qbezier[20](0,0)(50,0)(50,50) + \thinlines + \put(0,0){\line(1,1){50}} + \end{picture} +\end{verbatim} +The |\bezier| command is the same, except that the argument \m{N} is not +optional. It is provided for compatibility with the \LaTeX~2.09 +|bezier| document style option. + +\subsection{Old commands} + +\begin{decl} +|\samepage| +\end{decl} + +The |\samepage| command still exists but is no longer being +maintained. +This is because it only ever worked erratically; it does not +guarantee that there will be no page-breaks within its scope; and +it can cause footnotes and marginals to be wrongly placed. + +We recommend using |\enlargethispage| in conjunction with page-break +commands such as |\newpage| and |\pagebreak| to help control page +breaks. + +\begin{decl} + |\SLiTeX| +\end{decl} +Since \SLiTeX{} no longer exists, the logo is no longer defined in the +\LaTeX{} kernel. A suitable replacement is |\textsc{Sli\TeX}|. The +\SLiTeX{} logo is defined in \LaTeX~2.09 compatibility mode. + +\begin{decl} +|\mho| |\Join| |\Box| |\Diamond| |\leadsto| \\ +|\sqsubset| |\sqsupset| |\lhd| |\unlhd| |\rhd| |\unrhd| +\end{decl} + +These symbols are contained in the \LaTeX{} symbol font, which was +automatically loaded by \LaTeX~2.09. However, \TeX{} has room for +only sixteen math font families; thus many users discovered that they +ran out. Because of this, \LaTeX{} does not load the \LaTeX{} symbol +font unless you use the \textsf{latexsym} package. + +These symbols are also made available, using different fonts, by the +\textsf{amsfonts} package, which also defines a large number of other +symbols. It is supplied by the American Mathematical Society. + +The \textsf{latexsym} package is loaded automatically in \LaTeX~2.09 +compatibility mode. + +\section{\LaTeX~2.09 documents} +\label{Sec:209} + +\LaTeXe{} can process (almost) any \LaTeX~2.09 document, by entering +\emph{\LaTeX~2.09 compatibility mode}. Nothing has changed, you run +\LaTeX{} in the same way you always did, and you will get much the +same results. + +The reason for the `almost' is that some \LaTeX~2.09 packages made use +of low-level unsupported features of \LaTeX. If you discover such a +package, you should find out if it has been updated to work with +\LaTeXe. Most packages will still work with \LaTeXe---the easiest way +to find out whether a package still works is to try it! + +\LaTeX~2.09 compatibility mode is a comprehensive emulation of +\LaTeX~2.09, but at the cost of time. Documents can run up to 50\% +slower in compatibility mode than they did under \LaTeX~2.09. +In addition, many of the new features of \LaTeXe{} are not available in +\LaTeX~2.09 compatibility mode. + +\subsection{Warning} + +\NEWdescription{1995/12/01} +This \emph{\LaTeX~2.09 compatibility mode} is provided solely to allow +you to process 2.09 documents, i.e.~documents that were written (we +hope, a long time ago) for a very old system and therefore could be +processed by using a genuine antique \LaTeX~2.09 system. + +This mode is therefore \emph{not} intended to provide access to the +enhanced features of \LaTeXe{}. Thus it must not be used to process +new documents which masquerade as 2.09 documents (i.e.~they begin with +|\documentstyle|) but which could not be processed using that genuine +antique \LaTeX~2.09 system because they contain some new, +\LaTeXe{}-only, commands or environments. + +To prevent such misuse of the system, and the consequent trouble it +causes when such misleadingly encoded documents are distributed, the +\emph{\LaTeX~2.09 compatibility mode} turns off most of these new +features and commands. Any attempt to use them will give you an error +message and, moreover, many of them simply will not work, whilst +others will produce unpredictable results. +So don't bother sending us any bug reports about such occurrences since +they are intentional. + + +\subsection{Font selection problems} +\label{Sec:fsprob} + +When using compatibility mode, it is possible that you will find +problems with font-changing commands in some old documents. These +problems are of two types: + +\begin{itemize} +\item producing error messages; +\item not producing the font changes you expected. +\end{itemize} + +In case of error messages it is possible that the document (or an old +style file used therein) contains references to old internal commands +which are no longer defined, see Section~\ref{Sec:oldinternals} for +more information if this is the case. + +\NEWdescription{1995/12/01} +One example of the unexpected is if you use one of the new style of +math-mode font changing command as follows: +\begin{verbatim} +$ \mathbf{xy} A $ +\end{verbatim} +You may well find that this behaves as if you had put: +\begin{verbatim} +$ \bf {xy} A $ +\end{verbatim} +everything including the $A$ coming out bold. + +\LaTeX~2.09 allowed sites to customize their \LaTeX{} installation, +which resulted in documents producing different results on different +\LaTeX{} installations. \LaTeXe{} no longer allows so much +customization but, for compatibility with old documents, the local +configuration file |latex209.cfg| is loaded every time \LaTeXe{} +enters \LaTeX~2.09 compatibility mode. + +For example, if your site was customized to use the New Font +Selection Scheme (\NFSS) with the |oldlfont| option, then you can +make \LaTeXe{} emulate this by creating a |latex209.cfg| file +containing the commands: +\begin{verbatim} +\ExecuteOptions{oldlfont}\RequirePackage{oldlfont} +\end{verbatim} +Similarly, to emulate \NFSS{} with the |newlfont| option, you can +create a |latex209.cfg| file containing: +\begin{verbatim} +\ExecuteOptions{newlfont}\RequirePackage{newlfont} +\end{verbatim} + + +\subsection{Native mode} +\label{Sec:native} + +To run an old document faster, and use the new features of +\LaTeXe, you should try using \emph{\LaTeXe{} native mode}. +This is done by replacing the command: +\begin{quote} + |\documentstyle[|\m{options}|,|\m{packages}|]|\arg{class} +\end{quote} +with: +\begin{quote} + |\documentclass|\oarg{options}\arg{class} \\ + |\usepackage{latexsym,|\m{packages}|}| +\end{quote} +However, some documents which can be processed in \LaTeX~2.09 +compatibility mode may not work in native mode. Some \LaTeX~2.09 +packages will only work with \LaTeXe{} in 2.09 compatibility mode. +Some documents will cause errors because of \LaTeXe's improved error +detection abilities. + +But most \LaTeX~2.09 documents can be processed by \LaTeXe{}'s native +mode with the above change. Again, the easiest way to find out +whether your documents can be processed in native mode is to try it! + + +\section{Local modifications} +\label{sec:loc} + +\NEWdescription{1995/12/01} +There are two common types of local modifications that can be done +very simply. Do not forget that documents produced using such +modifications will not be usable at other places (such documents are +called `non-portable'). + +One type of modification is the use of personal commands for commonly +used symbols or constructions. These should be put into a package +file (for example, one called \texttt{mymacros.sty}) and loaded by +putting |\usepackage{mymacros}| in the document preamble. + +Another type is a local document class that is very similar to one of +the standard classes but contains some straightforward modifications +such as extra environments, different values for some parameters, etc. +These should be put into a class file; here we shall describe a simple +method of constructing such a file using, as an example, a class +called \textsf{larticle} that is very similar to the \textsf{article} +class. + +\NEWfeature{1995/12/01} +The class file called \texttt{larticle.cls} should (after the +preliminary identification commands) start as follows: +\begin{verbatim} + \LoadClassWithOptions{article} +\end{verbatim} +This command should be followed by whatever additions and changes you +wish to make to the results of reading in the file +\texttt{article.sty}. + +The effect of using the above |\LoadClassWithOptions| command is to +load the standard class file \textsf{article} with whatever options +are asked for by the document. Thus a document using your +\textsf{larticle} class can specify any option that could be specified +when using the standard \textsf{article} class; for example: +\begin{verbatim} + \documentclass[a4paper,twocolumn,dvips]{larticle} +\end{verbatim} + + +\section{Problems} +\label{Sec:problems} + +This section describes some of the things which may go wrong when +using \LaTeXe, and what you can do about it. + +\subsection{New error messages} + +\LaTeXe{} has a number of new error messages. +Please also note that many error messages now produce further helpful +information if you press |h| in response to the error prompt. + +\begin{decl} +|Option clash for package |\m{package}|.| +\end{decl} +The named package has been loaded twice with different options. If +you enter |h| you will be told what the options were, for example, if +your document contained: +\begin{verbatim} + \usepackage[foo]{fred} + \usepackage[baz]{fred} +\end{verbatim} +then you will get the error message: +\begin{verbatim} + Option clash for package fred. +\end{verbatim} +and typing |h| at the |?| prompt will give you: +\begin{verbatim} + The package fred has already been loaded with options: + [foo] + There has now been an attempt to load it with options: + [baz] + Adding the line: + \usepackage[foo,baz]{fred} + to your document may fix this. + Try typing <<return>> to proceed. +\end{verbatim} +The cure is, as suggested, to load the package with both sets of +options. Note that since \LaTeX{} packages can call other packages, +it is possible to get a package option clash without explicitly +requesting the same package twice. + +\begin{decl} + |Command |\m{command}| not provided in base NFSS.| +\end{decl} +The \m{command} is not provided by default in \LaTeXe. This error is +generated by using one of the commands: +\begin{verbatim} + \mho \Join \Box \Diamond \leadsto + \sqsubset \sqsupset \lhd \unlhd \rhd \unrhd +\end{verbatim} +which are now part of the \textsf{latexsym} package. +The cure is to add: +\begin{verbatim} + \usepackage{latexsym} +\end{verbatim} +in the preamble of your document. + +\begin{decl} + |LaTeX2e command <command> in LaTeX 2.09 document.| +\end{decl} +The \m{command} is a \LaTeXe{} command but this is a \LaTeX~2.09 +document. The cure is to replace the command by a \LaTeX~2.09 +command, or to run document in native mode, as described in +Section~\ref{Sec:native}. + +\begin{decl} + |NFSS release 1 command \newmathalphabet found.| +\end{decl} +The command |\newmathalphabet| was used by the New Font Selection +Scheme Release 1 but it has now been replaced by +|\DeclareMathAlphabet|, the use of which is described in +\emph{\fntguide}. + +The best cure is to update the package which contained the +|\newmathalphabet| command. Find out if there is a new release of +the package, or (if you wrote the package yourself) consult +\emph{\fntguide} for the new syntax of font commands. + +If there is no updated version of the package then you can cure this +error by using the \textsf{newlfont} or \textsf{oldlfont} package, +which tells \LaTeX{} which version of |\newmathalphabet| should be +emulated. + +You should use \textsf{oldlfont} if the document selects math fonts with +syntax such as this: +\begin{quote} + |{\cal A}|, etc. +\end{quote} +Use \textsf{newlfont} if the document's syntax is like this: +\begin{quote} + |\cal{A}|, etc. +\end{quote} + + +\begin{decl} + |Text for \verb command ended by end of line.| +\end{decl} +The |\verb| command has been begun but not ended on that line. This +usually means that you have forgotten to put in the end-character of +the |\verb| command. + +\begin{decl} + |Illegal use of \verb command.| +\end{decl} +The |\verb| command has been used inside the argument of another +command. This has never been allowed in \LaTeX{}---often producing +incorrect output without any warning---and so \LaTeXe{} produces +an error message. + +\subsection{Old internal commands} +\label{Sec:oldinternals} + +A number of \LaTeX~2.09 internal commands have been removed, since +their functionality is now provided in a different way. See +\emph{\clsguide} for more details of the new, supported interface for +class and package writers. + +\begin{decl} + |\tenrm| |\elvrm| |\twlrm| \dots\\ + |\tenbf| |\elvbf| |\twlbf| \dots\\ + |\tensf| |\elvsf| |\twlsf| \dots\\ + $\vdots$ +\end{decl} +These commands provided access to the seventy fonts preloaded by +\LaTeX~2.09. In contrast, \LaTeXe{} normally preloads at most +fourteen fonts, which saves a lot of font memory; but a consequence is +that any \LaTeX{} file which used the above commands to directly +access fonts will no longer work. + +Their use will usually produce an error message such as: +\begin{verbatim} + ! Undefined control sequence. + l.5 \tenrm +\end{verbatim} +The cure for this is to update the document to use the new +font-changing commands provided by \LaTeXe; these are described in +\emph{\fntguide}. + +If this is not possible then, as a last resort, you can +use the \textsf{rawfonts} package, which loads the +seventy \LaTeX~2.09 fonts and provides direct access to them using the +old commands. This takes both time and memory. If you do not +wish to load all seventy fonts, you can select some of them by using the +|only| option to \textsf{rawfonts}. For example, to load only |tenrm| +and |tenbf| you write: +\begin{verbatim} + \usepackage[only,tenrm,tenbf]{rawfonts} +\end{verbatim} + +The \textsf{rawfonts} package is distributed as part of the \LaTeX{} +tools software, see Section~\ref{Sec:st-pack}. + +\subsection{Old files} + +One of the more common mistakes in running \LaTeX{} is to read in old +versions of packages instead of the new versions. If you get an +incomprehensible error message from a standard package, make sure you +are loading the most recent version of the package. You can find out +which version of the package has been loaded by looking in the log +file for a line like: +\begin{verbatim} + Package: fred 1994/06/01 v0.01 Fred's package. +\end{verbatim} +You can use the \m{release-date} options to |\documentclass| and +|\usepackage| to make sure that you are getting a suitably recent copy +of the document class or package. This is useful when sending a +document to another site, which may have out-of-date software. + +\subsection{Where to go for more help} + +If you can't find the answer for your problem here, try looking in +\emph{\LaTeXbook} or \emph{\LaTeXcomp}. If you have a problem with +installing \LaTeX, look in the installation guide files which come with +the distribution. + +If this doesn't help, contact your local \LaTeX{} guru or local +\LaTeX{} mailing list. + +If you think you've discovered a bug then please report it! First, +you should find out if the problem is with a third-party package or +class. If the problem is caused by a package or class other than +those listed in Section~\ref{Sec:class+packages} then please report +the problem to the author of the package or class, not to the \LaTeX3 +project team. + +If the bug really is with core \LaTeX{} then you should create a +\emph{short}, \emph{self-contained} document which exhibits the +problem. You should run a \emph{recent} (less than a year old) +version of \LaTeX{} on the file and then run \LaTeX{} on +|latexbug.tex|. This will create an error report which you should +send, together with the sample document and log file, to the +\LaTeX{} bugs address which can be found in the file +|latexbug.tex| or |bugs.txt|. + + +\section{Enjoy!} +\label{Sec:enjoy} + +We certainly hope you will enjoy using the new standard \LaTeX{} but, +if this is not possible, we hope that you will enjoy success and +fulfillment as a result of the documents which it will help you to +create. + +If you find that the contribution of \LaTeX{} to your life is such +that you would like to support the work of the project team, then +please read Section~\ref{Sec:ltx3} and discover practical ways to do +this. + +\begin{thebibliography}{1} + +\bibitem{A-W:GRM97} +Michel Goossens, Sebastian Rahtz and Frank Mittelbach. +\newblock {\em The {\LaTeX} Graphics Companion}. +\newblock Addison-Wesley, Reading, Massachusetts, 1997. + + +\bibitem{A-W:GR99} +Michel Goossens and Sebastian Rahtz. +\newblock {\em The {\LaTeX} Web Companion}. +\newblock Addison-Wesley, Reading, Massachusetts, 1999. + + +\bibitem{A-W:DEK91} +Donald~E. Knuth. +\newblock {\em The \TeX book}. +\newblock Addison-Wesley, Reading, Massachusetts, 1986. +\newblock Revised to cover \TeX3, 1991. + + +\bibitem{A-W:LLa94} +Leslie Lamport. +\newblock {\em {\LaTeX:} A Document Preparation System}. +\newblock Addison-Wesley, Reading, Massachusetts, second edition, 1994. + +\bibitem{A-W:MG2004} +Frank Mittelbach and Michel Goossens. +\newblock {\em The {\LaTeX} Companion second edition}. +\newblock With Johannes Braams, David Carlisle, and Chris Rowley. +\newblock Addison-Wesley, Reading, Massachusetts, 2004. + + +\end{thebibliography} + +\end{document} -- cgit v1.2.3