diff options
author | Karl Berry <karl@freefriends.org> | 2018-04-09 22:55:14 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2018-04-09 22:55:14 +0000 |
commit | 8332274ebd0d286768355471bc43f4041922f385 (patch) | |
tree | 58d4a7d5918a8c04375944120db7c37374f101c7 /Master/texmf-dist/doc/latex/latex2e-help-texinfo/latex2e.dbk | |
parent | 448102519c08a5f76c073e2e104066560a0bfefc (diff) |
latex2e-help-texinfo
git-svn-id: svn://tug.org/texlive/trunk@47419 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/latex2e-help-texinfo/latex2e.dbk')
-rw-r--r-- | Master/texmf-dist/doc/latex/latex2e-help-texinfo/latex2e.dbk | 3231 |
1 files changed, 2717 insertions, 514 deletions
diff --git a/Master/texmf-dist/doc/latex/latex2e-help-texinfo/latex2e.dbk b/Master/texmf-dist/doc/latex/latex2e-help-texinfo/latex2e.dbk index b282655c48e..e19d3d75c39 100644 --- a/Master/texmf-dist/doc/latex/latex2e-help-texinfo/latex2e.dbk +++ b/Master/texmf-dist/doc/latex/latex2e-help-texinfo/latex2e.dbk @@ -4,14 +4,15 @@ <!ENTITY latex "LaTeX"> ]> <book id="latex2e.dbk" lang="en"> -<title>&latex;2e unofficial reference manual (November 2016)</title> + + +<title>&latex;2e unofficial reference manual (March 2018)</title> <!-- %**end of header (This is for running Texinfo on a region.) --> <!-- latex 2.09 commands should all be present now, --> <!-- xx but latex2e stuff is missing. --> <!-- xx random list of a few of the missing items is at the end of this file --> <!-- --> -<!-- xx misc commands from clsguide.pdf --> <!-- xx ending a run with errors --> <!-- xx ctan, distributions, components of TeX --> <!-- xx classes and packages - required, additional, useful; oberdiek; fonts --> @@ -22,6 +23,7 @@ <!-- xx merge latex-manual from savannah --> <!-- xx merge display style math --> <!-- xx vertical mode, horizontal mode --> +<!-- xx JH Discuss restricted execution --> <!-- --> <!-- xx The typeset source2e has an index with all kernel --> <!-- xx commands, though some are internal and shouldn't be included. --> @@ -29,7 +31,7 @@ <!-- xx See also http://ctan.org/pkg/macros2e. --> <bookinfo><legalnotice><para>This document is an unofficial reference manual for &latex;, a -document preparation system, version of November 2016. +document preparation system, version of March 2018. </para> <para>This manual was originally translated from <filename>LATEX.HLP</filename> v1.0a in the VMS Help Library. The pre-translation version was written by @@ -44,7 +46,7 @@ Group as <citetitle>&tex;niques</citetitle> number 10), as reference material (n text was directly copied). </para> <para>Copyright 2007, 2008, 2009, 2010, 2011, 2012, 2013, -2014, 2015, 2016 Karl Berry. +2014, 2015, 2016, 2017, 2018 Karl Berry. Copyright 1988, 1994, 2007 Stephen Gilmore. @@ -68,7 +70,7 @@ into another language, under the above conditions for modified versions. <para>This document is an unofficial reference manual for &latex;, a -document preparation system, version of November 2016. +document preparation system, version of March 2018. </para> <para>This manual was originally translated from <filename>LATEX.HLP</filename> v1.0a in the VMS Help Library. The pre-translation version was written by @@ -83,7 +85,7 @@ Group as <citetitle>&tex;niques</citetitle> number 10), as reference material (n text was directly copied). </para> <para>Copyright 2007, 2008, 2009, 2010, 2011, 2012, 2013, -2014, 2015, 2016 Karl Berry. +2014, 2015, 2016, 2017, 2018 Karl Berry. Copyright 1988, 1994, 2007 Stephen Gilmore. @@ -109,12 +111,11 @@ into another language, under the above conditions for modified versions. <!-- Best Effort Symbol --> - <chapter label="" id="Top"> <title>&latex;2e: An unofficial reference manual</title> <para>This document is an unofficial reference manual (version of -November 2016) for &latex;2e, a document preparation system. +March 2018) for &latex;2e, a document preparation system. </para> @@ -122,31 +123,31 @@ November 2016) for &latex;2e, a document preparation system. <chapter label="1" id="About-this-document"> <title>About this document</title> -<indexterm role="cp"><primary>bug reporting</primary></indexterm> -<indexterm role="cp"><primary>reporting bugs</primary></indexterm> -<indexterm role="fn"><primary><ulink url="http://home.gna.org/latexrefman">http://home.gna.org/latexrefman</ulink> home page</primary></indexterm> +<indexterm role="fn"><primary><ulink url="http://puszcza.gnu.org.ua/software/latexrefman/">http://puszcza.gnu.org.ua/software/latexrefman/</ulink> home page</primary></indexterm> <para>This is an unofficial reference manual for the &latex;2e document preparation system, which is a macro package for the &tex; typesetting program (see <link linkend="Overview">Overview</link>). This document’s home page is -<ulink url="http://home.gna.org/latexrefman">http://home.gna.org/latexrefman</ulink>. That page has links to the +<ulink url="http://puszcza.gnu.org.ua/software/latexrefman/">http://puszcza.gnu.org.ua/software/latexrefman/</ulink>. That page has links to the current output in various formats, sources, mailing list archives and subscriptions, and other infrastructure. </para> <indexterm role="cp"><primary>&latex; vs. &latex;2e</primary></indexterm> <para>In this document, we will mostly just use ‘&latex;’ rather than ‘&latex;2e’, since the previous version of &latex; (2.09) was -retired many years ago. +frozen decades ago. </para> <indexterm role="cp"><primary>unofficial nature of this manual</primary></indexterm> <indexterm role="cp"><primary>&latex; Project team</primary></indexterm> -<indexterm role="fn"><primary><email>latexrefman-discuss@gna.org</email> email address</primary></indexterm> +<indexterm role="fn"><primary><email>latexrefman@tug.org</email> email address</primary></indexterm> <para>&latex; is currently maintained by a group of volunteers (<ulink url="http://latex-project.org">http://latex-project.org</ulink>). The official documentation written by the &latex; project is available from their web site. This document is completely unofficial and has not been reviewed by the &latex; -maintainers. Do not send bug reports or anything else about this -document to them. Instead, please send all comments to -<email>latexrefman-discuss@gna.org</email>. +maintainers. +<indexterm role="cp"><primary>bug reporting</primary></indexterm> +<indexterm role="cp"><primary>reporting bugs</primary></indexterm> +Do not send bug reports or anything else about this document to them. +Instead, please send all comments to <email>latexrefman@tug.org</email>. </para> <para>This document is a reference. There is a vast array of other sources of information about &latex;, at all levels. Here are a few @@ -162,8 +163,9 @@ introductions. </para> </listitem></varlistentry><varlistentry><term><ulink url="http://ctan.org/pkg/usrguide">http://ctan.org/pkg/usrguide</ulink> </term><listitem><indexterm role="fn"><primary>usrguide official documentation</primary></indexterm> -<para>The guide for document authors that is maintained as part of &latex;; -there are plenty of others available elsewhere. +<para>The guide for document authors that is maintained as part of &latex;. +Many other guides by many other people are also available, independent +of &latex; itself; one such is the next item: </para> </listitem></varlistentry><varlistentry><term><ulink url="http://ctan.org/pkg/lshort">http://ctan.org/pkg/lshort</ulink> </term><listitem><indexterm role="fn"><primary>lshort document</primary></indexterm> @@ -438,7 +440,8 @@ commands it covers (barring unintentional omissions, a.k.a. bugs). </para> -<anchor id="Environment"/> +<sect2 label="2.4.1" id="Environment"> +<title>Environments</title> <para>Synopsis: </para> @@ -472,14 +475,18 @@ required (it specifies the formatting of columns). \end{tabular} </screen> -<anchor id="Declaration"/> +</sect2> +<sect2 label="2.4.2" id="Declaration"> +<title>Command declarations</title> <para>A command that changes the value, or changes the meaning, of some other command or parameter. For instance, the <literal>\mainmatter</literal> command changes the setting of page numbers from roman numerals to arabic. </para> -<anchor id="_005cmakeatletter-and-_005cmakeatother"/> +</sect2> +<sect2 label="2.4.3" id="_005cmakeatletter-and-_005cmakeatother"> +<title><literal>\makeatletter</literal> and <literal>\makeatother</literal></title> <para>Synopsis: </para> @@ -497,7 +504,7 @@ character category code, or <indexterm role="cp"><primary>catcode</primary></indexterm> <indexterm role="cp"><primary>character category code</primary></indexterm> <indexterm role="cp"><primary>category code, character</primary></indexterm> -<firstterm>catcode</firstterm> for shorter. For instance, the backslash <literal>\</literal> is +<firstterm>catcode</firstterm> for short. For instance, the backslash <literal>\</literal> is assigned the catcode 0, for characters that start a command. These two commands alter the catcode assigned to <literal>@</literal>. </para> @@ -511,36 +518,96 @@ So under the default category codes, user-defined commands cannot contain an <literal>@</literal>. But <literal>\makeatletter</literal> and <literal>\makeatother</literal> allow users to define or redefine commands named with <literal>@</literal>. </para> -<para>Use these inside a <filename>.tex</filename> file, in the preamble. Don’t use them -inside <filename>.sty</filename> or <filename>.cls</filename> files since the <literal>\usepackage</literal> -and <literal>\documentclass</literal> commands set the at sign to have the character -code of a letter. +<para>Use these two commands inside a <filename>.tex</filename> file, in the preamble, when +defining or redefining a command with <literal>@</literal> in its name. Don’t use +them inside <filename>.sty</filename> or <filename>.cls</filename> files since the +<literal>\usepackage</literal> and <literal>\documentclass</literal> commands set the at sign to +have the character code of a letter. </para> <indexterm role="cp"><primary>package, <literal>macros2e</literal></primary></indexterm> -<indexterm role="cp"><primary><literal>macros2e</literal> package For a comprehensive list of macros with an at-sign</primary></indexterm> -<para>in their names, see document -<ulink url="http://ctan.org/pkg/macros2e">http://ctan.org/pkg/macros2e</ulink>. These macros are mainly useful -to package or class authors; examples that may be useful to document -authors are provided hereinafter. -</para> -<para>The example code below, if put in the preamble, redefines the -section command to center the section title, put it in bold type, -and adjust the spacing. -</para> -<!-- xxx TODO, make \@startsection a separate node, see latex2e-fr.texi --> -<!-- From http://zoonek.free.fr/LaTeX/LaTeX_samples_section/0.html --> +<indexterm role="cp"><primary><literal>macros2e</literal> package</primary></indexterm> + +<para>For a comprehensive list of macros with an at-sign +in their names see <ulink url="http://ctan.org/pkg/macros2e">http://ctan.org/pkg/macros2e</ulink>. These macros are +mainly intended to package or class authors. +</para> +<para>The example below is typical. In the user’s class file is a command +<literal>\thesis@universityname</literal>. The user wants to change the +definition. These three lines should go in the preamble, before the +<literal>\begin{document}</literal>. +</para> <screen>\makeatletter -\renewcommand\section{% - \@startsection{section}% Name - {1}% Level: 0=part, 1=chapter, etc. - {0pt}% Heading indent - {-3.5ex plus -1ex minus -.2ex}% Beforeskip (if neg, no head indent) - {2.3ex plus.2ex}% Afterskip (if neg, run-in heading) - {\centering\normalfont\Large\bfseries}} % Style of head +\renewcommand{\thesis@universityname}{Saint Michael's College} \makeatother </screen> -<!-- xx TODO document \@ifstar, see latex2e-fr.texi --> + +<sect3 label="2.4.3.1" id="_005c_0040ifstar"> +<title><literal>\@ifstar</literal></title> + +<indexterm role="fn"><primary>\@ifstar</primary></indexterm> +<indexterm role="cp"><primary>commands, star-variants</primary></indexterm> +<indexterm role="cp"><primary>star-variants, commands</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\newcommand{\mycmd}{\@ifstar{\mycmd@star}{\mycmd@nostar}} +\newcommand{\mycmd@nostar}[<replaceable>non-starred command number of args</replaceable>]{<replaceable>body of non-starred command</replaceable>} +\newcommand{\mycmd@star}[<replaceable>starred command number of args</replaceable>]{<replaceable>body of starred command</replaceable>} +</screen> +<para>Many standard &latex; environments or commands have a variant with the +same name but ending with a star character <literal>*</literal>, an asterisk. +Examples are the <literal>table</literal> and <literal>table*</literal> environments and the +<literal>\section</literal> and <literal>\section*</literal> commands. +</para> +<para>When defining environments, following this pattern is straightforward +because <literal>\newenvironment</literal> and <literal>\renewenvironment</literal> allow the +environment name to contain a star. For commands the situation is more +complex. As in the synopsis above, there will be a user-called command, +given above as <literal>\mycmd</literal>, which peeks ahead to see if it is followed +by a star. For instance, &latex; does not really have a +<literal>\section*</literal> command; instead, the <literal>\section</literal> command peeks +ahead. This command does not accept arguments but instead expands to +one of two commands that do accept arguments. In the synopsis these two +are <literal>\mycmd@nostar</literal> and <literal>\mycmd@star</literal>. They could take the +same number of arguments or a different number, or no arguments at all. +As always, in a &latex; document a command using at-sign <literal>@</literal> +must be enclosed inside a <literal>\makeatletter ... \makeatother</literal> block +(see <link linkend="_005cmakeatletter-and-_005cmakeatother">\makeatletter and \makeatother</link>). +</para> +<para>This example of <literal>\@ifstar</literal> defines the command <literal>\ciel</literal> and a +variant <literal>\ciel*</literal>. Both have one required argument. A call to +<literal>\ciel{night}</literal> will return "starry night sky" while +<literal>\ciel*{blue}</literal> will return "starry not blue sky". +</para> +<screen>\newcommand*{\ciel@unstarred}[1]{starry #1 sky} +\newcommand*{\ciel@starred}[1]{starry not #1 sky} +\newcommand*{\ciel}{\@ifstar{\ciel@starred}{\ciel@unstarred}} +</screen> +<para>In the next example, the starred variant takes a different number of +arguments than does the unstarred one. With this definition, Agent +007’s <literal>``My name is \agentsecret*{Bond}, +\agentsecret{James}{Bond}.''</literal> is equivalent to <literal>``My name is +\textsc{Bond}, \textit{James} textsc{Bond}.''</literal> +</para> +<screen>\newcommand*{\agentsecret@unstarred}[2]{\textit{#1} \textsc{#2}} +\newcommand*{\agentsecret@starred}[1]{\textsc{#1}} +\newcommand*{\agentsecret}{\@ifstar{\agentsecret@starred}{\agentsecret@unstarred}} +</screen> +<para>There are two sometimes more convenient ways to accomplish the work of +<literal>\@ifstar</literal>. The <filename>suffix</filename> package allows the construct +<literal>\newcommand\mycommand{<replaceable>unstarred version</replaceable>}</literal> followed by +<literal>\WithSuffix\newcommand\mycommand*{<replaceable>starred version</replaceable>}</literal>. And +&latex;3 has the <filename>xparse</filename> package that allows this code. +</para> +<screen>\NewDocumentCommand\foo{s}{\IfBooleanTF#1 + {<replaceable>starred version</replaceable>}% + {<replaceable>unstarred version</replaceable>}% + } +</screen> + +</sect3> +</sect2> </sect1> </chapter> <chapter label="3" id="Document-classes"> @@ -645,12 +712,16 @@ size (these show height by width): <indexterm role="fn"><primary>\pdfpageheight</primary></indexterm> <indexterm role="cp"><primary>package, <literal>geometry</literal></primary></indexterm> <indexterm role="cp"><primary><literal>geometry</literal> package</primary></indexterm> + <para>When using one of the engines pdf&latex;, Lua&latex;, or Xe&latex; (see <link linkend="TeX-engines">&tex; engines</link>), options other than <literal>letterpaper</literal> set the print area but you must also set the physical paper size. One way to do that is to put <literal>\pdfpagewidth=\paperwidth</literal> and -<literal>\pdfpageheight=\paperheight</literal> in your document’s preamble. The -<literal>geometry</literal> package provides flexible ways of setting the print +<literal>\pdfpageheight=\paperheight</literal> in your document’s preamble. +<indexterm role="cp"><primary>package, <literal>geometry</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>geometry</literal> package</primary></indexterm> +</para> +<para>The <literal>geometry</literal> package provides flexible ways of setting the print area and physical page size. </para> <indexterm role="fn"><primary>draft option</primary></indexterm> @@ -781,14 +852,14 @@ SMC Math Department</literal> is for a class. <indexterm role="cp"><primary>difference between class and package</primary></indexterm> </para> <para>Inside of a class or package file you can use the at-sign <literal>@</literal> as a -character in command names without having to surround that command with -<literal>\makeatletter</literal> and <literal>\makeatother</literal>. See <link linkend="_005cmakeatletter-and-_005cmakeatother">\makeatletter and -\makeatother</link>. This allow you to create commands that users will not -accidentally redefine. Another technique is to preface class- or -package-specific commands with some string to prevent your class or -package from interacting with others. For instance, the class -<literal>smcmemo</literal> might have commands <literal>\smc@tolist</literal>, -<literal>\smc@fromlist</literal>, etc. +character in command names without having to surround the code +containing that command with <literal>\makeatletter</literal> and +<literal>\makeatother</literal>. See <link linkend="_005cmakeatletter-and-_005cmakeatother">\makeatletter and \makeatother</link>. This allow +you to create commands that users will not accidentally redefine. +Another technique is to preface class- or package-specific commands with +some string to prevent your class or package from interfering with +others. For instance, the class <literal>smcmemo</literal> might have commands +<literal>\smc@tolist</literal>, <literal>\smc@fromlist</literal>, etc. </para> @@ -804,29 +875,32 @@ package from interacting with others. For instance, the class <indexterm role="cp"><primary>class options</primary></indexterm> <indexterm role="cp"><primary>package options</primary></indexterm> -<para>A class file or package file typically has four parts. (1) In the -identification part, the file says that it is a &latex; package or -class and describes itself, using the <literal>\NeedsTeXFormat</literal> and -<literal>\ProvidesClass</literal> or <literal>\ProvidesPackage</literal> commands. (2) The -preliminary declarations part declares some commands and can also load -other files. Usually these commands will be those needed for the code -used in the next part. For example, an <literal>smcmemo</literal> class might be -called with an option to read in a file with a list of people for the -to-head, as <literal>\documentclass[mathto]{smcmemo}</literal>, and therefore -needs to define a command +<para>A class file or package file typically has four parts. +</para><orderedlist numeration="arabic"><para>In the <firstterm>identification part</firstterm>, the file says that it is a &latex; +package or class and describes itself, using the <literal>\NeedsTeXFormat</literal> +and <literal>\ProvidesClass</literal> or <literal>\ProvidesPackage</literal> commands. +</para><listitem><para>The <firstterm>preliminary declarations part</firstterm> declares some commands and +can also load other files. Usually these commands will be those needed +for the code used in the next part. For example, an <literal>smcmemo</literal> +class might be called with an option to read in a file with a list of +people for the to-head, as <literal>\documentclass[mathto]{smcmemo}</literal>, and +therefore needs to define a command <literal>\newcommand{\setto}[1]{\def\@tolist{#1}}</literal> used in that -file. (3) In the handle options part the class or package declares +file. +</para></listitem><listitem><para>In the <firstterm>handle options part</firstterm> the class or package declares and processes its options. Class options allow a user to start their document as <literal>\documentclass[<replaceable>option list</replaceable>]{<replaceable>class name</replaceable>}</literal>, to modify the behavior of the class. An example is when you declare <literal>\documentclass[11pt]{article}</literal> to set the default -document font size. Finally, (4) in the more declarations part the -class or package usually does most of its work: declaring new variables, -commands and fonts, and loading other files. -</para> -<para>Here is a starting class file, which should be saved as <literal>stub.cls</literal> +document font size. +</para></listitem><listitem><para>Finally, in the <firstterm>more declarations part</firstterm> the class or package usually does +most of its work: declaring new variables, commands and fonts, and +loading other files. +</para></listitem></orderedlist> + +<para>Here is a starting class file, which should be saved as <filename>stub.cls</filename> where &latex; can find it, for example in the same directory as the -<literal>.tex</literal> file. +<filename>.tex</filename> file. </para> <screen>\NeedsTeXFormat{LaTeX2e} \ProvidesClass{stub}[2017/07/06 stub to start building classes from] @@ -855,7 +929,7 @@ of the descriptions here derive from this document), or the tutorial </para> <variablelist><varlistentry><term><literal>\AtBeginDvi{specials}</literal> </term><listitem><indexterm role="fn"><primary>\AtBeginDvi</primary></indexterm> -<para>Save in a box register things that are written to the <literal>.dvi</literal> file +<para>Save in a box register things that are written to the <filename>.dvi</filename> file at the beginning of the shipout of the first page of the document. </para> </listitem></varlistentry><varlistentry><term><literal>\AtEndOfClass{<replaceable>code</replaceable>}</literal> @@ -867,6 +941,22 @@ processing the current class or package. You can use these hooks multiple times; the <literal>code</literal> will be executed in the order that you called it. See also <link linkend="_005cAtBeginDocument">\AtBeginDocument</link>. </para> +</listitem></varlistentry><varlistentry><term><literal>\CheckCommand{<replaceable>cmd</replaceable>}[<replaceable>num</replaceable>][<replaceable>default</replaceable>]{<replaceable>definition</replaceable>}</literal> +</term></varlistentry><varlistentry><term><literal>\CheckCommand*{<replaceable>cmd</replaceable>}[<replaceable>num</replaceable>][<replaceable>default</replaceable>]{<replaceable>definition</replaceable>}</literal> +</term><listitem><indexterm role="fn"><primary>\CheckCommand</primary></indexterm> +<indexterm role="fn"><primary>\CheckCommand*</primary></indexterm> +<indexterm role="cp"><primary>new command, check</primary></indexterm> +<para>Like <literal>\newcommand</literal> (see <link linkend="_005cnewcommand-_0026-_005crenewcommand">\newcommand & \renewcommand</link>) but does +not define <replaceable>cmd</replaceable>; instead it checks that the current definition of +<replaceable>cmd</replaceable> is exactly as given by <replaceable>definition</replaceable> and is or is not +<indexterm role="cp"><primary>long command</primary></indexterm> +<firstterm>long</firstterm> as expected. A long command is a command that accepts +<literal>\par</literal> within an argument. The <replaceable>cmd</replaceable> command is expected to be +long with the unstarred version of <literal>\CheckCommand</literal>. Raises an +error when the check fails. This allows you to check before you start +redefining <literal>cmd</literal> yourself that no other package has already +redefined this command. +</para> </listitem></varlistentry><varlistentry><term><literal>\ClassError{<replaceable>class name</replaceable>}{<replaceable>error text</replaceable>}{<replaceable>help text</replaceable>}</literal> </term></varlistentry><varlistentry><term><literal>\PackageError{<replaceable>package name</replaceable>}{<replaceable>error text</replaceable>}{<replaceable>help text</replaceable>}</literal> </term></varlistentry><varlistentry><term><literal>\ClassWarning{<replaceable>class name</replaceable>}{<replaceable>warning text</replaceable>}</literal> @@ -902,8 +992,9 @@ message, while the other versions do show that number. </para> <para>To format the messages, including the <replaceable>help text</replaceable>: use <literal>\protect</literal> to stop a command from expanding, get a line break with -<literal>\MessageBreak</literal>, and get a space with <literal>\space</literal>. Note that -&latex; appends a period to the messages. +<literal>\MessageBreak</literal>, and get a space with <literal>\space</literal> when a space +character does not allow it, like after a command. Note that &latex; +appends a period to the messages. </para> </listitem></varlistentry><varlistentry><term><literal>\CurrentOption</literal> </term><listitem><indexterm role="fn"><primary>\CurrentOption</primary></indexterm> @@ -912,7 +1003,7 @@ be used within the <replaceable>code</replaceable> argument of either <literal>\ or <literal>\DeclareOption*</literal>. </para> </listitem></varlistentry><varlistentry><term><literal>\DeclareOption{<replaceable>option</replaceable>}{<replaceable>code</replaceable>}</literal> -</term></varlistentry><varlistentry><term><literal>\DeclareOption*{<replaceable>option</replaceable>}{<replaceable>code</replaceable>}</literal> +</term></varlistentry><varlistentry><term><literal>\DeclareOption*{<replaceable>code</replaceable>}</literal> </term><listitem><indexterm role="fn"><primary>\DeclareOption</primary></indexterm> <indexterm role="fn"><primary>\DeclareOption*</primary></indexterm> <indexterm role="cp"><primary>class options</primary></indexterm> @@ -947,16 +1038,54 @@ passes the option to the <literal>article</literal> class. <screen>\DeclareOption*{\InputIfFileExists{\CurrentOption.memo}{}{% \PassOptionsToClass{\CurrentOption}{article}}} </screen> +</listitem></varlistentry><varlistentry><term><literal>\DeclareRobustCommand{<replaceable>cmd</replaceable>}[<replaceable>num</replaceable>][<replaceable>default</replaceable>]{<replaceable>definition</replaceable>}</literal> +</term></varlistentry><varlistentry><term><literal>\DeclareRobustCommand*{<replaceable>cmd</replaceable>}[<replaceable>num</replaceable>][<replaceable>default</replaceable>]{<replaceable>definition</replaceable>}</literal> +</term><listitem><indexterm role="fn"><primary>\DeclareRobustCommand</primary></indexterm> +<indexterm role="fn"><primary>\DeclareRobustCommand*</primary></indexterm> +<indexterm role="cp"><primary>new command, definition</primary></indexterm> +<para>Like <literal>\newcommand</literal> and <literal>\newcommand*</literal> (see <link linkend="_005cnewcommand-_0026-_005crenewcommand">\newcommand & +\renewcommand</link>) but these declare a robust command, even if some code +within the <replaceable>definition</replaceable> is fragile. (For a discussion of robust and +fragile commands see <link linkend="_005cprotect">\protect</link>.) Use this command to define new +robust commands or to redefine existing commands and make them +robust. Unlike <literal>\newcommand</literal> these do not give an error if macro +<replaceable>cmd</replaceable> already exists; instead, a log message is put into the +transcript file if a command is redefined. +</para> +<para>Commands defined this way are a bit less efficient than those defined +using <literal>\newcommand</literal> so unless the command’s data is fragile and the +command is used within a moving argument, use <literal>\newcommand</literal>. +</para> +<indexterm role="cp"><primary>package, <literal>etoolbox</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>etoolbox</literal> package</primary></indexterm> + +<para>The <literal>etoolbox</literal> package offers commands <literal>\newrobustcmd</literal>, +<literal>\newrobustcmd*</literal>, <literal>\renewrobustcmd</literal>, <literal>\renewrobustcmd*</literal>, +<literal>\providerobustcmd</literal>, and <literal>\providerobustcmd*</literal> which are similar +to <literal>\newcommand</literal>, <literal>\newcommand*</literal>, <literal>\renewcommand</literal>, +<literal>\renewcommand*</literal>, <literal>\providecommand</literal>, and +<literal>\providecommand*</literal>, but define a robust <replaceable>cmd</replaceable> with two advantages +as compared to <literal>\DeclareRobustCommand</literal>: +</para><orderedlist numeration="arabic"><listitem><para>They use the low-level e-&tex; protection mechanism rather than the +higher level &latex; <literal>\protect</literal> mechanism, so they do not incur +the slight loss of performance mentioned above, and +</para></listitem><listitem><para>They make the same distinction between <literal>\new…</literal>, +<literal>\renew…</literal>, and <literal>\provide…</literal>, as the standard +commands, so they do not just make a log message when you redefine +<replaceable>cmd</replaceable> that already exists, in that case you need to use either +<literal>\renew…</literal> or <literal>\provide…</literal> or you get an error. +</para></listitem></orderedlist> + </listitem></varlistentry><varlistentry><term><literal>\IfFileExists{<replaceable>file name</replaceable>}{<replaceable>true code</replaceable>}{<replaceable>false code</replaceable>}</literal> </term></varlistentry><varlistentry><term><literal>\InputIfFileExists{<replaceable>file name</replaceable>}{<replaceable>true code</replaceable>}{<replaceable>false code</replaceable>}</literal> </term><listitem><indexterm role="fn"><primary>\IfFileExists</primary></indexterm> <indexterm role="fn"><primary>\InputIfFileExists</primary></indexterm> -<para>Execute <replaceable>true code</replaceable> if &latex; can find the file and <replaceable>false -code</replaceable> otherwise. In the second case it inputs the file immediately -after executing <replaceable>true code</replaceable>. Thus +<para>Execute <replaceable>true code</replaceable> if &latex; can find the file <filename><replaceable>file +name</replaceable></filename> and <replaceable>false code</replaceable> otherwise. In the second case it inputs the +file immediately after executing <replaceable>true code</replaceable>. Thus <literal>\IfFileExists{img.pdf}{\includegraphics{img.pdf}}{\typeout{WARNING: -img.pdf not found}}</literal> will include the graphic if it is found but -otherwise just give a warning. +img.pdf not found}}</literal> will include the graphic <filename>img.pdf</filename> if it is +found but otherwise just give a warning. </para> <para>This command looks for the file in all search paths that &latex; uses, not only in the current directory. To look only in the current @@ -976,7 +1105,12 @@ list</replaceable>]{<replaceable>class name</replaceable>}[<replaceable>release </para> <para>The <replaceable>options list</replaceable>, if present, is a comma-separated list. The <replaceable>release date</replaceable> is optional. If present it must have the form -<replaceable>YYYY/MM/DD</replaceable>. If you request a <replaceable>release date</replaceable> and the date of +<replaceable>YYYY/MM/DD</replaceable>. +<!-- BTW, there are at-macros documented in macros2e.pdf to check the version --> +<!-- and do some actions conditionnally on version later or not to some --> +<!-- date. --> +</para> +<para>If you request a <replaceable>release date</replaceable> and the date of the package installed on your system is earlier, then you get a warning on the screen and in the log like <literal>You have requested, on input line 4, version `2038/01/19' of document class article, but only version @@ -990,8 +1124,8 @@ that lets you build classes on existing ones, such as the standard </para> </listitem></varlistentry><varlistentry><term><literal>\ExecuteOptions{<replaceable>options-list</replaceable>}</literal> </term><listitem><indexterm role="fn"><primary>\ExecuteOptions</primary></indexterm> -<para>For each option in the <replaceable>options-list</replaceable>, in order, this command -executes the command <literal>\ds@</literal><replaceable>option</replaceable>. If this command is not +<para>For each option <replaceable>option</replaceable> in the <replaceable>options-list</replaceable>, in order, this command +executes the command <literal>\ds@<replaceable>option</replaceable></literal>. If this command is not defined then that option is silently ignored. </para> <para>It can be used to provide a default option list before @@ -1001,13 +1135,13 @@ default to be 11pt fonts then you could specify </para> </listitem></varlistentry><varlistentry><term><literal>\NeedsTeXFormat{<replaceable>format</replaceable>}[<replaceable>format date</replaceable>]</literal> </term><listitem><indexterm role="fn"><primary>\NeedsTeXFormat</primary></indexterm> -<para>Specifies the format that this class should be run under. Often issued +<para>Specifies the format that this class must be run under. Often issued as the first line of a class file, and most often used as: -<literal>\NeedsTeXFormat{LaTeX2e}</literal>. The format that you specify must -exactly match the one installed on your system that you invoked, -including that the string is case sensitive. If it does not match then -execution stops with an error like ‘<literal>This file needs format `xxx' -but this is `LaTeX2e'.</literal>’ +<literal>\NeedsTeXFormat{LaTeX2e}</literal>. When a document using that class is +processed, the format name given here must match the format that is +actually being run (including that the <replaceable>format</replaceable> string is case +sensitive). If it does not match then execution stops with an error +like ‘<literal>This file needs format `LaTeX2e' but this is `xxx'.</literal>’ </para> <para>To specify a version of the format that you know to have certain features, include the optional <replaceable>format date</replaceable> on which those features @@ -1015,8 +1149,7 @@ were implemented. If present it must be in the form <literal>YYYY/MM/DD</litera If the format version installed on your system is earlier than <replaceable>format date</replaceable> then you get a warning like ‘<literal>You have requested release `2038/01/20' of LaTeX, but only release `2016/02/01' is -available.</literal>’ (The &latex; kernel has been frozen for many years so you -probably do not not need to specify the format date.) +available.</literal>’ </para> </listitem></varlistentry><varlistentry><term><literal>\OptionNotUsed</literal> </term><listitem><indexterm role="fn"><primary>\OptionNotUsed</primary></indexterm> @@ -1030,8 +1163,8 @@ within the <replaceable>code</replaceable> argument of either <literal>\DeclareO <!-- option(s): [unusedoption].} with the list of not-used options when it --> <!-- reaches @code{\begin@{document@}}. --> -</listitem></varlistentry><varlistentry><term><literal>\PassOptionsToClass{<replaceable>options list</replaceable>}{<replaceable>class name</replaceable>}</literal> -</term></varlistentry><varlistentry><term><literal>\PassOptionsToPackage{<replaceable>options list</replaceable>}{<replaceable>package name</replaceable>}</literal> +</listitem></varlistentry><varlistentry><term><literal>\PassOptionsToClass{<replaceable>option list</replaceable>}{<replaceable>class name</replaceable>}</literal> +</term></varlistentry><varlistentry><term><literal>\PassOptionsToPackage{<replaceable>option list</replaceable>}{<replaceable>package name</replaceable>}</literal> </term><listitem><indexterm role="fn"><primary>\PassOptionsToClass</primary></indexterm> <indexterm role="fn"><primary>\PassOptionsToPackage</primary></indexterm> <para>Adds the options in the comma-separated list <replaceable>option list</replaceable> to the @@ -1045,16 +1178,17 @@ more than once will get you an error like <literal>Option clash for package foo.</literal> (&latex; throws an error even if there is no conflict between the options.) </para> -<para>If your code is bringing in a package twice then you can collapse that -to once, for example replacing the two +<para>If your own code is bringing in a package twice then you can collapse +that to once, for example replacing the two <literal>\RequirePackage[landscape]{geometry}\RequirePackage[margins=1in]{geometry}</literal> with the single <literal>\RequirePackage[landscape,margins=1in]{geometry}</literal>. But if you are loading a package that in turn loads another package then you need -to queue up the options you desire. For instance, suppose the package -<literal>foo</literal> loads the package <literal>geometry</literal>. Instead of <literal> -\RequirePackage{foo}\RequirePackage[draft]{graphics}</literal> you must write -<literal>\PassOptionsToPackage{draft}{graphics} +to queue up the options you desire for this other package. For +instance, suppose the package <literal>foo</literal> loads the package +<literal>geometry</literal>. Instead of +<literal>\RequirePackage{foo}\RequirePackage[draft]{graphics}</literal> you must +write <literal>\PassOptionsToPackage{draft}{graphics} \RequirePackage{foo}</literal>. (If <literal>foo.sty</literal> loads an option in conflict with what you want then you may have to look into altering its source.) </para> @@ -1073,66 +1207,70 @@ option. The user could start their &latex; file with in the class file as <literal>\ProcessOptions\relax</literal> (because of the existence of the starred command). </para> -<para>Options come in two types. ‘Local’ options have been specified for this +<para>Options come in two types. <firstterm>Local options</firstterm> have been specified for this particular package in the <replaceable>options</replaceable> argument of <literal>\PassOptionsToPackage{<replaceable>options</replaceable>}</literal>, <literal>\usepackage[<replaceable>options</replaceable>]</literal>, or -<literal>\RequirePackage[<replaceable>options</replaceable>]</literal>. ‘Global’ options are those given +<literal>\RequirePackage[<replaceable>options</replaceable>]</literal>. <firstterm>Global options</firstterm> are those given by the class user in <literal>\documentclass[<replaceable>options</replaceable>]</literal> (If an option is specified both locally and globally then it is local.) </para> -<para>When <literal>\ProcessOptions</literal> is called for a package <literal>pkg.sty</literal>, the -following happens. (1) For each option <replaceable>option</replaceable> so far declared +<para>When <literal>\ProcessOptions</literal> is called for a package <filename>pkg.sty</filename>, the +following happens: +</para><orderedlist numeration="arabic"><listitem><para>For each option <replaceable>option</replaceable> so far declared with <literal>\DeclareOption</literal>, it looks to see if that option is either a global or a local option for <literal>pkg</literal>. If so then it executes the declared code. This is done in the order in which these options were -given in <literal>pkg.sty</literal>. (2) For each remaining local option, it -executes the command <literal>\ds@</literal><replaceable>option</replaceable> if it has been defined -somewhere (other than by a <literal>\DeclareOption</literal>); otherwise, it -executes the default option code given in <literal>\DeclareOption*</literal>. If no -default option code has been declared then it gives an error message. -This is done in the order in which these options were specified. -</para> +given in <filename>pkg.sty</filename>. +</para></listitem><listitem><para>For each remaining local option, it executes the command +<literal>\ds@</literal><replaceable>option</replaceable> if it has been defined somewhere (other than by +a <literal>\DeclareOption</literal>); otherwise, it executes the default option code +given in <literal>\DeclareOption*</literal>. If no default option code has been +declared then it gives an error message. This is done in the order in +which these options were specified. +</para></listitem></orderedlist> <para>When <literal>\ProcessOptions</literal> is called for a class it works in the same -way except that all options are local, and the default value for +way except that all options are local, and the default <replaceable>code</replaceable> for <literal>\DeclareOption*</literal> is <literal>\OptionNotUsed</literal> rather than an error. </para> -<para>The starred version <literal>\ProcessOptions*</literal><replaceable>\@options</replaceable> executes the +<para>The starred version <literal>\ProcessOptions*</literal> 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. </para> -</listitem></varlistentry><varlistentry><term><literal>\ProvidesClass{<replaceable>class name</replaceable>}[<replaceable><release date></replaceable> <replaceable><brief additional information></replaceable>]</literal> -</term></varlistentry><varlistentry><term><literal>\ProvidesPackage{<replaceable>package name</replaceable>}[<replaceable><release date></replaceable> <replaceable><brief additional information></replaceable>]</literal> +</listitem></varlistentry><varlistentry><term><literal>\ProvidesClass{<replaceable>class name</replaceable>}[<replaceable>release date</replaceable> <replaceable>brief additional information</replaceable>]</literal> +</term></varlistentry><varlistentry><term><literal>\ProvidesClass{<replaceable>class name</replaceable>}[<replaceable>release date</replaceable>]</literal> +</term></varlistentry><varlistentry><term><literal>\ProvidesPackage{<replaceable>package name</replaceable>}[<replaceable>release date</replaceable> <replaceable>brief additional information</replaceable>]</literal> +</term></varlistentry><varlistentry><term><literal>\ProvidesPackage{<replaceable>package name</replaceable>}[<replaceable>release date</replaceable>]</literal> </term><listitem><indexterm role="fn"><primary>\ProvidesClass</primary></indexterm> <indexterm role="fn"><primary>\ProvidesPackage</primary></indexterm> <para>Identifies the class or package, printing a message to the screen and the log file. </para> <para>When a user writes <literal>\documentclass{smcmemo}</literal> then &latex; loads -the file <literal>smcmemo.cls</literal>. Similarly, a user writing +the file <filename>smcmemo.cls</filename>. Similarly, a user writing <literal>\usepackage{test}</literal> prompts &latex; to load the file <literal>test.sty</literal>. If the name of the file does not match the declared class or package name then you get a warning. Thus, if you invoke -<literal>\documentclass{smcmemo}</literal>, and the file <literal>smcmemo.cls</literal> has +<literal>\documentclass{smcmemo}</literal>, and the file <filename>smcmemo.cls</filename> has the statement <literal>\ProvidesClass{xxx}</literal> then you get a warning like <literal>You have requested document class `smcmemo', but the document class provides 'xxx'.</literal> This warning does not prevent &latex; from processing the rest of the class file normally. </para> -<para>If you include the optional part then you must include the date, before -the first space, and it must have the form <literal>YYYY/MM/DD</literal>. The rest -of the optional part is free-form, although it traditionally identifies +<para>If you include the optional argument, then you must include the date, before +the first space if any, and it must have the form <literal>YYYY/MM/DD</literal>. The rest +of the optional argument is free-form, although it traditionally identifies the class, and is written to the screen during compilation and to the -log file. Thus, if your file <literal>smcmem.cls</literal> contains the line -<literal>\ProvidesClass{smcmem}[2008/06/01 SMC memo class]</literal> and your -document’s first line is <literal>\documentclass{smcmem}</literal> then you will -see <literal>Document Class: smcmemo 2008/06/01 SMC memo class</literal>. +log file. Thus, if your file <filename>smcmemo.cls</filename> contains the line +<literal>\ProvidesClass{smcmemo}[2008/06/01 v1.0 SMC memo class]</literal> and your +document’s first line is <literal>\documentclass{smcmemo}</literal> then you will +see <literal>Document Class: smcmemo 2008/06/01 v1.0 SMC memo class</literal>. </para> -<para>The date in the optional portion allows class and package users to ask +<para>The date in the optional argument allows class and package users to ask to be warned if the version of the class or package installed on their -system is earlier than <replaceable>release date</replaceable>, by using the optional calls -such as <literal>\documentclass{smcmem}[2018/10/12]</literal> or +system is earlier than <replaceable>release date</replaceable>, by using the optional arguments +such as <literal>\documentclass{smcmemo}[2018/10/12]</literal> or <literal>\usepackage{foo}[[2017/07/07]]</literal>. (Note that package users only rarely include a date, and class users almost never do.) </para> @@ -1141,19 +1279,21 @@ rarely include a date, and class users almost never do.) <para>Declare a file other than the main class and package files, such as configuration files or font definition files. Put this command in that file and you get in the log a string like <literal>File: test.config -2017/10/12 config file for test.cls</literal>. +2017/10/12 config file for test.cls</literal> for <replaceable>file name</replaceable> equal to +‘<literal>test.config</literal>’ and <replaceable>additional information</replaceable> equal to +‘<literal>2017/10/12 config file for test.cls</literal>’. </para> -</listitem></varlistentry><varlistentry><term><literal>\RequirePackage[<replaceable>options list</replaceable>]{<replaceable>package name</replaceable>}[<replaceable>release date</replaceable>]</literal> +</listitem></varlistentry><varlistentry><term><literal>\RequirePackage[<replaceable>option list</replaceable>]{<replaceable>package name</replaceable>}[<replaceable>release date</replaceable>]</literal> </term></varlistentry><varlistentry><term><literal>\RequirePackageWithOptions{<replaceable>package name</replaceable>}[<replaceable>release date</replaceable>]</literal> </term><listitem><indexterm role="fn"><primary>\RequirePackage</primary></indexterm> <indexterm role="fn"><primary>\RequirePackageWithOptions</primary></indexterm> -<para>Load a package, like the author command <literal>\usepackage</literal>. +<para>Load a package, like the document author command <literal>\usepackage</literal>. See <link linkend="Additional-packages">Additional packages</link>. An example is <literal>\RequirePackage[landscape,margin=1in]{geometry}</literal>. Note that the &latex; development team strongly recommends use of these commands over Plain &tex;’s <literal>\input</literal>; see the Class Guide. </para> -<para>The <replaceable>options list</replaceable>, if present, is a comma-separated list. The +<para>The <replaceable>option list</replaceable>, if present, is a comma-separated list. The <replaceable>release date</replaceable>, if present, must have the form <replaceable>YYYY/MM/DD</replaceable>. If the release date of the package as installed on your system is earlier than <replaceable>release date</replaceable> then you get a warning like <literal>You have @@ -1383,10 +1523,11 @@ formulas. <literal>\mathversion{normal}</literal> restores the default. <indexterm role="cp"><primary>lining numerals</primary></indexterm> <indexterm role="cp"><primary>package, <literal>textcomp</literal></primary></indexterm> <indexterm role="cp"><primary><literal>textcomp</literal> package</primary></indexterm> + <para>Finally, the command <literal>\oldstylenums{<replaceable>numerals</replaceable>}</literal> will typeset so-called “old-style” numerals, which have differing heights and depths (and sometimes widths) from the standard “lining” numerals, -which all have the same height as upper-case letters. &latex;’s +which all have the same height as uppercase letters. &latex;’s default fonts support this, and will respect <literal>\textbf</literal> (but not other styles; there are no italic old-style numerals in Computer Modern). Many other fonts have old-style numerals also; sometimes the @@ -1469,7 +1610,8 @@ Knuth’s original encoding for Computer Modern (the default), and <literal>T1</literal>, also known as the Cork encoding, which has support for the accented characters used by the most widespread European languages (German, French, Italian, Polish and others), which allows &tex; to -hyphenate words containing accented letters. +hyphenate words containing accented letters. For more, see +<ulink url="https://ctan.org/pkg/encguide">https://ctan.org/pkg/encguide</ulink>. </para> </listitem></varlistentry><varlistentry><term><literal>\fontfamily{<replaceable>family</replaceable>}</literal> </term><listitem><indexterm role="fn"><primary>\fontfamily</primary></indexterm> @@ -1480,29 +1622,48 @@ hyphenate words containing accented letters. through many of the fonts easily used with &latex;. Here are examples of some common families: </para> -<!-- Sorry about the ugly @t{@ }. The idea is to make the lists line up --> -<!-- in Info. Since the items are so short, it seems nice to have them --> -<!-- on the same line instead of using @table. --> - -<itemizedlist><listitem><para><!-- /@w --> <literal>pag</literal><literal> </literal> Avant Garde -</para></listitem><listitem><para><!-- /@w --> <literal>fvs</literal><literal> </literal> Bitstream Vera Sans -</para></listitem><listitem><para><!-- /@w --> <literal>pbk</literal><literal> </literal> Bookman -</para></listitem><listitem><para><!-- /@w --> <literal>bch</literal><literal> </literal> Charter -</para></listitem><listitem><para><!-- /@w --> <literal>ccr</literal><literal> </literal> Computer Concrete -</para></listitem><listitem><para><!-- /@w --> <literal>cmr</literal><literal> </literal> Computer Modern -</para></listitem><listitem><para><!-- /@w --> <literal>pcr</literal><literal> </literal> Courier -</para></listitem><listitem><para><!-- /@w --> <literal>phv</literal><literal> </literal> Helvetica -</para></listitem><listitem><para><!-- /@w --> <literal>fi4</literal><literal> </literal> Inconsolata -</para></listitem><listitem><para><!-- /@w --> <literal>lmr</literal><literal> </literal> Latin Modern -</para></listitem><listitem><para><!-- /@w --> <literal>lmss</literal> Latin Modern Sans -</para></listitem><listitem><para><!-- /@w --> <literal>lmtt</literal> Latin Modern Typewriter -</para></listitem><listitem><para><!-- /@w --> <literal>pnc</literal><literal> </literal> New Century Schoolbook -</para></listitem><listitem><para><!-- /@w --> <literal>ppl</literal><literal> </literal> Palatino -</para></listitem><listitem><para><!-- /@w --> <literal>ptm</literal><literal> </literal> Times -</para></listitem><listitem><para><!-- /@w --> <literal>uncl</literal> Uncial -</para></listitem><listitem><para><!-- /@w --> <literal>put</literal><literal> </literal> Utopia -</para></listitem><listitem><para><!-- /@w --> <literal>pzc</literal><literal> </literal> Zapf Chancery -</para></listitem></itemizedlist> +<informaltable><tgroup cols="2"><colspec colwidth="4*"></colspec><colspec colwidth="31*"></colspec><tbody><row><entry><para><literal>pag</literal> +</para></entry><entry><para>Avant Garde +</para></entry></row><row><entry><para><literal>fvs</literal> +</para></entry><entry><para>Bitstream Vera Sans +</para></entry></row><row><entry><para><literal>pbk</literal> +</para></entry><entry><para>Bookman +</para></entry></row><row><entry><para><literal>bch</literal> +</para></entry><entry><para>Charter +</para></entry></row><row><entry><para><literal>ccr</literal> +</para></entry><entry><para>Computer Concrete +</para></entry></row><row><entry><para><literal>cmr</literal> +</para></entry><entry><para>Computer Modern +</para></entry></row><row><entry><para><literal>cmss</literal> +</para></entry><entry><para>Computer Modern Sans Serif +</para></entry></row><row><entry><para><literal>cmtt</literal> +</para></entry><entry><para>Computer Modern Typewriter +</para></entry></row><row><entry><para><literal>pcr</literal> +</para></entry><entry><para>Courier +</para></entry></row><row><entry><para><literal>phv</literal> +</para></entry><entry><para>Helvetica +</para></entry></row><row><entry><para><literal>fi4</literal> +</para></entry><entry><para>Inconsolata +</para></entry></row><row><entry><para><literal>lmr</literal> +</para></entry><entry><para>Latin Modern +</para></entry></row><row><entry><para><literal>lmss</literal> +</para></entry><entry><para>Latin Modern Sans +</para></entry></row><row><entry><para><literal>lmtt</literal> +</para></entry><entry><para>Latin Modern Typewriter +</para></entry></row><row><entry><para><literal>pnc</literal> +</para></entry><entry><para>New Century Schoolbook +</para></entry></row><row><entry><para><literal>ppl</literal> +</para></entry><entry><para>Palatino +</para></entry></row><row><entry><para><literal>ptm</literal> +</para></entry><entry><para>Times +</para></entry></row><row><entry><para><literal>uncl</literal> +</para></entry><entry><para>Uncial +</para></entry></row><row><entry><para><literal>put</literal> +</para></entry><entry><para>Utopia +</para></entry></row><row><entry><para><literal>pzc</literal> +</para></entry><entry><para>Zapf Chancery +</para></entry></row></tbody></tgroup></informaltable> + </listitem></varlistentry><varlistentry><term><literal>\fontseries{<replaceable>series</replaceable>}</literal> </term><listitem><indexterm role="fn"><primary>\fontseries</primary></indexterm> <indexterm role="cp"><primary>series, of fonts</primary></indexterm> @@ -1510,39 +1671,64 @@ examples of some common families: <firstterm>width</firstterm>. Typically, a font supports only a few of the possible combinations. Some common combined series values include: </para> -<itemizedlist><listitem><para><!-- /@w --> <literal>m</literal><literal> </literal> Medium (normal) -</para></listitem><listitem><para><!-- /@w --> <literal>b</literal><literal> </literal> Bold -</para></listitem><listitem><para><!-- /@w --> <literal>c</literal><literal> </literal> Condensed -</para></listitem><listitem><para><!-- /@w --> <literal>bc</literal> Bold condensed -</para></listitem><listitem><para><!-- /@w --> <literal>bx</literal> Bold extended -</para></listitem></itemizedlist> +<informaltable><tgroup cols="2"><colspec colwidth="2*"></colspec><colspec colwidth="17*"></colspec><tbody><row><entry><para><literal>m</literal> +</para></entry><entry><para>Medium (normal) +</para></entry></row><row><entry><para><literal>b</literal> +</para></entry><entry><para>Bold +</para></entry></row><row><entry><para><literal>c</literal> +</para></entry><entry><para>Condensed +</para></entry></row><row><entry><para><literal>bc</literal> +</para></entry><entry><para>Bold condensed +</para></entry></row><row><entry><para><literal>bx</literal> +</para></entry><entry><para>Bold extended +</para></entry></row></tbody></tgroup></informaltable> <indexterm role="cp"><primary>weights, of fonts</primary></indexterm> <para>The possible values for weight, individually, are: </para> -<itemizedlist><listitem><para><!-- /@w --> <literal>ul</literal> Ultra light -</para></listitem><listitem><para><!-- /@w --> <literal>el</literal> Extra light -</para></listitem><listitem><para><!-- /@w --> <literal>l</literal><literal> </literal> Light -</para></listitem><listitem><para><!-- /@w --> <literal>sl</literal> Semi light -</para></listitem><listitem><para><!-- /@w --> <literal>m</literal><literal> </literal> Medium (normal) -</para></listitem><listitem><para><!-- /@w --> <literal>sb</literal> Semi bold -</para></listitem><listitem><para><!-- /@w --> <literal>b</literal><literal> </literal> Bold -</para></listitem><listitem><para><!-- /@w --> <literal>eb</literal> Extra bold -</para></listitem><listitem><para><!-- /@w --> <literal>ub</literal> Ultra bold -</para></listitem></itemizedlist> +<informaltable><tgroup cols="2"><colspec colwidth="2*"></colspec><colspec colwidth="18*"></colspec><tbody><row><entry><para><literal>ul</literal> +</para></entry><entry><para>Ultra light +</para></entry></row><row><entry><para><literal>el</literal> +</para></entry><entry><para>Extra light +</para></entry></row><row><entry><para><literal>l</literal> +</para></entry><entry><para>Light +</para></entry></row><row><entry><para><literal>sl</literal> +</para></entry><entry><para>Semi light +</para></entry></row><row><entry><para><literal>m</literal> +</para></entry><entry><para>Medium (normal) +</para></entry></row><row><entry><para><literal>sb</literal> +</para></entry><entry><para>Semi bold +</para></entry></row><row><entry><para><literal>b</literal> +</para></entry><entry><para>Bold +</para></entry></row><row><entry><para><literal>eb</literal> +</para></entry><entry><para>Extra bold +</para></entry></row><row><entry><para><literal>ub</literal> +</para></entry><entry><para>Ultra bold +</para></entry></row></tbody></tgroup></informaltable> <indexterm role="cp"><primary>widths, of fonts</primary></indexterm> -<para>The possible values for width, individually, are (the percentages -are just guides and are not followed precisely by all fonts): -</para> -<itemizedlist><listitem><para><!-- /@w --> <literal>uc</literal> Ultra condensed, 50% -</para></listitem><listitem><para><!-- /@w --> <literal>ec</literal> Extra condensed, 62.5% -</para></listitem><listitem><para><!-- /@w --> <literal>c</literal><literal> </literal> Condensed, 75% -</para></listitem><listitem><para><!-- /@w --> <literal>sc</literal> Semi condensed, 87.5% -</para></listitem><listitem><para><!-- /@w --> <literal>m</literal><literal> </literal> Medium, 100% -</para></listitem><listitem><para><!-- /@w --> <literal>sx</literal> Semi expanded, 112.5% -</para></listitem><listitem><para><!-- /@w --> <literal>x</literal><literal> </literal> Expanded, 125% -</para></listitem><listitem><para><!-- /@w --> <literal>ex</literal> Extra expanded, 150% -</para></listitem><listitem><para><!-- /@w --> <literal>ux</literal> Ultra expanded, 200% -</para></listitem></itemizedlist> +<para>The possible values for width, individually, are (the meaning and +relationship of these terms varies with individual typefaces): +</para> + +<informaltable><tgroup cols="2"><colspec colwidth="2*"></colspec><colspec colwidth="15*"></colspec><tbody><row><entry><para><literal>uc</literal> +</para></entry><entry><para>Ultra condensed +</para></entry></row><row><entry><para><literal>ec</literal> +</para></entry><entry><para>Extra condensed +</para></entry></row><row><entry><para><literal>c</literal> +</para></entry><entry><para>Condensed +</para></entry></row><row><entry><para><literal>sc</literal> +</para></entry><entry><para>Semi condensed +</para></entry></row><row><entry><para><literal>m</literal> +</para></entry><entry><para>Medium +</para></entry></row><row><entry><para><literal>sx</literal> +</para></entry><entry><para>Semi expanded +</para></entry></row><row><entry><para><literal>x</literal> +</para></entry><entry><para>Expanded +</para></entry></row><row><entry><para><literal>ex</literal> +</para></entry><entry><para>Extra expanded +</para></entry></row><row><entry><para><literal>ux</literal> +</para></entry><entry><para>Ultra expanded +</para></entry></row></tbody></tgroup></informaltable> + <para>When forming the <replaceable>series</replaceable> string from the weight and width, drop the <literal>m</literal> that stands for medium weight or medium width, unless both weight and width are <literal>m</literal>, in which case use just one @@ -1553,13 +1739,20 @@ weight and width are <literal>m</literal>, in which case use just one <indexterm role="cp"><primary>shapes, of fonts</primary></indexterm> <para>Select font shape. Valid shapes are: </para> -<itemizedlist><listitem><para><!-- /@w --> <literal>n</literal><literal> </literal> Upright (normal) -</para></listitem><listitem><para><!-- /@w --> <literal>it</literal> Italic -</para></listitem><listitem><para><!-- /@w --> <literal>sl</literal> Slanted (oblique) -</para></listitem><listitem><para><!-- /@w --> <literal>sc</literal> Small caps -</para></listitem><listitem><para><!-- /@w --> <literal>ui</literal> Upright italics -</para></listitem><listitem><para><!-- /@w --> <literal>ol</literal> Outline -</para></listitem></itemizedlist> +<informaltable><tgroup cols="2"><colspec colwidth="2*"></colspec><colspec colwidth="19*"></colspec><tbody><row><entry><para><literal>n</literal> +</para></entry><entry><para>Upright (normal) +</para></entry></row><row><entry><para><literal>it</literal> +</para></entry><entry><para>Italic +</para></entry></row><row><entry><para><literal>sl</literal> +</para></entry><entry><para>Slanted (oblique) +</para></entry></row><row><entry><para><literal>sc</literal> +</para></entry><entry><para>Small caps +</para></entry></row><row><entry><para><literal>ui</literal> +</para></entry><entry><para>Upright italics +</para></entry></row><row><entry><para><literal>ol</literal> +</para></entry><entry><para>Outline +</para></entry></row></tbody></tgroup></informaltable> + <para>The two last shapes are not available for most font families, and small caps are often missing as well. </para> @@ -1580,11 +1773,13 @@ reset every time a size change happens; see <literal>\baselinestretch</literal>, <para>&latex; multiplies the line spacing by the value of the <literal>\baselinestretch</literal> parameter; the default factor is 1. A change takes effect when <literal>\selectfont</literal> (see below) is called. You can -make line skip changes happen for the entire document by doing -<literal>\renewcommand{\baselinestretch}{2.0}</literal> in the preamble. +make a line skip change happen for the entire document, for instance +doubling it, by doing <literal>\renewcommand{\baselinestretch}{2.0}</literal> in +the preamble. </para> <indexterm role="cp"><primary>package, <literal>setspace</literal></primary></indexterm> <indexterm role="cp"><primary><literal>setspace</literal> package</primary></indexterm> + <indexterm role="cp"><primary>double spacing</primary></indexterm> <para>However, the best way to double-space a document is to use the <filename>setspace</filename> package. In addition to offering a number of spacing @@ -2024,6 +2219,7 @@ automatically added. <indexterm role="cp"><primary>here, putting floats</primary></indexterm> <indexterm role="cp"><primary>package, <literal>float</literal></primary></indexterm> <indexterm role="cp"><primary><literal>float</literal> package</primary></indexterm> + <para>To absolutely force a float to appear “here”, you can <literal>\usepackage{float}</literal> and use the <literal>H</literal> specifier which it defines. For further discussion, see the FAQ entry at @@ -2057,6 +2253,9 @@ use the <filename>afterpage</filename> package and issue <literal>\afterpage{\clearpage}</literal>. This will wait until the current page is finished and then flush all outstanding floats. </para> +<indexterm role="cp"><primary>package, <literal>flafter</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>flafter</literal> package</primary></indexterm> + <para>&latex; can typeset a float before where it appears in the source (although on the same output page) if there is a <literal>t</literal> specifier in the <replaceable>placement</replaceable> parameter. If this is not desired, and deleting @@ -2197,15 +2396,229 @@ command is something like </screen> <indexterm role="fn"><primary>secnumdepth counter</primary></indexterm> <indexterm role="cp"><primary>section numbers, printing</primary></indexterm> -<para>The <literal>secnumdepth</literal> counter controls printing of section numbers. +<anchor id="Sectioning_002fsecnumdepth"/><para>The <literal>secnumdepth</literal> counter controls printing of section numbers. The setting </para> <screen>\setcounter{secnumdepth}{<replaceable>level</replaceable>} </screen> <para>suppresses heading numbers at any depth <inlineequation><mathphrase>> <replaceable>level</replaceable></mathphrase></inlineequation>, where -<literal>chapter</literal> is level zero. (See <link linkend="_005csetcounter">\setcounter</link>.) +<literal>chapter</literal> is level zero. The default <literal>secnumdepth</literal> is 3 in +&latex;’s <filename>article</filename> class and 2 in the <filename>book</filename> and +<filename>report</filename> classes. (See <link linkend="_005csetcounter">\setcounter</link>.) +</para> + + +<sect1 label="6.1" id="_005c_0040startsection"> +<title><literal>\@startsection</literal></title> + +<indexterm role="fn"><primary>\@startsection</primary></indexterm> +<indexterm role="cp"><primary>section, redefining</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\@startsection{<replaceable>name</replaceable>}{<replaceable>level</replaceable>}{<replaceable>indent</replaceable>}{<replaceable>beforeskip</replaceable>}{<replaceable>afterskip</replaceable>}{<replaceable>style</replaceable>} +</screen> +<para>Used to help redefine the behavior of commands that start sectioning +divisions such as <literal>\section</literal> or <literal>\subsection</literal>. +</para> +<para>Note that the <filename>titlesec</filename> package makes manipulation of sectioning +easier. Further, while most requirements for sectioning commands can be +satisfied with <literal>\@startsection</literal>, some cannot. For instance, in +the standard &latex; <literal>book</literal> and <literal>report</literal> classes the commands +<literal>\chapter</literal> and <literal>\report</literal> are not constructed in this way. To +make such a command you may want to use the <literal>\secdef</literal> command. +<!-- xx define, and make a cross reference to, secdef. --> +</para> +<para>Technically, <literal>\@startsection</literal> has the form +</para><screen>\@startsection{<replaceable>name</replaceable>}{<replaceable>level</replaceable>}{<replaceable>indent</replaceable>}{<replaceable>beforeskip</replaceable>}{<replaceable>afterskip</replaceable>}{<replaceable>style</replaceable>}*[<replaceable>toctitle</replaceable>]{<replaceable>title</replaceable>} +</screen><para>(the star <literal>*</literal> is optional), so that issuing +</para><screen>\renewcommand{\section}{\@startsection{<replaceable>name</replaceable>}{<replaceable>level</replaceable>}{<replaceable>indent</replaceable>}{<replaceable>beforeskip</replaceable>}{<replaceable>afterskip</replaceable>}{<replaceable>style</replaceable>}} +</screen><para>redefines <literal>\section</literal> to have the form +<literal>\section*[<replaceable>toctitle</replaceable>]{<replaceable>title</replaceable>}</literal> (here too, the +star <literal>*</literal> is optional). See <link linkend="Sectioning">Sectioning</link>. This implies that +when you write a command like <literal>\renewcommand{section}{...}</literal>, +the <literal>\@startsection{...}</literal> must come last in the definition. See +the examples below. +</para> +<variablelist> +<varlistentry><term><replaceable>name</replaceable> +</term><listitem><anchor id="_005c_0040startsection_002fname"/><para>Name of the counter used to number the +sectioning header. This counter must be defined separately. Most +commonly this is either <literal>section</literal>, <literal>subsection</literal>, or +<literal>paragraph</literal>. Although in those three cases the counter name is the +same as the sectioning command itself, using the same name is not +required. +</para> +<para>Then <literal>\the</literal><replaceable>name</replaceable> displays the title number and +<literal>\</literal><replaceable>name</replaceable><literal>mark</literal> is for the page headers. See the third +example below. +</para> +</listitem></varlistentry><varlistentry><term><replaceable>level</replaceable> +</term><listitem><anchor id="_005c_0040startsection_002flevel"/><para>An integer giving the depth of the +sectioning command: 0 for <literal>chapter</literal> (only applies to the standard +<literal>book</literal> and <literal>report</literal> classes), 1 for <literal>section</literal>, 2 for +<literal>subsection</literal>, 3 for <literal>subsubsection</literal>, 4 for <literal>paragraph</literal>, +and 5 for <literal>subparagraph</literal>. In the <literal>book</literal> and <literal>report</literal> +classes <literal>part</literal> has level -1, while in the <literal>article</literal> class +<literal>part</literal> has level 0. +</para> +<para>If <replaceable>level</replaceable> is less than or equal to the value of <literal>secnumdepth</literal> +then the titles for this sectioning command will be numbered. For +instance, in an <literal>article</literal>, if <literal>secnumdepth</literal> is 1 then a +<literal>\section{Introduction}</literal> command will produce output like “1 +Introduction” while <literal>\subsection{Discussion}</literal> will produce +output like “Discussion”, without the number prefix. +See <link linkend="Sectioning_002fsecnumdepth">Sectioning/secnumdepth</link>. +</para> +<para>If <replaceable>level</replaceable> is less than or equal to the value of <replaceable>tocdepth</replaceable> then +the table of contents will have an entry for this sectioning unit. +For instance, in an <literal>article</literal>, if <replaceable>tocdepth</replaceable> is 1 then the table of +contents will list sections but not subsections. +<!-- xx add, and cross reference to, tocdepth --> +</para> +</listitem></varlistentry><varlistentry><term><replaceable>indent</replaceable> +</term><listitem><anchor id="_005c_0040startsection_002findent"/><para>A length giving the indentation of all +of the title lines with respect to the left margin. To have the title +flush with the margin use <literal>0pt</literal>. A negative indentation such as +<literal>-\parindent</literal> will move the title into the left margin. +</para> +</listitem></varlistentry><varlistentry><term><replaceable>beforeskip</replaceable> +</term><listitem><anchor id="_005c_0040startsection_002fbeforeskip"/><para>The absolute value of this length is +the amount of vertical space that is inserted before this sectioning +unit’s title. This space will be discarded if the sectioning unit +happens to start at the top of a fresh page. If this number is negative +then the first paragraph following the header is not indented, if it is +non-negative then the first paragraph is indented. (Note that the +negative of <literal>1pt plus 2pt minus 3pt</literal> is <literal>-1pt plus -2pt minus +-3pt</literal>.) +</para> +<para>For example, if <replaceable>beforeskip</replaceable> is <literal>-3.5ex plus -1ex minus -0.2ex</literal> +then to start the new sectioning unit, &latex; will add about 3.5 times +the height of a letter x in vertical space, and the first paragraph in +the section will not be indented. Using a rubber length, with +<literal>plus</literal> and <literal>minus</literal>, is good practice here since it gives +&latex; more flexibility in making up the page (see <link linkend="Lengths">Lengths</link>). +</para> +<para>The full accounting of the vertical space between the baseline of the +line prior to this sectioning unit’s header and the baseline of the +header is that it is the sum of the <literal>\parskip</literal> of the text font, +the <literal>\baselineskip</literal> of the title font, and the absolute value of +the <replaceable>beforeskip</replaceable>. This space is typically rubber so it may stretch +or shrink. (If the sectioning unit starts on a fresh page so that the +vertical space is discarded then the baseline of the header text will be +where &latex; would put the baseline of the first text line on that +page.) +</para> +</listitem></varlistentry><varlistentry><term><replaceable>afterskip</replaceable> +</term><listitem><anchor id="_005c_0040startsection_002fafterskip"/><para>This is a length. If <replaceable>afterskip</replaceable> +is non-negative then this is the vertical space inserted after the +sectioning unit’s title header. If it is negative then the title header +becomes a run-in header, so that it becomes part of the next paragraph. +In this case the absolute value of the length gives the horizontal space +between the end of the title and the beginning of the following +paragraph. (Note that the negative of <literal>1pt plus 2pt minus 3pt</literal> is +<literal>-1pt plus -2pt minus -3pt</literal>.) +</para> +<para>As with <replaceable>beforeskip</replaceable>, using a rubber length, with <literal>plus</literal> and +<literal>minus</literal> components, is good practice here since it gives &latex; +more flexibility in putting together the page. +</para> +<para>If <literal>afterskip</literal> is non-negative then the full accounting of the +vertical space between the baseline of the sectioning unit’s header and +the baseline of the first line of the following paragraph is that it is +the sum of the <literal>\parskip</literal> of the title font, the +<literal>\baselineskip</literal> of the text font, and the value of <replaceable>after</replaceable>. +That space is typically rubber so it may stretch or shrink. (Note that +because the sign of <literal>afterskip</literal> changes the sectioning unit +header’s from standalone to run-in, you cannot use a negative +<literal>afterskip</literal> to cancel part of the <literal>\parskip</literal>.) +</para> +</listitem></varlistentry><varlistentry><term><replaceable>style</replaceable> +</term><listitem><anchor id="_005c_0040startsection_002fstyle"/><para>Controls the styling of the title. See +the examples below. Typical commands to use here are <literal>\centering</literal>, +<literal>\raggedright</literal>, <literal>\normalfont</literal>, <literal>\hrule</literal>, or +<literal>\newpage</literal>. The last command in <replaceable>style</replaceable> may be one such as +<literal>\MakeUppercase</literal> or <literal>\fbox</literal> that takes one argument. The +section title will be supplied as the argument to this command. For +instance, setting <replaceable>style</replaceable> to <literal>\bfseries\MakeUppercase</literal> would +produce titles that are bold and upper case. +</para></listitem></varlistentry></variablelist> +<para>These are &latex;’s defaults for the first three sectioning units that +are defined with <literal>\@startsection</literal>, for the <filename>article</filename>, +<filename>book</filename>, and <filename>report</filename> classes. +</para> +<informaltable><tgroup cols="4"><colspec colwidth="10*"></colspec><colspec colwidth="30*"></colspec><colspec colwidth="30*"></colspec><colspec colwidth="30*"></colspec><thead><row><entry></entry><entry><para><literal>section</literal> </para></entry><entry><para><literal>subsection</literal> </para></entry><entry><para><literal>subsubsection</literal> +</para></entry></row></thead><tbody><row><entry><para><link linkend="_005c_0040startsection_002fname"><replaceable>name</replaceable></link> +</para></entry><entry><para>section </para></entry><entry><para>subsection </para></entry><entry><para>subsubsection +</para></entry></row><row><entry><para><link linkend="_005c_0040startsection_002flevel"><replaceable>level</replaceable></link> +</para></entry><entry><para>1 </para></entry><entry><para>2 </para></entry><entry><para>3 +</para></entry></row><row><entry><para><link linkend="_005c_0040startsection_002findent"><replaceable>indent</replaceable></link> +</para></entry><entry><para><literal>0pt</literal> </para></entry><entry><para><literal>0pt</literal> </para></entry><entry><para><literal>0pt</literal> +</para></entry></row><row><entry><para><link linkend="_005c_0040startsection_002fbeforeskip"><replaceable>beforeskip</replaceable></link> +</para></entry><entry><para><literal>-3.5ex plus -1ex minus -0.2ex</literal> +</para></entry><entry><para><literal>-3.25ex plus -1ex minus -0.2ex</literal> +</para></entry><entry><para><literal>-3.25ex plus -1ex minus -0.2ex</literal> +</para></entry></row><row><entry><para><link linkend="_005c_0040startsection_002fafterskip"><replaceable>afterskip</replaceable></link> +</para></entry><entry><para><literal>2.3ex plus 0.2ex</literal> +</para></entry><entry><para><literal>1.5ex plus 0.2ex</literal> +</para></entry><entry><para><literal>1.5ex plus 0.2ex</literal> +</para></entry></row><row><entry><para><link linkend="_005c_0040startsection_002fstyle"><replaceable>style</replaceable></link> +</para></entry><entry><para><literal>\normalfont\Large\bfseries</literal> +</para></entry><entry><para><literal>\normalfont\large\bfseries</literal> +</para></entry><entry><para><literal>\normalfont\normalsize\bfseries</literal> +</para></entry></row></tbody></tgroup></informaltable> +<para>Here are examples. They go either in a package or class file or in the +preamble of a &latex; document. If you put them in the preamble they +must go between a <literal>\makeatletter</literal> command and a +<literal>\makeatother</literal>. (Probably the error message <literal>You can't use +`\spacefactor' in vertical mode.</literal> means that you forgot this.) +See <link linkend="_005cmakeatletter-and-_005cmakeatother">\makeatletter and \makeatother</link>. +</para> +<para>This will put section titles in large boldface type, centered. It says +<literal>\renewcommand</literal> because &latex;’s standard classes have already +defined a <literal>\section</literal>. For the same reason it does not define a +<literal>section</literal> counter, or the commands <literal>\thesection</literal> and +<literal>\l@section</literal>. +</para> +<screen>\renewcommand\section{% + \@startsection{section}% <link linkend="_005c_0040startsection_002fname"><replaceable>name</replaceable></link> + {1}% <link linkend="_005c_0040startsection_002flevel"><replaceable>level</replaceable></link> + {0pt}% <link linkend="_005c_0040startsection_002findent"><replaceable>indent</replaceable></link> + {-3.5ex plus -1ex minus -.2ex}% <link linkend="_005c_0040startsection_002fbeforeskip"><replaceable>beforeskip</replaceable></link> + {2.3ex plus.2ex}% <link linkend="_005c_0040startsection_002fafterskip"><replaceable>afterskip</replaceable></link> + {\centering\normalfont\Large\bfseries}% <link linkend="_005c_0040startsection_002fstyle"><replaceable>style</replaceable></link> + } +</screen> +<para>This will put <literal>subsection</literal> titles in small caps type, inline with the paragraph. </para> +<screen>\renewcommand\subsection{% + \@startsection{subsection}% <link linkend="_005c_0040startsection_002fname"><replaceable>name</replaceable></link> + {2}% <link linkend="_005c_0040startsection_002flevel"><replaceable>level</replaceable></link> + {0em}% <link linkend="_005c_0040startsection_002findent"><replaceable>indent</replaceable></link> + {-1ex plus 0.1ex minus -0.05ex}% <link linkend="_005c_0040startsection_002fbeforeskip"><replaceable>beforeskip</replaceable></link> + {-1em plus 0.2em}% <link linkend="_005c_0040startsection_002fafterskip"><replaceable>afterskip</replaceable></link> + {\scshape}% <link linkend="_005c_0040startsection_002fstyle"><replaceable>style</replaceable></link> + } +</screen> +<para>The prior examples redefined existing sectional unit title commands. This defines a new one, illustrating the needed counter and macros to display that counter. +</para> +<!-- From https://groups.google.com/forum/#!searchin/comp.text.tex/startsection%7Csort:relevance/comp.text.tex/sB-nTS-oL08/ZZeKYdG0llMJ --> +<screen>\setcounter{secnumdepth}{6}% show counters this far down +\newcounter{subsubparagraph}[subparagraph]% counter for numbering +\renewcommand{\thesubsubparagraph}% how to display + {\thesubparagraph.\@arabic\c@subsubparagraph}% numbering +\newcommand{\subsubparagraph}{\@startsection + {subsubparagraph}% + {6}% + {0em}% + {\baselineskip}% + {0.5\baselineskip}% + {\normalfont\normalsize}} +\newcommand*\l@subsubparagraph{\@dottedtocline{6}{10em}{5em}}% for toc +\newcommand{\subsubparagraphmark}[1]{}% for page headers +</screen> +</sect1> </chapter> <chapter label="7" id="Cross-references"> <title>Cross references</title> @@ -2395,6 +2808,7 @@ the end. For instance, the input <indexterm role="fn"><primary>environment, <literal>abstract</literal></primary></indexterm> <indexterm role="fn"><primary><literal>abstract</literal> environment</primary></indexterm> + <indexterm role="cp"><primary>abstracts</primary></indexterm> <para>Synopsis: @@ -2448,6 +2862,7 @@ a more flexible solution, use the package <filename>abstract</filename>). <indexterm role="fn"><primary>environment, <literal>array</literal></primary></indexterm> <indexterm role="fn"><primary><literal>array</literal> environment</primary></indexterm> + <indexterm role="cp"><primary>arrays, math</primary></indexterm> <para>Synopsis: @@ -2487,6 +2902,9 @@ by <literal>\arraycolsep</literal>, which gives half the width between columns. The default for this is ‘<literal>5pt</literal>’. </para> +<indexterm role="cp"><primary>package, <literal>amsmath</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>amsmath</literal> package</primary></indexterm> + <para>To obtain arrays with braces the standard is to use the <filename>amsmath</filename> package. It comes with environments <literal>pmatrix</literal> for an array surrounded by parentheses <literal>(...)</literal>, <literal>bmatrix</literal> for an array @@ -2522,6 +2940,7 @@ preamble: <indexterm role="fn"><primary>environment, <literal>center</literal></primary></indexterm> <indexterm role="fn"><primary><literal>center</literal> environment</primary></indexterm> + <indexterm role="cp"><primary>centering text, environment for</primary></indexterm> <para>Synopsis: @@ -2611,48 +3030,64 @@ centered. <indexterm role="fn"><primary>environment, <literal>description</literal></primary></indexterm> <indexterm role="fn"><primary><literal>description</literal> environment</primary></indexterm> + <indexterm role="cp"><primary>labelled lists, creating</primary></indexterm> <indexterm role="cp"><primary>description lists, creating</primary></indexterm> <para>Synopsis: </para> <screen>\begin{description} -\item [<replaceable>first label</replaceable>] text of first item -\item [<replaceable>second label</replaceable>] text of second item +\item[<replaceable>label of first item</replaceable>] text of first item +\item[<replaceable>label of second item</replaceable>] text of second item ... \end{description} </screen> -<para>Environment to make a labelled list of items. Each item’s <replaceable>label</replaceable> -is typeset in bold, flush-left. Each item’s text may contain multiple -paragraphs. Although the labels on the items are optional there is no -sensible default, so all items should have labels. +<para>Environment to make a labeled list of items. Each item’s <replaceable>label</replaceable> is +typeset in bold, and is flush left so that long labels continue into the +first line of the item text. There must be at least one item; having +none causes the &latex; error ‘<literal>Something's wrong--perhaps a +missing \item</literal>’. </para> +<para>This example shows the environment used for a sequence of definitions. +The labels ‘<literal>lama</literal>’ and ‘<literal>llama</literal>’ come out in boldface with their +left edges aligned on the left margin. +</para> +<screen>\begin{definition} + \item[lama] A priest. + \item[llama] A beast. +\end{definition} +</screen> <indexterm role="fn"><primary>\item</primary></indexterm> -<para>The list consists of at least one item, created with the <literal>\item</literal> -command (see <link linkend="_005citem">\item</link>). Having no items causes the &latex; error -‘<literal>Something's wrong--perhaps a missing \item</literal>’). +<para>Start list items with the <literal>\item</literal> command (see <link linkend="_005citem">\item</link>). Use the +optional labels, as in <literal>\item[Main point]</literal>, because there is +no sensible default. Following the <literal>\item</literal> is optional text, which +may contain multiple paragraphs. </para> <indexterm role="cp"><primary>bold typewriter, avoiding</primary></indexterm> <indexterm role="cp"><primary>typewriter labels in lists</primary></indexterm> <para>Since the labels are in bold style, if the label text calls for a font -change given in argument style (see <link linkend="Font-styles">Font styles</link>) then it will -come out bold. For instance, if the label text calls for typewriter -with <literal>\item[\texttt{label text}]</literal> then it will appear in bold +change given in argument style (see <link linkend="Font-styles">Font styles</link>) then it will come +out bold. For instance, if the label text calls for typewriter with +<literal>\item[\texttt{label text}]</literal> then it will appear in bold typewriter, if that is available. The simplest way to get non-bold typewriter is to use declarative style: <literal>\item[{\tt label -text}]</literal>. Similarly, to get the standard roman font, use -<literal>\item[{\rm label text}]</literal>. +text}]</literal>. Similarly, get the standard roman font with <literal>\item[{\rm +label text}]</literal>. </para> <para>For other major &latex; labelled list environments, see <link linkend="itemize">itemize</link> -and <link linkend="enumerate">enumerate</link>. For information about customizing list layout, see -<link linkend="list">list</link>; also, the package <filename>enumitem</filename> is useful for this. +and <link linkend="enumerate">enumerate</link>. Unlike those environments, nesting +<literal>description</literal> environments does not change the default label; it is +boldface and flush left at all levels. </para> -<para>This example shows the environment used for a sequence of definitions. +<para>For information about list layout parameters, including the default +values, and for information about customizing list layout, see +<link linkend="list">list</link>. The package <filename>enumitem</filename> is useful for customizing +lists. </para> -<screen>\begin{definition} - \item[lama] A priest. - \item[llama] A beast. -\end{definition} +<para>This example changes the description labels to small caps. +</para> +<screen>\renewcommand{\descriptionlabel}[1]{% + {\hspace{\labelsep}\textsc{#1}}} </screen> </sect1> @@ -2662,40 +3097,43 @@ and <link linkend="enumerate">enumerate</link>. For information about customizi <indexterm role="fn"><primary>environment, <literal>displaymath</literal></primary></indexterm> <indexterm role="fn"><primary><literal>displaymath</literal> environment</primary></indexterm> + <para>Synopsis: </para> <screen>\begin{displaymath} - ... math text ... +<replaceable>math text</replaceable> \end{displaymath} </screen> <para>Environment to typeset the math text on its own line, in display style and centered. To make the text be flush-left use the global option <literal>fleqn</literal>; see <link linkend="Document-class-options">Document class options</link>. </para> -<para>&latex; will not break the math text across lines. -</para> <para>In the <literal>displaymath</literal> environment no equation number is added to the math text. One way to get an equation number is to use the <literal>equation</literal> environment (see <link linkend="equation">equation</link>). </para> -<para>Note that the <filename>amsmath</filename> package has extensive displayed equation -facilities. Those facilities are the best approach for such output in -new documents. For example, there are a number of options in that -package for having math text broken across lines. +<para>&latex; will not break the <replaceable>math text</replaceable> across lines. +</para> +<indexterm role="cp"><primary>package, <literal>amsmath</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>amsmath</literal> package</primary></indexterm> + +<para>Note that the <filename>amsmath</filename> package has significantly more extensive +displayed equation facilities. For example, there are a number of +ways in that package for having math text broken across lines. </para> -<para>The construct <literal>\[..math text..\]</literal> is essentially a synonym for -<literal>\begin{displaymath}..math text..\end{displaymath}</literal> but the +<para>The construct <literal>\[<replaceable>math text</replaceable>\]</literal> is essentially a synonym for +<literal>\begin{displaymath}<replaceable>math text</replaceable>\end{displaymath}</literal> but the latter is easier to work with in the source file; for instance, searching for a square bracket may get false positives but the word -<literal>displaymath</literal> will likely be unique. (The construct <literal>$$..math -text..$$</literal> from Plain &tex; is sometimes mistakenly used as a -synonym for <literal>displaymath</literal>. It is not a synonym, because the -<literal>displaymath</literal> environment checks that it isn’t started in math mode -and that it ends in math mode begun by the matching environment start, -because the <literal>displaymath</literal> environment has different vertical -spacing, and because the <literal>displaymath</literal> environment honors the -<literal>fleqn</literal> option.) +<literal>displaymath</literal> will likely be unique. (The construct +<literal>$$<replaceable>math text</replaceable>$$</literal> from Plain &tex; is sometimes +mistakenly used as a synonym for <literal>displaymath</literal>. It is not a +synonym, because the <literal>displaymath</literal> environment checks that it isn’t +started in math mode and that it ends in math mode begun by the matching +environment start, because the <literal>displaymath</literal> environment has +different vertical spacing, and because the <literal>displaymath</literal> +environment honors the <literal>fleqn</literal> option.) </para> <para>The output from this example is centered and alone on its line. </para><screen>\begin{displaymath} @@ -2711,13 +3149,15 @@ spacing, and because the <literal>displaymath</literal> environment honors the <indexterm role="fn"><primary>environment, <literal>document</literal></primary></indexterm> <indexterm role="fn"><primary><literal>document</literal> environment</primary></indexterm> + <para>The <literal>document</literal> environment encloses the entire body of a document. It is required in every &latex; document. See <link linkend="Starting-and-ending">Starting and ending</link>. </para> -<anchor id="_005cAtBeginDocument"/> +<sect2 label="8.6.1" id="_005cAtBeginDocument"> +<title><literal>\AtBeginDocument</literal></title> <indexterm role="fn"><primary>\AtBeginDocument</primary></indexterm> <indexterm role="cp"><primary>beginning of document hook</primary></indexterm> @@ -2736,7 +3176,9 @@ the preamble so you cannot do any typesetting with it. will be executed in the order that you gave them. </para> -<anchor id="_005cAtEndDocument"/> +</sect2> +<sect2 label="8.6.2" id="_005cAtEndDocument"> +<title><literal>\AtEndDocument</literal></title> <indexterm role="fn"><primary>\AtEndDocument</primary></indexterm> <indexterm role="cp"><primary>end of document hook</primary></indexterm> @@ -2756,44 +3198,54 @@ appropriate point in <replaceable>code</replaceable>. will be executed in the order that you gave them. </para> +</sect2> </sect1> <sect1 label="8.7" id="enumerate"> <title><literal>enumerate</literal></title> <indexterm role="fn"><primary>environment, <literal>enumerate</literal></primary></indexterm> <indexterm role="fn"><primary><literal>enumerate</literal> environment</primary></indexterm> + <indexterm role="cp"><primary>lists of items, numbered</primary></indexterm> <para>Synopsis: </para> <screen>\begin{enumerate} -\item [<replaceable>first label</replaceable>] text of first item -\item [<replaceable>second label</replaceable>] text of second item +\item[<replaceable>optional label of first item</replaceable>] text of first item +\item[<replaceable>optional label of second item</replaceable>] text of second item ... \end{enumerate} </screen> <para>Environment to produce a numbered list of items. The format of the -label numbering depends on whether this environment is nested within -another; see below. -</para> -<indexterm role="fn"><primary>\item</primary></indexterm> -<para>The list consists of at least one item. Having no items causes the -&latex; error ‘<literal>Something's wrong--perhaps a missing \item</literal>’. Each -item is produced with an <literal>\item</literal> command. +label numbering depends on the nesting level of this environment; see +below. The default top-level numbering is ‘<literal>1.</literal>’, ‘<literal>2.</literal>’, +etc. Each <literal>enumerate</literal> list environment must have at least one item; +having none causes the &latex; error ‘<literal>Something's wrong--perhaps a +missing \item</literal>’. </para> -<para>This example lists the top two finishers in the 1908 Olympic marathon. +<para>This example gives the first two finishers in the 1908 Olympic marathon. +As a top-level list the labels would come out as ‘<literal>1.</literal>’ and +‘<literal>2.</literal>’. </para> <screen>\begin{enumerate} \item Johnny Hayes (USA) \item Charles Hefferon (RSA) \end{enumerate} </screen> -<para>Enumerations may be nested within a paragraph-making environment, -including <literal>itemize</literal> (see <link linkend="itemize">itemize</link>), <literal>description</literal> -(see <link linkend="description">description</link>) and <literal>enumeration</literal>, up to four levels deep. -The format of the label produced depends on the place in the nesting. -This gives &latex;’s default for the format at each nesting level -(where 1 is the outermost level): +<indexterm role="fn"><primary>\item</primary></indexterm> +<para>Start list items with the <literal>\item</literal> command (see <link linkend="_005citem">\item</link>). If you +give <literal>\item</literal> an optional argument by following it with square +brackets, as in <literal>\item[Interstitial label]</literal>, then the next item +will continue the interrupted sequence (see <link linkend="_005citem">\item</link>). That is, you +will get labels like ‘<literal>1.</literal>’, then ‘<literal>Interstitial label</literal>’, then +‘<literal>2.</literal>’. Following the <literal>\item</literal> is optional text, which may +contain multiple paragraphs. +</para> +<para>Enumerations may be nested within other <literal>enumerate</literal> environments, +or within any paragraph-making environment such as <literal>itemize</literal> +(see <link linkend="itemize">itemize</link>), up to four levels deep. This gives &latex;’s +default for the format at each nesting level, where 1 is the top level, +the outermost level. </para> <orderedlist numeration="arabic"><listitem><para>arabic number followed by a period: ‘<literal>1.</literal>’, ‘<literal>2.</literal>’, … </para></listitem><listitem><para>lower case letter inside parentheses: ‘<literal>(a)</literal>’, ‘<literal>(b)</literal>’ … @@ -2805,9 +3257,13 @@ This gives &latex;’s default for the format at each nesting level <indexterm role="fn"><primary>\enumiii</primary></indexterm> <indexterm role="fn"><primary>\enumiv</primary></indexterm> <para>The <literal>enumerate</literal> environment uses the counters <literal>\enumi</literal> through -<literal>\enumiv</literal> counters (see <link linkend="Counters">Counters</link>). If you use the optional -argument to <literal>\item</literal> then the counter is not incremented for that -item (see <link linkend="_005citem">\item</link>). +<literal>\enumiv</literal> (see <link linkend="Counters">Counters</link>). +</para> +<para>For other major &latex; labeled list environments, see +<link linkend="description">description</link> and <link linkend="itemize">itemize</link>. For information about list layout +parameters, including the default values, and for information about +customizing list layout, see <link linkend="list">list</link>. The package <filename>enumitem</filename> is +useful for customizing lists. </para> <indexterm role="fn"><primary>\labelenumi</primary></indexterm> <indexterm role="fn"><primary>\labelenumii</primary></indexterm> @@ -2817,30 +3273,26 @@ item (see <link linkend="_005citem">\item</link>). (see <link linkend="_005cnewcommand-_0026-_005crenewcommand">\newcommand & \renewcommand</link>) on the commands <literal>\labelenumi</literal> through <literal>\labelenumiv</literal>. For instance, this first level list will be labelled with uppercase letters, in boldface, and without a trailing -period: +period. </para> <indexterm role="fn"><primary>\Alph example</primary></indexterm> <screen>\renewcommand{\labelenumi}{\textbf{\Alph{enumi}}} \begin{enumerate} - \item eI - \item bi: - \item si: + \item Shows as boldface A + \item Shows as boldface B \end{enumerate} </screen> -<para>For a list of counter-labelling commands like <literal>\Alph</literal> see -<link linkend="_005calph-_005cAlph-_005carabic-_005croman-_005cRoman-_005cfnsymbol">\alph \Alph \arabic \roman \Roman \fnsymbol</link>. -</para> -<para>For more on customizing the layout see <link linkend="list">list</link>. Also, the package -<filename>enumitem</filename> is useful for this. +<para>For a list of counter-labeling commands see <link linkend="_005calph-_005cAlph-_005carabic-_005croman-_005cRoman-_005cfnsymbol">\alph \Alph \arabic +\roman \Roman \fnsymbol</link>. </para> - </sect1> <sect1 label="8.8" id="eqnarray"> <title><literal>eqnarray</literal></title> <indexterm role="fn"><primary>environment, <literal>eqnarray</literal></primary></indexterm> <indexterm role="fn"><primary><literal>eqnarray</literal> environment</primary></indexterm> + <indexterm role="cp"><primary>equations, aligning</primary></indexterm> <indexterm role="cp"><primary>aligning equations</primary></indexterm> @@ -2911,6 +3363,7 @@ while the third line has not entry on the left side. <indexterm role="fn"><primary>environment, <literal>equation</literal></primary></indexterm> <indexterm role="fn"><primary><literal>equation</literal> environment</primary></indexterm> + <indexterm role="cp"><primary>equations, environment for</primary></indexterm> <indexterm role="cp"><primary>formulas, environment for</primary></indexterm> @@ -2925,6 +3378,10 @@ equation number in the right margin. </para> <para>The equation number is generated using the <literal>equation</literal> counter. </para> +<para>You should have no blank lines between <literal>\begin{equation}</literal> and +<literal>\begin{equation}</literal>, or &latex; will tell you that there is a +missing dollar sign, $<literal>$</literal>. +</para> <para>Note that the <filename>amsmath</filename> package has extensive displayed equation facilities. Those facilities are the best approach for such output in new documents. @@ -2936,6 +3393,7 @@ new documents. <indexterm role="fn"><primary>environment, <literal>figure</literal></primary></indexterm> <indexterm role="fn"><primary><literal>figure</literal> environment</primary></indexterm> + <indexterm role="cp"><primary>inserting figures</primary></indexterm> <indexterm role="cp"><primary>figures, inserting</primary></indexterm> @@ -2998,8 +3456,10 @@ end of the document, on a page of floats. <indexterm role="fn"><primary>environment, <literal>filecontents</literal></primary></indexterm> <indexterm role="fn"><primary><literal>filecontents</literal> environment</primary></indexterm> + <indexterm role="fn"><primary>environment, <literal>filecontents*</literal></primary></indexterm> <indexterm role="fn"><primary><literal>filecontents*</literal> environment</primary></indexterm> + <indexterm role="cp"><primary>external files, writing</primary></indexterm> <indexterm role="cp"><primary>writing external files</primary></indexterm> @@ -3058,6 +3518,7 @@ Article by \myname. <indexterm role="fn"><primary>environment, <literal>flushleft</literal></primary></indexterm> <indexterm role="fn"><primary><literal>flushleft</literal> environment</primary></indexterm> + <indexterm role="cp"><primary>left-justifying text, environment for</primary></indexterm> <indexterm role="cp"><primary>ragged right text, environment for</primary></indexterm> @@ -3100,6 +3561,7 @@ command that ends the paragraph unit. <indexterm role="fn"><primary>environment, <literal>flushright</literal></primary></indexterm> <indexterm role="fn"><primary><literal>flushright</literal> environment</primary></indexterm> + <indexterm role="cp"><primary>ragged left text, environment for</primary></indexterm> <indexterm role="cp"><primary>right-justifying text, environment for</primary></indexterm> @@ -3142,6 +3604,7 @@ command that ends the paragraph unit. <indexterm role="fn"><primary>environment, <literal>itemize</literal></primary></indexterm> <indexterm role="fn"><primary><literal>itemize</literal> environment</primary></indexterm> + <indexterm role="fn"><primary>\item</primary></indexterm> <indexterm role="cp"><primary>lists of items</primary></indexterm> <indexterm role="cp"><primary>unordered lists</primary></indexterm> @@ -3150,34 +3613,53 @@ command that ends the paragraph unit. <para>Synopsis: </para> <screen>\begin{itemize} -\item <replaceable>item1</replaceable> -\item <replaceable>item2</replaceable> +\item[<replaceable>optional label of first item</replaceable>] text of first item +\item[<replaceable>optional label of second item</replaceable>] text of second item ... \end{itemize} </screen> <para>The <literal>itemize</literal> environment produces an “unordered”, “bulleted” -list. Itemized lists can be nested within one another, up to four -levels deep. They can also be nested within other paragraph-making -environments, such as <literal>enumerate</literal> (see <link linkend="enumerate">enumerate</link>). +list. The format of the label numbering depends on the nesting level of +this environment; see below. Each <literal>itemize</literal> list environment must +have at least one item; having none causes the &latex; error +‘<literal>Something's wrong--perhaps a missing \item</literal>’. </para> -<para>Each item of an <literal>itemize</literal> list begins with an <literal>\item</literal> command. -There must be at least one <literal>\item</literal> command within the environment. +<para>This example gives a two-item list. As a top-level list each label +would come out as a bullet, •. </para> -<para>By default, the marks at each level look like this: +<screen>\begin{itemize} + \item Pencil and watercolor sketch by Cassandra + \item Rice portrait +\end{itemize} +</screen> +<indexterm role="fn"><primary>\item</primary></indexterm> +<para>Start list items with the <literal>\item</literal> command (see <link linkend="_005citem">\item</link>). If you +give <literal>\item</literal> an optional argument by following it with square +brackets, as in <literal>\item[Optional label]</literal>, then by default it will +appear in bold and be flush right, so it could extend into the left +margin. For labels that are flush left see the <link linkend="description">description</link> +environment. Following the <literal>\item</literal> is optional text, which may +contain multiple paragraphs. </para> -<orderedlist numeration="arabic"><listitem><para>• (bullet) -</para></listitem><listitem><para><emphasis role="bold">--<!-- /@w --></emphasis> (bold en-dash) -</para></listitem><listitem><para>* (asterisk) -</para></listitem><listitem><para>. (centered dot, rendered here as a period) -</para></listitem></orderedlist> <indexterm role="fn"><primary>\labelitemi</primary></indexterm> <indexterm role="fn"><primary>\labelitemii</primary></indexterm> <indexterm role="fn"><primary>\labelitemiii</primary></indexterm> <indexterm role="fn"><primary>\labelitemiv</primary></indexterm> -<para>The <literal>itemize</literal> environment uses the commands <literal>\labelitemi</literal> -through <literal>\labelitemiv</literal> to produce the default label. So, you can -use <literal>\renewcommand</literal> to change the labels. For instance, to have -the first level use diamonds: +<para>Itemized lists can be nested within one another, up to four levels deep. +They can also be nested within other paragraph-making environments, such +as <literal>enumerate</literal> (see <link linkend="enumerate">enumerate</link>). The <literal>itemize</literal> environment +uses the commands <literal>\labelitemi</literal> through <literal>\labelitemiv</literal> to +produce the default label (this also uses the convention of lower case +roman numerals at the end of the command names that signify the nesting +level). These are the default marks at each level. +</para> +<orderedlist numeration="arabic"><listitem><para>• (bullet, from <literal>\textbullet</literal>) +</para></listitem><listitem><para><emphasis role="bold">--<!-- /@w --></emphasis> (bold en-dash, from <literal>\normalfont\bfseries\textendash</literal>) +</para></listitem><listitem><para>* (asterisk, from <literal>\textasteriskcentered</literal>) +</para></listitem><listitem><para>. (centered dot, rendered here as a period, from <literal>\textperiodcentered</literal>) +</para></listitem></orderedlist> +<para>Change the labels with <literal>\renewcommand</literal>. For instance, this makes +the first level use diamonds. </para> <screen>\renewcommand{\labelitemi}{$\diamond$} </screen> @@ -3188,67 +3670,26 @@ the first level use diamonds: <indexterm role="fn"><primary>\leftmarginiv</primary></indexterm> <indexterm role="fn"><primary>\leftmarginv</primary></indexterm> <indexterm role="fn"><primary>\leftmarginvi</primary></indexterm> -<para>The <literal>\leftmargini</literal> through <literal>\leftmarginvi</literal> parameters define -the distance between the left margin of the enclosing environment and -the left margin of the list. By convention, <literal>\leftmargin</literal> is set -to the appropriate <literal>\leftmargin<replaceable>N</replaceable></literal> when a new level of -nesting is entered. -</para> -<para>The defaults vary from ‘<literal>.5em</literal>’ (highest levels of nesting) to -‘<literal>2.5em</literal>’ (first level), and are a bit reduced in two-column mode. -This example greatly reduces the margin space for outermost lists: +<para>The distance between the left margin of the enclosing environment and +the left margin of the <literal>itemize</literal> list is determined by the +parameters <literal>\leftmargini</literal> through <literal>\leftmarginvi</literal>. (Note the +convention of using lower case roman numerals a the end of the command +name to denote the nesting level.) The defaults are: <literal>2.5em</literal> in +level 1 (<literal>2em</literal> in two-column mode), <literal>2.2em</literal> in level 2, +<literal>1.87em</literal> in level 3, and <literal>1.7em</literal> in level 4, with smaller +values for more deeply nested levels. +</para> +<para>For other major &latex; labeled list environments, see +<link linkend="description">description</link> and <link linkend="enumerate">enumerate</link>. For information about list +layout parameters, including the default values, and for information +about customizing list layout, see <link linkend="list">list</link>. The package +<filename>enumitem</filename> is useful for customizing lists. +</para> +<para>This example greatly reduces the margin space for outermost itemized +lists. </para> <screen>\setlength{\leftmargini}{1.25em} % default 2.5em </screen> -<!-- xx should be in its own generic section --> -<para>Some parameters that affect list formatting: -</para> -<variablelist><varlistentry><term><indexterm role="fn"><primary>\itemindent</primary></indexterm><literal>\itemindent</literal> -</term><listitem><para>Extra indentation before each item in a list; default zero. -</para> -</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\labelsep</primary></indexterm><literal>\labelsep</literal> -</term><listitem><para>Space between the label and text of an item; default ‘<literal>.5em</literal>’. -</para> -</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\labelwidth</primary></indexterm><literal>\labelwidth</literal> -</term><listitem><para>Width of the label; default ‘<literal>2em</literal>’, or ‘<literal>1.5em</literal>’ in two-column mode. -</para> -</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\listparindent</primary></indexterm><literal>\listparindent</literal> -</term><listitem><para>Extra indentation added to second and subsequent paragraphs within a -list item; default ‘<literal>0pt</literal>’. -</para> -</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\rightmargin</primary></indexterm><literal>\rightmargin</literal> -</term><listitem><para>Horizontal distance between the right margin of the list and the -enclosing environment; default ‘<literal>0pt</literal>’, except in the <literal>quote</literal>, -<literal>quotation</literal>, and <literal>verse</literal> environments, where it is set equal -to <literal>\leftmargin</literal>. -</para> -</listitem></varlistentry></variablelist> -<para>Parameters affecting vertical spacing between list items (rather -loose, by default). -</para> -<variablelist><varlistentry><term><indexterm role="fn"><primary>\itemsep</primary></indexterm><literal>\itemsep</literal> -</term><listitem><para>Vertical space between items. The default is <literal>2pt plus1pt -minus1pt</literal> for <literal>10pt</literal> documents, <literal>3pt plus2pt minus1pt</literal> for -<literal>11pt</literal>, and <literal>4.5pt plus2pt minus1pt</literal> for <literal>12pt</literal>. -</para> -</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\parsep</primary></indexterm><literal>\parsep</literal> -</term><listitem><para>Extra vertical space between paragraphs within a list item. Defaults -are the same as <literal>\itemsep</literal>. -</para> -</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\topsep</primary></indexterm><literal>\topsep</literal> -</term><listitem><para>Vertical space between the first item and the preceding paragraph. -For top-level lists, the default is <literal>8pt plus2pt minus4pt</literal> for -<literal>10pt</literal> documents, <literal>9pt plus3pt minus5pt</literal> for <literal>11pt</literal>, -and <literal>10pt plus4pt minus6pt</literal> for <literal>12pt</literal>. These are reduced -for nested lists. -</para> -</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\partopsep</primary></indexterm><literal>\partopsep</literal> -</term><listitem><para>Extra space added to <literal>\topsep</literal> when the list environment starts a -paragraph. The default is <literal>2pt plus1pt minus1pt</literal> for <literal>10pt</literal> -documents, <literal>3pt plus1pt minus1pt</literal> for <literal>11pt</literal>, and <literal>3pt -plus2pt minus2pt</literal> for <literal>12pt</literal>. -</para> -</listitem></varlistentry></variablelist> <indexterm role="fn"><primary>\parskip example</primary></indexterm> <para>Especially for lists with short items, it may be desirable to elide space between items. Here is an example defining an <literal>itemize*</literal> @@ -3270,6 +3711,7 @@ see <link linkend="_005cparskip">\parskip</link>): <indexterm role="fn"><primary>environment, <literal>letter</literal></primary></indexterm> <indexterm role="fn"><primary><literal>letter</literal> environment</primary></indexterm> + <para>This environment is used for creating letters. See <link linkend="Letters">Letters</link>. </para> @@ -3280,54 +3722,329 @@ see <link linkend="_005cparskip">\parskip</link>): <indexterm role="fn"><primary>environment, <literal>list</literal></primary></indexterm> <indexterm role="fn"><primary><literal>list</literal> environment</primary></indexterm> + <indexterm role="cp"><primary>lists of items, generic</primary></indexterm> -<para>The <literal>list</literal> environment is a generic environment which is used for -defining many of the more specific environments. It is seldom used in -documents, but often in macros. +<para>Synopsis: </para> <screen>\begin{list}{<replaceable>labeling</replaceable>}{<replaceable>spacing</replaceable>} -\item <replaceable>item1</replaceable> -\item <replaceable>item2</replaceable> +\item[<replaceable>optional label of first item</replaceable>] text of first item +\item[<replaceable>optional label of second item</replaceable>] text of second item ... \end{list} </screen> -<para>The mandatory <replaceable>labeling</replaceable> argument specifies how items should be -labelled (unless the optional argument is supplied to <literal>\item</literal>). -This argument is a piece of text that is inserted in a box to form the -label. It can and usually does contain other &latex; commands. +<para>The <literal>list</literal> environment is a generic environment for constructing +more specialized lists. It is most often used to create lists via the +<literal>description</literal>, <literal>enumerate</literal>, and <literal>itemize</literal> environments +(see <link linkend="description">description</link>, <link linkend="enumerate">enumerate</link>, and <link linkend="itemize">itemize</link>). +</para> +<para>Also, many standard &latex; environments that are not visually lists +are constructed using <literal>list</literal>, including <literal>quotation</literal>, +<literal>quote</literal>, <literal>center</literal>, <literal>verbatim</literal>, and plenty more +(see <link linkend="quotation-and-quote">quotation and quote</link>, see <link linkend="center">center</link>, see <link linkend="flushright">flushright</link>). +</para> +<indexterm role="cp"><primary>package, <literal>enumitem</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>enumitem</literal> package</primary></indexterm> + +<para>The third-party package <literal>enumitem</literal> is useful for customizing lists. +Here, we describe the <literal>list</literal> environment by defining a new custom +environment. +</para> +<screen>\newcounter{namedlistcounter} % number the items +\newenvironment{named} + {\begin{list} + {Item~\Roman{namedlistcounter}.} % labeling argument + {\usecounter{namedlistcounter} % spacing argument + \setlength{\leftmargin}{3.5em}} % still spacing arg + } + {\end{list}} + +\begin{named} + \item Shows as ``Item~I.'' + \item[Special label.] Shows as ``Special label.'' + \item Shows as ``Item~II.'' +\end{named} +</screen> +<para>The <literal>list</literal> environment’s mandatory first argument, +<replaceable>labeling</replaceable>, specifies the default labeling of list items. It can +contain text and &latex; commands, as above where it contains both +‘<literal>Item</literal>’ and ‘<literal>\Roman{...}</literal>’. &latex; forms the label by +putting the <replaceable>labeling</replaceable> argument in a box of width +<literal>\labelwidth</literal>. If the label is wider than that, the additional +material extends to the right. When making an instance of a list you +can override the default labeling by giving <literal>\item</literal> an optional +argument by including square braces and the text, as in the above +<literal>\item[Special label.]</literal>; see <link linkend="_005citem">\item</link>. +</para> +<indexterm role="fn"><primary>\makelabel</primary></indexterm> +<para>The label box is constructed by the command <literal>\makelabel</literal>. By +default it positions the contents flush right. It takes one argument, +the label. It typesets the contents in LR mode. An example of changing +its definition is that to the above example before the definition of the +<literal>named</literal> environment add +<literal>\newcommand{\namedmakelabel}[1]{\textsc{#1}}</literal>, and between +the <literal>\setlength</literal> command and the parenthesis that closes the +<replaceable>spacing</replaceable> argument also add <literal>\let\makelabel\namedmakelabel</literal>. +Then the items will be typeset in small caps. Similarly, changing the +second code line to <literal>\let\makelabel\fbox</literal> puts the labels inside a +framed box. Another example is at the bottom of this entry. +</para> +<para>The mandatory second argument <replaceable>spacing</replaceable> can have a list of +commands to redefine the spacing parameters for the list, such as +<literal>\setlength{\labelwidth}{2em}</literal>. If this argument is empty, +i.e., <literal>{}</literal>, then the list will have the default spacing given +below. To number the items using a counter, put +<literal>\usecounter{<replaceable>countername</replaceable>}</literal> in this argument +(see <link linkend="_005cusecounter">\usecounter</link>). +</para> +<para>Below are the spacing parameters for list formatting. See also the +figure below. Each is a length (see <link linkend="Lengths">Lengths</link>). The vertical +spaces are normally rubber lengths, with <literal>plus</literal> and <literal>minus</literal> +components, to give &tex; flexibility in setting the page. Change +each with a command such as <literal>\setlength{itemsep}{2pt plus1pt +minus1pt}</literal>. For some effects these lengths should be zero or +negative. Default values for derived environments such as +<literal>itemize</literal> can be changed from the values shown here for the basic +<literal>list</literal>. +</para> +<variablelist><varlistentry><term><indexterm role="fn"><primary>\itemindent</primary></indexterm><literal>\itemindent</literal> +</term><listitem><para>Extra horizontal space indentation, beyond <literal>leftmargin</literal>, of the +first line each item. Its default value is <literal>0pt</literal>. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\itemsep</primary></indexterm><literal>\itemsep</literal> +</term><listitem><para>Vertical space between items, beyond the <literal>\parsep</literal>. The defaults +for the first three levels in &latex;’s ‘<literal>article</literal>’, ‘<literal>book</literal>’, +and ‘<literal>report</literal>’ classes at 10 point size are: <literal>4pt plus2pt +minus1pt</literal>, <literal>\parsep</literal> (that is, <literal>2pt plus1pt minus1pt</literal>), and +<literal>\topsep</literal> (that is, <literal>2pt plus1pt minus1pt</literal>). The defaults at +11 point are: <literal>4.5pt plus2pt minus1pt</literal>, <literal>\parsep</literal> (that is, +<literal>2pt plus1pt minus1pt</literal>), and <literal>topsep</literal> (that is, <literal>2pt +plus1pt minus1pt</literal>). The defaults at 12 point are: <literal>5pt plus2.5pt +minus1pt</literal>, <literal>\parsep</literal> (that is, <literal>2.5pt plus1pt minus1pt</literal>), and +<literal>\topsep</literal> (that is, <literal>2.5pt plus1pt minus1pt</literal>). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\labelsep</primary></indexterm><literal>\labelsep</literal> +</term><listitem><para>Horizontal space between the label and text of an item. +The default for &latex;’s ‘<literal>article</literal>’, ‘<literal>book</literal>’, +and ‘<literal>report</literal>’ classes is <literal>0.5em</literal>. </para> -<para>The mandatory <replaceable>spacing</replaceable> argument contains commands to change the -spacing parameters for the list. This argument will most often be -empty, i.e., <literal>{}</literal>, which leaves the default spacing. +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\labelwidth</primary></indexterm><literal>\labelwidth</literal> +</term><listitem><para>Horizontal width. The box containing the label is nominally this wide. +If <literal>\makelabel</literal> returns text that is wider than this then the first +line of the item will be indented to make room for this extra material. +If <literal>\makelabel</literal> returns text of width less than or equal to +<literal>\labelwidth</literal> then &latex;’s default is that the label is typeset +flush right in a box of this width. +</para> +<para>The left edge of the label box is +<literal>\leftmargin</literal>+<literal>\itemindent</literal>-<literal>\labelsep</literal>-<literal>\labelwidth</literal> +from the left margin of the enclosing environment. +</para> +<para>The default for &latex;’s ‘<literal>article</literal>’, ‘<literal>book</literal>’, and +‘<literal>report</literal>’ classes at the top level is +<literal>\leftmargini</literal>-<literal>\labelsep</literal>, (which is <literal>2em</literal> in one column +mode and <literal>1.5em</literal> in two column mode). At the second level it is +<literal>\leftmarginii</literal>-<literal>\labelsep</literal>, and at the third level it is +<literal>\leftmarginiii</literal>-<literal>\labelsep</literal>. These definitions make the +label’s left edge coincide with the left margin of the enclosing +environment. </para> -<para>The width used for typesetting the list items is specified by -<literal>\linewidth</literal> (see <link linkend="Page-layout-parameters">Page layout parameters</link>). +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\leftmargin</primary></indexterm><literal>\leftmargin</literal> +</term><listitem><para>Horizontal space between the left margin of the enclosing environment +(or the left margin of the page if this is a top-level list), and the +left margin of this list. It must be non-negative. +</para> +<para>In the standard &latex; document classes, a top-level list has this set +to the value of <literal>\leftmargini</literal>, while a list that is nested inside +a top-level list has this margin set to <literal>\leftmarginii</literal>. More +deeply nested lists get the values of <literal>\leftmarginiii</literal> through +<literal>\leftmarginvi</literal>. (Nesting greater than level five generates the +error message ‘<literal>Too deeply nested</literal>’.) +</para> +<para>The defaults for the first three levels in &latex;’s ‘<literal>article</literal>’, +‘<literal>book</literal>’, and ‘<literal>report</literal>’ classes are: <literal>\leftmargini</literal> is +<literal>2.5em</literal> (in two column mode, <literal>2em</literal>), <literal>\leftmarginii</literal> is +<literal>2.2em</literal>, and <literal>\leftmarginiii</literal> is <literal>1.87em</literal>. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\listparindent</primary></indexterm><literal>\listparindent</literal> +</term><listitem><para>Horizontal space of additional line indentation, beyond +<literal>\leftmargin</literal>, for second and subsequent paragraphs within a list +item. A negative value makes this an “outdent”. Its default value +is <literal>0pt</literal>. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\parsep</primary></indexterm><literal>\parsep</literal> +</term><listitem><para>Vertical space between paragraphs within an item. In the ‘<literal>book</literal>’ +and ‘<literal>article</literal>’ classes The defaults for the first three levels in +&latex;’s ‘<literal>article</literal>’, ‘<literal>book</literal>’, and ‘<literal>report</literal>’ classes at 10 +point size are: <literal>4pt plus2pt minus1pt</literal>, <literal>2pt plus1pt +minus1pt</literal>, and <literal>0pt</literal>. The defaults at 11 point size are: +<literal>4.5pt plus2pt minus1pt</literal>, <literal>2pt plus1pt minus1pt</literal>, and +<literal>0pt</literal>. The defaults at 12 point size are: <literal>5pt plus2.5pt +minus1pt</literal>, <literal>2.5pt plus1pt minus1pt</literal>, and <literal>0pt</literal>. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\partopsep</primary></indexterm><literal>\partopsep</literal> +</term><listitem><para>Vertical space added, beyond <literal>\topsep</literal>+<literal>\parskip</literal>, to the top +and bottom of the entire environment if the list instance is preceded by +a blank line. (A blank line in the &latex; source before the list +changes spacing at both the top and bottom of the list; whether the line +following the list is blank does not matter.) +</para> +<para>The defaults for the first three levels in &latex;’s ‘<literal>article</literal>’, +‘<literal>book</literal>’, and ‘<literal>report</literal>’ classes at 10 point size are: <literal>2pt +plus1 minus1pt</literal>, <literal>2pt plus1pt minus1pt</literal>, and <literal>1pt plus0pt +minus1pt</literal>. The defaults at 11 point are: <literal>3pt plus1pt minus1pt</literal>, +<literal>3pt plus1pt minus1pt</literal>, and <literal>1pt plus0pt minus1pt</literal>). The +defaults at 12 point are: <literal>3pt plus2pt minus3pt</literal>, <literal>3pt plus2pt +minus2pt</literal>, and <literal>1pt plus0pt minus1pt</literal>. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\rightmargin</primary></indexterm><literal>\rightmargin</literal> +</term><listitem><para>Horizontal space between the right margin of the list and the right +margin of the enclosing environment. Its default value is <literal>0pt</literal>. +It must be non-negative. +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\topsep</primary></indexterm><literal>\topsep</literal> +</term><listitem><para>Vertical space added to both the top and bottom of the list, in addition +to <literal>\parskip</literal> (see <link linkend="_005cparskip">\parskip</link>). The defaults for the first three +levels in &latex;’s ‘<literal>article</literal>’, ‘<literal>book</literal>’, and ‘<literal>report</literal>’ +classes at 10 point size are: <literal>8pt plus2pt minus4pt</literal>, <literal>4pt +plus2pt minus1pt</literal>, and <literal>2pt plus1pt minus1pt</literal>. The defaults at 11 +point are: <literal>9pt plus3pt minus5pt</literal>, <literal>4.5pt plus2pt minus1pt</literal>, +and <literal>2pt plus1pt minus1pt</literal>. The defaults at 12 point are: +<literal>10pt plus4pt minus6pt</literal>, <literal>5pt plus2.5pt minus1pt</literal>, and +<literal>2.5pt plus1pt minus1pt</literal>. </para> +</listitem></varlistentry></variablelist> +<para>This shows the horizontal and vertical distances. +</para> +<informalfigure><mediaobject><imageobject><imagedata fileref="latex2e-figures/list.eps" format="EPS"></imagedata></imageobject><imageobject><imagedata fileref="latex2e-figures/list.pdf" format="PDF"></imagedata></imageobject><imageobject><imagedata fileref="latex2e-figures/list.png" format="PNG"></imagedata></imageobject><textobject><literallayout>....................................................................... +..............Surrounding environment, preceding material.............. - + | v0 + |---h0--|-h1-| | + ..Label.. .....First item..................................... - + ............................................................ + ............................................................ - + | v1 + ........First item, second paragraph .................. - + |-h2-| | v2 + | + ..Label.. .....Second item.................................... - + ............................................................ + ............................................................ - +|-h3--|-h4-| |-h5-| |v3 + | +..............Surrounding environment, following material.............. - +.......................................................................</literallayout></textobject></mediaobject></informalfigure> + +<para>The lengths shown are listed below. The key relationship is that the +right edge of the bracket for <replaceable>h1</replaceable> equals the right edge of the +bracket for <replaceable>h4</replaceable>, so that the left edge of the label box is at +<replaceable>h3</replaceable>+<replaceable>h4</replaceable>-(<replaceable>h0</replaceable>+<replaceable>h1</replaceable>). +</para> +<variablelist><varlistentry><term><replaceable>v0</replaceable> +</term><listitem><para><inlineequation><mathphrase><literal>\topsep</literal> + <literal>\parskip</literal></mathphrase></inlineequation> if +the list environment does not start a new paragraph, and +<literal>\topsep</literal>+<literal>\parskip</literal>+<literal>\partopsep</literal> if it does +</para> +</listitem></varlistentry><varlistentry><term><replaceable>v1</replaceable> +</term><listitem><para><literal>\parsep</literal> +</para> +</listitem></varlistentry><varlistentry><term><replaceable>v2</replaceable> +</term><listitem><para><literal>\itemsep</literal>+<literal>\parsep</literal> +</para> +</listitem></varlistentry><varlistentry><term><replaceable>v3</replaceable> +</term><listitem><para>Same as <replaceable>v0</replaceable>. (This space is affected by whether a blank line +appears in the source above the environment; whether a blank line +appears in the source below the environment does not matter.) +</para> +</listitem></varlistentry><varlistentry><term><replaceable>h1</replaceable> +</term><listitem><para><literal>\labelsep</literal> +</para> +</listitem></varlistentry><varlistentry><term><replaceable>h2</replaceable> +</term><listitem><para><literal>\listparindent</literal> +</para> +</listitem></varlistentry><varlistentry><term><replaceable>h3</replaceable> +</term><listitem><para><literal>\leftmargin</literal> +</para> +</listitem></varlistentry><varlistentry><term><replaceable>h4</replaceable> +</term><listitem><para><literal>\itemindent</literal> +</para> +</listitem></varlistentry><varlistentry><term><replaceable>h5</replaceable> +</term><listitem><para><literal>\rightmargin</literal> +</para> +</listitem></varlistentry></variablelist> +<para>The list’s left and right margins, shown above as <replaceable>h3</replaceable> and <replaceable>h5</replaceable>, +are with respect to the ones provided by the surrounding environment, or +with respect to the page margins for a top-level list. The line width +used for typesetting the list items is <literal>\linewidth</literal> (see <link linkend="Page-layout-parameters">Page +layout parameters</link>). For instance, set the list’s left margin to be one +quarter of the distance between the left and right margins of the +enclosing environment with +<literal>\setlength{\leftmargin}{0.25\linewidth}</literal>. +</para> +<para>Page breaking in a list structure is controlled by the three +parameters below. For each, the &latex; default is +<literal>-\@lowpenalty</literal>, that is, <literal>-51</literal>. Because it is negative, +it somewhat encourages a page break at each spot. Change it with, +e.g., <literal>\@beginparpenalty=9999</literal>; a value of 10000 prohibits a +page break. +</para> +<variablelist><varlistentry><term><indexterm role="fn"><primary>\@beginparpenalty</primary></indexterm><literal>\@beginparpenalty</literal> +</term><listitem><para>The page breaking penalty for breaking before the list (default <literal>-51</literal>). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\@itempenalty</primary></indexterm><literal>\@itempenalty</literal> +</term><listitem><para>The page breaking penalty for breaking before a list item (default <literal>-51</literal>). +</para> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\@endparpenalty</primary></indexterm><literal>\@endparpenalty</literal> +</term><listitem><para>The page breaking penalty for breaking after a list (default <literal>-51</literal>). +</para> +</listitem></varlistentry></variablelist> +<para>This example has the labels in red. They are numbered, and the left +edge of the label lines up with the left edge of the item text. +</para> +<screen>\usepackage{color} +\newcounter{cnt} +\newcommand{\makeredlabel}[1]{\textcolor{red}{#1.}} +\newenvironment{redlabel} + {\begin{list} + {\arabic{cnt}} + {\usecounter{cnt} + \setlength{\labelwidth}{0em} + \setlength{\labelsep}{0.5em} + \setlength{\leftmargin}{1.5em} + \setlength{\itemindent}{0.5em} % equals \labelwidth+\labelsep + \let\makelabel=\makeredlabel + } + } +{\end{list} } +</screen> <sect2 label="8.16.1" id="_005citem"> -<title><literal>\item</literal>: An entry in a list.</title> +<title><literal>\item</literal>: An entry in a list</title> <para>Synopsis: </para> <screen>\item text of item </screen> <para>or -</para><screen>\item[<replaceable>optional label</replaceable>] text of item +</para><screen>\item[<replaceable>optional-label</replaceable>] text of item </screen> <para>An entry in a list. The entries are prefixed by a label, whose default -depends on the list type. +depends on the list type. +</para> +<para>Because the optional label is surrounded by square brackets +‘<literal>[...]</literal>’, if you have an item whose text starts with ‘<literal>[</literal>’, you +have to to hide the bracket inside curly braces, as in: <literal>\item +{[} is an open square bracket</literal>; otherwise, &latex; will think it +marks the start of an optional label. </para> -<para>Because the optional argument <replaceable>optional label</replaceable> is surrounded by -square brackets (<literal>[</literal> and <literal>]</literal>), to use square brackets -inside the optional argument you must hide them inside curly braces, as -in <literal>\item[Close square bracket, {]}]</literal>. Similarly, to use an open -square bracket as first character in the text of the item, also hide it -inside curly braces. See <link linkend="LaTeX-command-syntax">&latex; command syntax</link>. +<para>Similarly, if the item does have the optional label and you need a +close square bracket inside that label, you must hide it in the same +way: <literal>\item[Close square bracket, {]}]</literal>. See <link linkend="LaTeX-command-syntax">&latex; +command syntax</link>. </para> -<para>In this example the <literal>enumerate</literal> list has two items that use the -default label and one that uses the optional label. +<para>In this example the enumerate list has two items that use the default +label and one that uses the optional label. </para> <screen>\begin{enumerate} \item Moe @@ -3336,11 +4053,52 @@ default label and one that uses the optional label. \end{enumerate} </screen> <para>The first item is labelled ‘<literal>1.</literal>’, the second item is labelled -‘<literal>sometimes</literal>’, and the third item is labelled ‘<literal>2.</literal>’ (note that, -because of the optional label in the second item, the third item does -not get a ‘<literal>3.</literal>’). +‘<literal>sometimes</literal>’, and the third item is labelled ‘<literal>2.</literal>’. Because +of the optional label in the second item, the third item is not +labelled ‘<literal>3.</literal>’. </para> +</sect2> +<sect2 label="8.16.2" id="trivlist"> +<title><literal>trivlist</literal>: A restricted form of <literal>list</literal></title> + +<para>Synopsis: +</para> +<screen>\begin{trivlist} + ... +\end{trivlist} +</screen> +<para>A restricted version of the list environment, in which margins are not +indented and an <literal>\item</literal> without an optional argument produces no +text. It is most often used in macros, to define an environment where +the <literal>\item</literal> command as part of the environment’s definition. For +instance, the <literal>center</literal> environment is defined essentially like +this: +</para> +<screen>\newenvironment{center} + {\begin{trivlist}\centering\item\relax} + {\end{trivlist}} +</screen> +<para>Using <literal>trivlist</literal> in this way allows the macro to inherit some +common code: combining vertical space of two adjacent environments; +detecting whether the text following the environment should be +considered a new paragraph or a continuation of the previous one; +adjusting the left and right margins for possible nested list +environments. +</para> +<para>Specifically, <literal>trivlist</literal> uses the current values of the list +parameters (see <link linkend="list">list</link>), except that <literal>\parsep</literal> is set to the +value of <literal>\parskip</literal>, and <literal>\leftmargin</literal>, <literal>\labelwidth</literal>, +and <literal>\itemindent</literal> are set to zero. +</para> +<para>This example outputs the items as two paragraphs, except that (by +default) they have no paragraph indent and are vertically separated. +</para> +<screen>\begin{trivlist} +\item The \textit{Surprise} is not old; no one would call her old. +\item She has a bluff bow, lovely lines. +\end{trivlist} +</screen> </sect2> </sect1> @@ -3349,6 +4107,7 @@ not get a ‘<literal>3.</literal>’). <indexterm role="fn"><primary>environment, <literal>math</literal></primary></indexterm> <indexterm role="fn"><primary><literal>math</literal> environment</primary></indexterm> + <indexterm role="cp"><primary>in-line formulas</primary></indexterm> <para>Synopsis: @@ -3357,8 +4116,8 @@ not get a ‘<literal>3.</literal>’). <replaceable>math</replaceable> \end{math} </screen> -<para>The <literal>math</literal> environment inserts the given <replaceable>math</replaceable> within the -running text. <literal>\(...\)</literal> and <literal>$...$</literal> are synonyms. +<para>The <literal>math</literal> environment inserts given <replaceable>math</replaceable> material within +the running text. <literal>\(...\)</literal> and <literal>$...$</literal> are synonyms. See <link linkend="Math-formulas">Math formulas</link>. </para> @@ -3368,6 +4127,7 @@ See <link linkend="Math-formulas">Math formulas</link>. <indexterm role="fn"><primary>environment, <literal>minipage</literal></primary></indexterm> <indexterm role="fn"><primary><literal>minipage</literal> environment</primary></indexterm> + <indexterm role="cp"><primary>minipage, creating a</primary></indexterm> <screen>\begin{minipage}[<replaceable>position</replaceable>][<replaceable>height</replaceable>][<replaceable>inner-pos</replaceable>]{<replaceable>width</replaceable>} @@ -3408,6 +4168,7 @@ footnotes; they may wind up at the bottom of the wrong minipage. <indexterm role="fn"><primary>environment, <literal>picture</literal></primary></indexterm> <indexterm role="fn"><primary><literal>picture</literal> environment</primary></indexterm> + <indexterm role="cp"><primary>creating pictures</primary></indexterm> <indexterm role="cp"><primary>pictures, creating</primary></indexterm> @@ -3432,6 +4193,7 @@ The default value is <literal>1pt</literal>. </para> <indexterm role="cp"><primary>package, <literal>picture</literal></primary></indexterm> <indexterm role="cp"><primary><literal>picture</literal> package</primary></indexterm> + <para>The <literal>picture</literal> package redefine the <literal>picture</literal> environment so that everywhere a number is used in a <replaceable>picture commands</replaceable> to specify a coordinate, one can use alternatively a length. Be aware however that @@ -3763,11 +4525,13 @@ values must lie between −4 and +4, inclusive. <indexterm role="fn"><primary>environment, <literal>quotation</literal></primary></indexterm> <indexterm role="fn"><primary><literal>quotation</literal> environment</primary></indexterm> + <indexterm role="cp"><primary>quoted text with paragraph indentation, displaying</primary></indexterm> <indexterm role="cp"><primary>displaying quoted text with paragraph indentation</primary></indexterm> <indexterm role="cp"><primary>paragraph indentations in quoted text</primary></indexterm> <indexterm role="fn"><primary>environment, <literal>quote</literal></primary></indexterm> <indexterm role="fn"><primary><literal>quote</literal> environment</primary></indexterm> + <indexterm role="cp"><primary>quoted text without paragraph indentation, displaying</primary></indexterm> <indexterm role="cp"><primary>displaying quoted text without paragraph indentation</primary></indexterm> <indexterm role="cp"><primary>paragraph indentations in quoted text, omitting</primary></indexterm> @@ -3813,6 +4577,7 @@ quotations. <indexterm role="fn"><primary>environment, <literal>tabbing</literal></primary></indexterm> <indexterm role="fn"><primary><literal>tabbing</literal> environment</primary></indexterm> + <indexterm role="cp"><primary>tab stops, using</primary></indexterm> <indexterm role="cp"><primary>lining text up using tab stops</primary></indexterm> <indexterm role="cp"><primary>alignment via tabbing</primary></indexterm> @@ -3820,23 +4585,69 @@ quotations. <para>Synopsis: </para> <screen>\begin{tabbing} -<replaceable>row1col1</replaceable> \= <replaceable>row1col2</replaceable> \= <replaceable>row1col3</replaceable> \= <replaceable>row1col4</replaceable> \\ -<replaceable>row2col1</replaceable> \> \> <replaceable>row2col3</replaceable> \\ +<replaceable>row1col1</replaceable> \= <replaceable>row1col2</replaceable> ... \\ +<replaceable>row2col1</replaceable> \> <replaceable>row2col2</replaceable> ... \\ ... \end{tabbing} </screen> -<para>The <literal>tabbing</literal> environment provides a way to align text in -columns. It works by setting tab stops and tabbing to them much as -was done on an ordinary typewriter. It is best suited for cases where -the width of each column is constant and known in advance. +<para>The <literal>tabbing</literal> environment aligns text in columns. It works by +setting tab stops and tabbing to them much as was done on a typewriter. +It is best suited for cases where the width of each column is constant +and known in advance. </para> -<para>This environment can be broken across pages, unlike the <literal>tabular</literal> -environment. +<para>This example has a first line where the tab stops are set to explicit +widths, ended by a <literal>\kill</literal> command (which is described below): </para> -<para>The following commands can be used inside a <literal>tabbing</literal> environment: +<screen>\begin{tabbing} +\hspace{0.75in} \= \hspace{0.40in} \= \hspace{0.40in} \kill +Ship \> Guns \> Year \\ +\textit{Sophie} \> 14 \> 1800 \\ +\textit{Polychrest} \> 24 \> 1803 \\ +\textit{Lively} \> 38 \> 1804 \\ +\textit{Surprise} \> 28 \> 1805 \\ +\end{tabbing} +</screen> +<para>Both the <literal>tabbing</literal> environment and the more widely-used +<literal>tabular</literal> environment put text in columns. The most important +distinction is that in <literal>tabular</literal> the width of columns is +determined automatically by &latex;, while in <literal>tabbing</literal> the user +sets the tab stops. Another distinction is that <literal>tabular</literal> +generates a box, but <literal>tabbing</literal> can be broken across pages. +Finally, while <literal>tabular</literal> can be used in any mode, <literal>tabbing</literal> +can be used only in paragraph mode and it starts a new paragraph. +</para> +<para>A <literal>tabbing</literal> environment always starts a new paragraph, without +indentation. Moreover, as shown in the example above, there is no need +to use the starred form of the <literal>\hspace</literal> command at the beginning +of a tabbed row. The right margin of the <literal>tabbing</literal> environment is +the end of line, so that the width of the environment is +<literal>\linewidth</literal>. +</para> +<indexterm role="cp"><primary>row, tabbing</primary></indexterm> +<para>The <literal>tabbing</literal> environment contains a sequence of <firstterm>tabbed +rows</firstterm>. The first tabbed row begins immediately after +<literal>\begin{tabbing}</literal> and each row ends with <literal>\\</literal> or +<literal>\kill</literal>. The last row may omit the <literal>\\</literal> and end with just +<literal>\end{tabbing}</literal>. +</para> +<para>At any point the <literal>tabbing</literal> environment has a current tab stop +pattern, a sequence of <inlineequation><mathphrase><replaceable>n</replaceable> > 0</mathphrase></inlineequation> tab stops, numbered 0, 1, +etc. These create <replaceable>n</replaceable> corresponding columns. Tab stop 0 is +always the left margin, defined by the enclosing environment. Tab +stop number <replaceable>i</replaceable> is set if it is assigned a horizontal +position on the page. Tab stop number <replaceable>i</replaceable> can only be set if +all the stops 0, …, <inlineequation><mathphrase>i-1</mathphrase></inlineequation> have already been set; normally +later stops are to the right of earlier ones. +</para> +<para>By default any text typeset in a <literal>tabbing</literal> environment is typeset +ragged right and left-aligned on the current tab stop. Typesetting is +done in LR mode (see <link linkend="Modes">Modes</link>). +</para> +<para>The following commands can be used inside a <literal>tabbing</literal> environment. +They are all fragile (see <link linkend="_005cprotect">\protect</link>). </para> <variablelist><varlistentry><term><indexterm role="fn"><primary>\\ (tabbing)</primary></indexterm><literal>\\ (tabbing)</literal> -</term><listitem><para>End a line. +</term><listitem><para>End a tabbed line and typeset it. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\= (tabbing)</primary></indexterm><literal>\= (tabbing)</literal> </term><listitem><para>Sets a tab stop at the current position. @@ -3859,34 +4670,35 @@ necessary. following commands one tab stop to the left, beginning tabbed line if necessary. </para> -</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\’ (tabbing)</primary></indexterm><literal>\' (tabbing)</literal> -</term><listitem><para>Moves everything that you have typed so far in the -current column, i.e., everything from the most recent <literal>\></literal>, -<literal>\<</literal>, <literal>\'</literal>, <literal>\\</literal>, or <literal>\kill</literal> command, to the right -of the previous column, flush against the current column’s tab stop. +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\' (tabbing)</primary></indexterm><literal>\' (tabbing)</literal> +</term><listitem><para>Moves everything that you have typed so far in the current column, i.e., +everything from the most recent <literal>\></literal>, <literal>\<</literal>, <literal>\'</literal>, +<literal>\\</literal>, or <literal>\kill</literal> command, to the previous column and aligned +to the right, flush against the current column’s tab stop. </para> -</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\‘ (tabbing)</primary></indexterm><literal>\` (tabbing)</literal> +</listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\` (tabbing)</primary></indexterm><literal>\` (tabbing)</literal> </term><listitem><para>Allows you to put text flush right against any tab stop, including tab -stop 0. However, it can’t move text to the right of the last column -because there’s no tab stop there. The <literal>\`</literal> command moves all the -text that follows it, up to the <literal>\\</literal> or <literal>\end{tabbing}</literal> -command that ends the line, to the right margin of the tabbing -environment. There must be no <literal>\></literal> or <literal>\'</literal> command between -the <literal>\`</literal> and the command that ends the line. +stop 0. However, it can’t move text to the right of the last +column because there’s no tab stop there. The <literal>\`</literal> command moves +all the text that follows it, up to the <literal>\\</literal> or +<literal>\end{tabbing}</literal> command that ends the line, to the right margin +of the <literal>tabbing</literal> environment. There must be no <literal>\></literal> or +<literal>\'</literal> command between the <literal>\`</literal> and the <literal>\\</literal> or +<literal>\end{tabbing}</literal> command that ends the line. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\a (tabbing)</primary></indexterm><literal>\a (tabbing)</literal> -</term><listitem><indexterm role="fn"><primary>\a’ (acute accent in tabbing)</primary></indexterm> -<indexterm role="fn"><primary>\a‘ (grave accent in tabbing)</primary></indexterm> +</term><listitem><indexterm role="fn"><primary>\a' (acute accent in tabbing)</primary></indexterm> +<indexterm role="fn"><primary>\a` (grave accent in tabbing)</primary></indexterm> <indexterm role="fn"><primary>\a= (macron accent in tabbing)</primary></indexterm> <para>In a <literal>tabbing</literal> environment, the commands <literal>\=</literal>, <literal>\'</literal> and <literal>\`</literal> do not produce accents as usual (see <link linkend="Accents">Accents</link>). Instead, -the commands <literal>\a=</literal>, <literal>\a'</literal> and <literal>\a`</literal> are used. +use the commands <literal>\a=</literal>, <literal>\a'</literal> and <literal>\a`</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\kill</primary></indexterm><literal>\kill</literal> -</term><listitem><para>Sets tab stops without producing text. Works just like <literal>\\</literal> -except that it throws away the current line instead of producing -output for it. The effect of any <literal>\=</literal>, <literal>\+</literal> or <literal>\-</literal> -commands in that line remain in effect. +</term><listitem><para>Sets tab stops without producing text. Works just like <literal>\\</literal> except +that it throws away the current line instead of producing output for it. +Any <literal>\=</literal>, <literal>\+</literal> or <literal>\-</literal> commands in that line remain in +effect. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\poptabs</primary></indexterm><literal>\poptabs</literal> </term><listitem><indexterm role="fn"><primary>\poptabs</primary></indexterm> @@ -3897,28 +4709,56 @@ commands in that line remain in effect. tab stop positions in the middle of a <literal>tabbing</literal> environment. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\tabbingsep</primary></indexterm><literal>\tabbingsep</literal> -</term><listitem><para>Distance to left of tab stop moved by <literal>\'</literal>. +</term><listitem><para>Distance of the text moved by <literal>\'</literal> to left of current tab stop. </para> </listitem></varlistentry></variablelist> -<para>This example typesets a Pascal function in a traditional format: +<para>This example typesets a Pascal function: </para> <screen>\begin{tabbing} function \= fact(n : integer) : integer;\\ \> begin \= \+ \\ - \> if \= n $>$ 1 then \+ \\ + \> if \= n > 1 then \+ \\ fact := n * fact(n-1) \- \\ else \+ \\ fact := 1; \-\- \\ end;\\ \end{tabbing} </screen> +<para>The output looks like this: +</para><screen>function fact(n : integer) : integer; + begin + if n > 1 then + fact := n * fact(n-1); + else + fact := 1; + end; +</screen> +<indexterm role="cp"><primary>package, <literal>algorithm2e</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>algorithm2e</literal> package</primary></indexterm> +<indexterm role="cp"><primary>package, <literal>listings</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>listings</literal> package</primary></indexterm> +<indexterm role="cp"><primary>package, <literal>minted</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>minted</literal> package</primary></indexterm> + +<indexterm role="cp"><primary>package, <literal>fancyvrb</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>fancyvrb</literal> package</primary></indexterm> + +<para>(The above example is just for illustration of the environment. To +actually typeset computer code in typewriter like this, a verbatim +environment (see <link linkend="verbatim">verbatim</link>) would normally suffice. For +pretty-printed code, there are quite a few packages, including +<literal>algorithm2e</literal>, <literal>fancyvrb</literal>, <literal>listings</literal>, and +<literal>minted</literal>.) +</para> + </sect1> <sect1 label="8.22" id="table"> <title><literal>table</literal></title> <indexterm role="fn"><primary>environment, <literal>table</literal></primary></indexterm> <indexterm role="fn"><primary><literal>table</literal> environment</primary></indexterm> + <indexterm role="cp"><primary>tables, creating</primary></indexterm> <indexterm role="cp"><primary>creating tables</primary></indexterm> @@ -3970,6 +4810,7 @@ unless it is pushed to a float page at the end. <indexterm role="fn"><primary>environment, <literal>tabular</literal></primary></indexterm> <indexterm role="fn"><primary><literal>tabular</literal> environment</primary></indexterm> + <indexterm role="cp"><primary>lines in tables</primary></indexterm> <indexterm role="cp"><primary>lining text up in tables</primary></indexterm> @@ -4326,6 +5167,7 @@ is required. <indexterm role="fn"><primary>environment, <literal>thebibliography</literal></primary></indexterm> <indexterm role="fn"><primary><literal>thebibliography</literal> environment</primary></indexterm> + <indexterm role="cp"><primary>bibliography, creating (manually)</primary></indexterm> <para>Synopsis: @@ -4339,13 +5181,29 @@ is required. reference list. </para> <para>In the <literal>article</literal> class, this reference list is labelled -“References”; in the <literal>report</literal> class, it is labelled -“Bibliography”. You can change the label (in the standard classes) -by redefining the command <literal>\refname</literal>. For instance, this -eliminates it entirely: +‘<literal>References</literal>’ and the label is stored in macro <literal>\refname</literal>; in +the <literal>report</literal> class, it is labelled ‘<literal>Bibliography</literal>’ and the +label is stored in macro <literal>\bibname</literal>. +</para> +<para>You can change the label by redefining the command <literal>\refname</literal> or +<literal>\bibname</literal>, whichever is applicable depending on the class: +</para> +<itemizedlist><listitem><indexterm role="fn"><primary>\bibname</primary></indexterm> +<para>For standard classes whose top level sectioning is <literal>\chapter</literal> +(such as <filename>book</filename> and <filename>report</filename>), the label is in the macro +<literal>\bibname</literal>; +</para> +</listitem><listitem><indexterm role="fn"><primary>\refname</primary></indexterm> +<para>For standard classes whose the top level sectioning is <literal>\section</literal> +(such as <filename>article</filename>), the label is in macro <literal>\refname</literal>. +</para></listitem></itemizedlist> +<indexterm role="cp"><primary>package, <literal>babel</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>babel</literal> package</primary></indexterm> + +<para>Typically it is neither necessary nor desirable to directly redefine +<literal>\refname</literal> or <literal>\bibname</literal>; language support packages like +<filename>babel</filename> do this. </para> -<screen>\renewcommand{\refname}{} -</screen> <para>The mandatory <replaceable>widest-label</replaceable> argument is text that, when typeset, is as wide as the widest item label produced by the <literal>\bibitem</literal> commands. It is typically given as <literal>9</literal> for bibliographies with @@ -4465,6 +5323,7 @@ Bib&tex; format. Only the entries referred to via <literal>\cite</literal> and <indexterm role="fn"><primary>environment, <literal>theorem</literal></primary></indexterm> <indexterm role="fn"><primary><literal>theorem</literal> environment</primary></indexterm> + <indexterm role="cp"><primary>theorems, typesetting</primary></indexterm> <para>Synopsis: @@ -4485,6 +5344,7 @@ possibilities for <replaceable>n</replaceable> are described under <literal>\new <indexterm role="fn"><primary>environment, <literal>titlepage</literal></primary></indexterm> <indexterm role="fn"><primary><literal>titlepage</literal> environment</primary></indexterm> + <indexterm role="cp"><primary>making a title page</primary></indexterm> <indexterm role="cp"><primary>title pages, creating</primary></indexterm> @@ -4531,6 +5391,7 @@ is left to the author. <indexterm role="fn"><primary>environment, <literal>verbatim</literal></primary></indexterm> <indexterm role="fn"><primary><literal>verbatim</literal> environment</primary></indexterm> + <indexterm role="cp"><primary>verbatim text</primary></indexterm> <indexterm role="cp"><primary>simulating typed text</primary></indexterm> <indexterm role="cp"><primary>typed text, simulating</primary></indexterm> @@ -4549,7 +5410,8 @@ which &latex; produces exactly what you type in; for instance the into a typewriter with carriage returns and blanks having the same effect that they would on a typewriter. </para> -<para>The <literal>verbatim</literal> uses a monospaced typewriter-like font (<literal>\tt</literal>). +<para>The <literal>verbatim</literal> environment uses a monospaced typewriter-like font +(<literal>\tt</literal>). </para> <sect2 label="8.27.1" id="_005cverb"> @@ -4581,6 +5443,7 @@ verbatim text. The delimiter must not appear in <replaceable>literal-text</repl <indexterm role="fn"><primary>environment, <literal>verse</literal></primary></indexterm> <indexterm role="fn"><primary><literal>verse</literal> environment</primary></indexterm> + <indexterm role="cp"><primary>poetry, an environment for</primary></indexterm> <para>Synopsis: @@ -5085,6 +5948,7 @@ sequence with other footnotes. </screen> <indexterm role="cp"><primary>package, <literal>footmisc</literal></primary></indexterm> <indexterm role="cp"><primary><literal>footmisc</literal> package</primary></indexterm> + <indexterm role="cp"><primary><literal>stable</literal> option to <literal>footmisc</literal> package</primary></indexterm> <para>causes the footnote to appear at the bottom of the page where the section starts, as usual, but also at the bottom of the table of @@ -5177,6 +6041,7 @@ footnotes. This is ‘<literal>6.65pt</literal>’ for ‘<literal> <para>&latex; has support for making new commands of many different kinds. </para> <!-- xx everything in this chapter needs examples. --> +<!-- xx Add DeclareRobustCommand (see clsguide.pdf) --> @@ -5681,11 +6546,14 @@ characters in each: <indexterm role="cp"><primary>fragile commands</primary></indexterm> <indexterm role="cp"><primary>robust commands</primary></indexterm> -<para>All &latex; commands are either <firstterm>fragile</firstterm> or <firstterm>robust</firstterm>. -Footnotes, line breaks, any command that has an optional argument, and -many more, are fragile. A fragile command can break when it is used in -the argument to certain commands. To prevent such commands from -breaking one solution is to have them preceded by the command +<para>All &latex; commands are either <firstterm>fragile</firstterm> or <firstterm>robust</firstterm>. A +fragile command can break when it is used in the argument to certain +other commands. Commands that contain data that &latex; writes to an +auxiliary file and re-reads later are fragile. This includes material +that goes into a table of contents, list of figures, list of tables, +etc. Fragile commands also include line breaks, any command that has an +optional argument, and many more. To prevent such commands from +breaking, one solution is to preceded them with the command <literal>\protect</literal>. </para> <para>For example, when &latex; runs the <literal>\section{<replaceable>section @@ -5733,6 +6601,87 @@ to <literal>\protect\(..\protect\)</literal>. </screen> </sect1> +<sect1 label="12.10" id="_005cignorespaces-_0026-_005cignorespacesafterend"> +<title><literal>\ignorespaces & \ignorespacesafterend</literal></title> + +<indexterm role="fn"><primary>\ignorespaces</primary></indexterm> +<indexterm role="fn"><primary>\ignorespacesafterend</primary></indexterm> +<indexterm role="cp"><primary>spaces, ignore around commands</primary></indexterm> +<indexterm role="cp"><primary>commands, ignore spaces</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\ignorespaces +</screen> +<para>or +</para> +<screen>\ignorespacesafterend +</screen> +<para>Both commands cause &latex; to ignore spaces after the end of the +command up until the first non-space character. The first is a command +from Plain &tex;, and the second is &latex;-specific. +</para> +<para>The <literal>ignorespaces</literal> is often used when defining commands via +<literal>\newcommand</literal>, or <literal>\newenvironment</literal>, or <literal>\def</literal>. The +example below illustrates. It allows a user to show the points values +for quiz questions in the margin but it is inconvenient because, as +shown in the <literal>enumerate</literal> list, users must not put any space between +the command and the question text. +</para> +<screen>\newcommand{\points}[1]{\makebox[0pt]{\makebox[10em][l]{#1~pts}} +\begin{enumerate} + \item\points{10}no extra space output here + \item\points{15} extra space output between the number and the word `extra' +\end{enumerate} +</screen> +<para>The solution is to change to +<literal>\newcommand{\points}[1]{\makebox[0pt]{\makebox[10em][l]{#1~pts}}\ignorespaces}</literal>. +</para> +<para>A second example shows spaces being removed from the front of text. The +commands below allow a user to uniformly attach a title to names. But, +as given, if a title accidentally starts with a space then +<literal>\fullname</literal> will reproduce that. +</para> +<screen>\makeatletter +\newcommand{\honorific}[1]{\def\@honorific{#1}} % remember title +\newcommand{\fullname}[1]{\@honorific~#1} % recall title; put before name +\makeatother +\begin{tabular}{|l|} +\honorific{Mr/Ms} \fullname{Jones} \\ % no extra space here +\honorific{ Mr/Ms} \fullname{Jones} % extra space before title +\end{tabular} +</screen> +<para>To fix this, change to +<literal>\newcommand{\fullname}[1]{\ignorespaces\@honorific~#1}</literal>. +</para> +<para>The <literal>\ignorespaces</literal> is also often used in a <literal>\newenvironment</literal> +at the end of the <replaceable>begin</replaceable> clause, that is, as part of the second +argument, as in <literal>\begin{newenvironment}{<replaceable>env +name</replaceable>}{... \ignorespaces}{...}</literal>. +</para> +<para>To strip spaces off the end of an environment use +<literal>\ignorespacesafterend</literal>. An example is that this will show a much +larger vertical space between the first and second environments than +between the second and third. +</para> +<screen>\newenvironment{eq}{\begin{equation}}{\end{equation}} +\begin{eq} +e=mc^2 +\end{eq} +\begin{equation} +F=ma +\end{equation} +\begin{equation} +E=IR +\end{equation} +</screen> +<para>Putting a comment character <literal>%</literal> immediately after the +<literal>\end{eq}</literal> will make the vertical space disappear, but that is +inconvenient. The solution is to change to +<literal>\newenvironment{eq}{\begin{equation}}{\end{equation}\ignorespacesafterend}</literal>. +</para> + +</sect1> </chapter> <chapter label="13" id="Counters"> <title>Counters</title> @@ -5802,14 +6751,17 @@ symbols (conventionally used for labeling footnotes). The value of </para> <para>Here are the symbols: </para> -<informaltable><tgroup cols="3"><colspec colwidth="33*"></colspec><colspec colwidth="33*"></colspec><colspec colwidth="33*"></colspec><thead><row><entry><para>Name</para></entry><entry><para>Command</para></entry><entry><para>Equivalent Unicode symbol and/or numeric code point<!-- --> -</para></entry></row></thead><tbody><row><entry><para>asterisk</para></entry><entry><para><literal>\ast</literal></para></entry><entry><para>*<!-- --> +<informaltable><tgroup cols="3"><colspec colwidth="33*"></colspec><colspec colwidth="33*"></colspec><colspec colwidth="33*"></colspec><thead><row><entry><para>Name</para></entry><entry><para>Command</para></entry><entry><para>Equivalent Unicode symbol and/or numeric code point<!-- + --> +</para></entry></row></thead><tbody><row><entry><para>asterisk</para></entry><entry><para><literal>\ast</literal></para></entry><entry><para>*<!-- + --> </para></entry></row><row><entry><para>dagger</para></entry><entry><para><literal>\dagger</literal></para></entry><entry><para>† </para></entry></row><row><entry><para>ddagger</para></entry><entry><para><literal>\ddagger</literal></para></entry><entry><para>‡ </para></entry></row><row><entry><para>section-sign</para></entry><entry><para><literal>\S</literal></para></entry><entry><para>§ </para></entry></row><row><entry><para>paragraph-sign</para></entry><entry><para><literal>\P</literal></para></entry><entry><para>¶ </para></entry></row><row><entry><para>double-vert</para></entry><entry><para><literal>\parallel</literal></para></entry><entry><para>‖ -</para></entry></row><row><entry><para>double-asterisk</para></entry><entry><para><literal>\ast\ast</literal></para></entry><entry><para>**<!-- --> +</para></entry></row><row><entry><para>double-asterisk</para></entry><entry><para><literal>\ast\ast</literal></para></entry><entry><para>**<!-- + --> </para></entry></row><row><entry><para>double-dagger</para></entry><entry><para><literal>\dagger\dagger</literal></para></entry><entry><para>†† </para></entry></row><row><entry><para>double-ddagger</para></entry><entry><para><literal>\ddagger\ddagger</literal></para></entry><entry><para>‡‡ </para></entry></row></tbody></tgroup></informaltable> @@ -6323,10 +7275,13 @@ notes from falling off the bottom of the page. <indexterm role="cp"><primary>math mode, entering</primary></indexterm> <indexterm role="fn"><primary>environment, <literal>math</literal></primary></indexterm> <indexterm role="fn"><primary><literal>math</literal> environment</primary></indexterm> + <indexterm role="fn"><primary>environment, <literal>displaymath</literal></primary></indexterm> <indexterm role="fn"><primary><literal>displaymath</literal> environment</primary></indexterm> + <indexterm role="fn"><primary>environment, <literal>equation</literal></primary></indexterm> <indexterm role="fn"><primary><literal>equation</literal> environment</primary></indexterm> + <para>There are three environments that put &latex; in math mode: </para> @@ -6614,7 +7569,7 @@ arrow <literal>\Downarrow</literal>. arrow <literal>\downarrow</literal>. </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\ell</primary></indexterm><literal>\ell</literal> -</term><listitem><para>ℓ Lower-case cursive letter l (ordinary). +</term><listitem><para>ℓ Lowercase cursive letter l (ordinary). </para> </listitem></varlistentry><varlistentry><term><indexterm role="fn"><primary>\emptyset</primary></indexterm><literal>\emptyset</literal> </term><listitem><para>∅ Empty set symbol (ordinary). The variant form is @@ -7940,8 +8895,60 @@ space that does not disappear at line breaks use </para> </sect1> -<sect1 label="19.3" id="_005c_0028SPACE_0029-and-_005c_0040"> -<title><literal>\(SPACE)</literal> and \@</title> +<sect1 label="19.3" id="_005cspacefactor"> +<title><literal>\spacefactor</literal></title> + +<para>Synopsis: +</para> +<screen>\spacefactor=<replaceable>integer</replaceable> +</screen> +<indexterm role="fn"><primary>\spacefactor</primary></indexterm> +<para>While &latex; is making the page, to give the lines the best appearance +it may stretch or shrink the gaps between words. The +<literal>\spacefactor</literal> command (from Plain &tex;) allows you to +change the &latex;’s default behavior. +</para> +<para>After &latex; places each character, or rule or other box, it sets a +parameter called the <firstterm>space factor</firstterm>. If the next thing in the input +is a space then this parameter affects how much of a horizontal gap +&latex; will have it span. (This gap is not a character; it is called +<firstterm>interword glue</firstterm>.) A larger space factor means that the glue gap +can stretch more and shrink less. +</para> +<para>Normally, the space factor is 1000; this value is in effect following +most characters, and any non-character box or math formula. But it is +3000 after a period, exclamation mark, or question mark, it is 2000 +after a colon, 1500 after a semicolon, 1250 after a comma, and 0 after a +right parenthesis or bracket, or closing double quote or single quote. +Finally, it is 999 after a capital letter. +</para> +<para>If the space factor <replaceable>f</replaceable> is 1000 then the glue gap will be the +font’s normal space value (for Computer Modern Roman 10 point this is +3.3333 points). Otherwise, if the space factor <replaceable>f</replaceable> is greater +than 2000 then &tex; adds the font’s extra space value (for Computer +Modern Roman 10 point this is 1.11111 points), and then the font’s +normal stretch value is multiplied by <inlineequation><mathphrase>f /1000</mathphrase></inlineequation> and the normal +shrink value is multiplied by <inlineequation><mathphrase>1000/f</mathphrase></inlineequation> (for Computer Modern Roman +10 point these are 1.66666 and 1.11111 points). In short, compared +to a normal space, such as the space following a word ending in a +lowercase letter, inter-sentence spacing has a fixed extra space added +and then the space can stretch 3 times as much and shrink 1/3 as much. +</para> +<para>The rules for how &tex; uses space factors are even more complex +because they play two more roles. In practice, there are two +consequences. First, if a period or other punctuation is followed by a +close parenthesis or close double quote then its effect is still in +place, that is, the following glue will have increased stretch and +shrink. Second, conversely, if punctuation comes after a capital letter +then its effect is not in place so you get an ordinary space. For how +to adjust to this second case, for instance if an abbreviation does not +end in a capital letter, see <link linkend="_005c_0028SPACE_0029-and-_005c_0040">\(SPACE) and \@</link>. +</para> + + + +<sect2 label="19.3.1" id="_005c_0028SPACE_0029-and-_005c_0040"> +<title><literal>\(SPACE)</literal> and <literal>\@</literal></title> <indexterm role="fn"><primary>\(SPACE)</primary></indexterm> <indexterm role="fn"><primary>\TAB</primary></indexterm> @@ -7949,39 +8956,65 @@ space that does not disappear at line breaks use <indexterm role="fn"><primary>\@</primary></indexterm> <anchor id="_005cAT"/><!-- old name --> -<para>Mark a punctuation character, typically a period, as either ending a -sentence or as ending an abbreviation. +<para>Here, <literal>\(SPACE)</literal> means a backslash followed by a space. These +commands mark a punctuation character, typically a period, as either +ending a sentence or as ending an abbreviation. </para> <para>By default, in justifying a line &latex; adjusts the space after a sentence-ending period (or a question mark, exclamation point, comma, or -colon) more than the space between words -(see <link linkend="_005cfrenchspacing">\frenchspacing</link>). &latex; assumes that the period ends a -sentence unless it is preceded by a capital letter, in which case it -takes that period for part of an abbreviation. Note that if a -sentence-ending period is immediately followed by a right parenthesis or -bracket, or right single or double quote, then the inter-sentence space -follows that parenthesis or quote. -</para> -<para>If you have a period ending an abbreviation whose last letter is not a -capital letter, and that abbreviation is not the last word in the +colon) more than the space between words. See <link linkend="_005cspacefactor">\spacefactor</link>. As +described there, &latex; assumes that the period ends a sentence unless +it is preceded by a capital letter, in which case it takes that period +for part of an abbreviation. Note that if a sentence-ending period is +immediately followed by a right parenthesis or bracket, or right single +or double quote, then the space effect of that period follows through +that parenthesis or quote. +</para> +<para>So: if you have a period ending an abbreviation whose last letter is not +a capital letter, and that abbreviation is not the last word in the sentence, then follow that period with a backslash-space (<literal>\ </literal>) or -a tie (<literal>~</literal>). Examples are <literal>Nat.\ Acad.\ Science</literal>, and -<literal>Mr.~Bean</literal>, and <literal>(manure, etc.)\ for sale</literal>. -</para> -<para>For another use of <literal>\ </literal>, see <link linkend="_005c_0028SPACE_0029-after-control-sequence">\(SPACE) after control sequence</link>. +a tie (<literal>~</literal>) or a <literal>\@</literal>. Examples are <literal>Nat.\ Acad.\ +Science</literal>, and <literal>Mr.~Bean</literal>, and <literal>(manure, etc.\@) for sale</literal> +(note that in the last the <literal>\@</literal> comes before the closing parenthesis). </para> <para>In the opposite situation, if you have a capital letter followed by a -period that ends the sentence, then put <literal>\@</literal> before that period. -For example, <literal>book by the MAA\@.</literal> will have inter-sentence -spacing after the period. +period that does end the sentence, then put <literal>\@</literal> before the +period. For example, <literal>book by the MAA\@.</literal> will have correct +inter-sentence spacing after the period. </para> -<para>In contrast, putting <literal>\@</literal> after a period tells &tex; that the -period does not end the sentence. In the example <literal>reserved words -(if, then, etc.\@) are different</literal>, &tex; will put interword space -after the closing parenthesis (note that <literal>\@</literal> is before the -parenthesis). +<para>For another use of <literal>\(SPACE)</literal>, see <link linkend="_005c_0028SPACE_0029-after-control-sequence">\(SPACE) after control sequence</link>. </para> +</sect2> +<sect2 label="19.3.2" id="_005cfrenchspacing"> +<title><literal>\frenchspacing</literal></title> + +<indexterm role="fn"><primary>\frenchspacing</primary></indexterm> +<indexterm role="fn"><primary>\nonfrenchspacing</primary></indexterm> +<indexterm role="cp"><primary>spacing, inter-sentence</primary></indexterm> + +<para>This declaration (from Plain &tex;) causes &latex; to treat +inter-sentence spacing in the same way as interword spacing. +</para> +<para>In justifying the text in a line, some typographic traditions, including +English, prefer to adjust the space between sentences (or after other +punctuation marks) more than the space between words. Following this +declaration, all spaces are instead treated equally. +</para> +<para>Revert to the default behavior by declaring <literal>\nonfrenchspacing</literal>. +</para> + +</sect2> +<sect2 label="19.3.3" id="_005cnormalsfcodes"> +<title><literal>\normalsfcodes</literal></title> + +<indexterm role="fn"><primary>\normalsfcodes</primary></indexterm> +<indexterm role="cp"><primary>spacing, inter-sentence</primary></indexterm> + +<para>Reset the &latex; space factor values to the default. +</para> + +</sect2> </sect1> <sect1 label="19.4" id="_005c_0028SPACE_0029-after-control-sequence"> <title><literal>\ </literal> after control sequence</title> @@ -8003,31 +9036,13 @@ by a space or by a punctuation mark. Compare: </screen> <indexterm role="cp"><primary>package, <literal>xspace</literal></primary></indexterm> <indexterm role="cp"><primary><literal>xspace</literal> package</primary></indexterm> + <para>Some individual commands, notably those defined with the <literal>xspace</literal>, package do not follow the standard behavior. </para> </sect1> -<sect1 label="19.5" id="_005cfrenchspacing"> -<title><literal>\frenchspacing</literal></title> - -<indexterm role="fn"><primary>\frenchspacing</primary></indexterm> -<indexterm role="fn"><primary>\nonfrenchspacing</primary></indexterm> -<indexterm role="cp"><primary>spacing, inter-sentence</primary></indexterm> - -<para>This declaration (from Plain &tex;) causes &latex; to treat -inter-sentence spacing in the same way as interword spacing. -</para> -<para>In justifying the text in a line, some typographic traditions, including -English, prefer to adjust the space between sentences (or after other -punctuation marks) more than the space between words. Following this -declaration, all spaces are instead treated equally. -</para> -<para>Revert to the default behavior by declaring <literal>\nonfrenchspacing</literal>. -</para> - -</sect1> -<sect1 label="19.6" id="_005cthinspace"> +<sect1 label="19.5" id="_005cthinspace"> <title><literal>\thinspace</literal>: Insert 1/6em</title> <indexterm role="fn"><primary>\thinspace</primary></indexterm> @@ -8038,7 +9053,7 @@ quotes, as in ’”.<!-- Abuse @dmn, which is a thin space in Texinfo. </para> </sect1> -<sect1 label="19.7" id="_005c_002f"> +<sect1 label="19.6" id="_005c_002f"> <title><literal>\/</literal>: Insert italic correction</title> <indexterm role="fn"><primary>\/</primary></indexterm> @@ -8071,7 +9086,7 @@ in a different way. </para> </sect1> -<sect1 label="19.8" id="_005chrulefill-_005cdotfill"> +<sect1 label="19.7" id="_005chrulefill-_005cdotfill"> <title><literal>\hrulefill \dotfill</literal></title> <indexterm role="fn"><primary>\hrulefill</primary></indexterm> @@ -8100,7 +9115,7 @@ length of 0.33em to 1.00em. </para> </sect1> -<sect1 label="19.9" id="_005caddvspace"> +<sect1 label="19.8" id="_005caddvspace"> <title><literal>\addvspace</literal></title> <indexterm role="fn"><primary>\addvspace</primary></indexterm> @@ -8129,7 +9144,7 @@ change that is to precede this command with a <literal>\par</literal> command. </para> </sect1> -<sect1 label="19.10" id="_005cbigskip-_005cmedskip-_005csmallskip"> +<sect1 label="19.9" id="_005cbigskip-_005cmedskip-_005csmallskip"> <title><literal>\bigskip \medskip \smallskip</literal></title> <para>These commands produce a given amount of space, specified by the @@ -8157,7 +9172,7 @@ quarter of a line space, with stretch and shrink (the default for the </listitem></varlistentry></variablelist> </sect1> -<sect1 label="19.11" id="_005cvfill"> +<sect1 label="19.10" id="_005cvfill"> <title><literal>\vfill</literal></title> <indexterm role="fn"><primary>\vfill</primary></indexterm> @@ -8189,7 +9204,7 @@ Lost Dog! </screen> </sect1> -<sect1 label="19.12" id="_005cvspace"> +<sect1 label="19.11" id="_005cvspace"> <title><literal>\vspace{<replaceable>length</replaceable>}</literal></title> <indexterm role="fn"><primary>\vspace</primary></indexterm> @@ -8270,8 +9285,8 @@ argument. <!-- xxref --> <indexterm role="fn"><primary>\fboxrule</primary></indexterm> <indexterm role="fn"><primary>\fboxsep</primary></indexterm> <para>Both commands produce a rule of thickness <literal>\fboxrule</literal> (default -‘<literal>.4pt</literal>’), and leave a space of <literal>\fboxsep</literal> (default -‘<literal>3pt</literal>’) between the rule and the contents of the box. +<literal>0.4pt</literal>), and leave a space of <literal>\fboxsep</literal> (default <literal>3pt</literal>) +between the rule and the contents of the box. </para> <para>See <link linkend="_005cframebox-_0028picture_0029">\framebox (picture)</link>, for the <literal>\framebox</literal> command in the <literal>picture</literal> environment. @@ -8335,8 +9350,9 @@ see <link linkend="_005cmakebox-_0028picture_0029">\makebox (picture)</link>. </para> <screen>\parbox[<replaceable>position</replaceable>][<replaceable>height</replaceable>][<replaceable>inner-pos</replaceable>]{<replaceable>width</replaceable>}{<replaceable>text</replaceable>} </screen> +<indexterm role="cp"><primary>paragraph mode</primary></indexterm> <para>The <literal>\parbox</literal> command produces a box whose contents are created -in <literal>paragraph</literal> mode. It should be used to make a box small +in <firstterm>paragraph mode</firstterm>. It should be used to make a box small pieces of text, with nothing fancy inside. In particular, you shouldn’t use any paragraph-making environments inside a <literal>\parbox</literal> argument. For larger pieces of text, including ones @@ -8444,7 +9460,1130 @@ included in the normal output, it is saved in the box labeled </sect1> </chapter> -<chapter label="21" id="Special-insertions"> +<chapter label="21" id="Color"> +<title>Color</title> + +<indexterm role="cp"><primary>color</primary></indexterm> + +<para>You can add color to text, rules, etc. You can also have color in a box +or on an entire page and write text on top of it. +</para> +<para>Color support comes as an additional package. So all the commands below +will only work if your document preamble contains +<literal>\usepackage{color}</literal>, that brings in the standard package. +</para> +<para>Many other packages also supplement &latex;’s color abilities. +Particularly worth mentioning is <filename>xcolor</filename>, which is widely used and +significantly extends the capabilities described here, including adding +‘<literal>HTML</literal>’ and ‘<literal>Hsb</literal>’ color models. +</para> + + +<sect1 label="21.1" id="Color-package-options"> +<title>Color package options</title> + +<indexterm role="cp"><primary>color package options</primary></indexterm> +<indexterm role="cp"><primary>options, color package</primary></indexterm> + +<para>Synopsis (must be in the document preamble): +</para> +<screen>\usepackage[<replaceable>comma-separated option list</replaceable>]{color} +</screen> +<para>When you load the <filename>color</filename> package there are two kinds of available +options. +</para> +<para>The first specifies the <firstterm>printer driver</firstterm>. &latex; doesn’t contain +information about different output systems but instead depends on +information stored in a file. Normally you should not specify the +driver option in the document, and instead rely on your system’s +default. One advantage of this is that it makes the document portable +across systems. For completeness we include a list of the drivers. The +currently relevant ones are: <filename>dvipdfmx</filename>, <filename>dvips</filename>, +<filename>dvisvgm</filename>, <filename>luatex</filename>, <filename>pdftex</filename>, <filename>xetex</filename>. The two +<filename>xdvi</filename> and <filename>oztex</filename> are essentially aliases for <filename>dvips</filename> +(and <filename>xdvi</filename> is monochrome). Ones that should not be used for new +systems are: <filename>dvipdf</filename>, <filename>dvipdfm</filename>, <filename>dviwin</filename>, +<filename>dvipsone</filename>, <filename>emtex</filename>, <filename>pctexps</filename>, <filename>pctexwin</filename>, +<filename>pctexhp</filename>, <filename>pctex32</filename>, <filename>truetex</filename>, <filename>tcidvi</filename>, +<filename>vtex</filename> (and <filename>dviwindo</filename> is an alias for <filename>dvipsone</filename>). +</para> +<para>The second kind of options, beyond the drivers, are below. +</para> +<variablelist> +<varlistentry><term><literal>monochrome</literal> +</term><listitem><para>Disable the color commands, so that they do not generate errors but do +not generate color either. +</para> +</listitem></varlistentry><varlistentry><term><literal>dvipsnames</literal> +</term><listitem><para>Make available a list of 68 color names that are often used, +particularly in legacy documents. These color names were originally +provided by the <filename>dvips</filename> driver, giving the option name. +</para> +</listitem></varlistentry><varlistentry><term><literal>nodvipsnames</literal> +</term><listitem><para>Do not load that list of color names, saving &latex; a tiny amount of +memory space. +</para> +</listitem></varlistentry></variablelist> + +</sect1> +<sect1 label="21.2" id="Color-models"> +<title>Color models</title> + +<indexterm role="cp"><primary>color models</primary></indexterm> + +<para>A <firstterm>color model</firstterm> is a way of representing colors. &latex;’s +capabilities depend on the printer driver. However, the <filename>pdftex</filename>, +<filename>xetex</filename>, and <filename>luatex</filename> printer drivers are today by far the +most commonly used. The models below work for those drivers. All but +one of these is also supported by essentially all other printer drivers +used today. +</para> +<para>Note that color combination can be additive or subtractive. Additive +mixes colors of light, so that for instance combining full intensities +of red, green, and blue produces white. Subtractive mixes pigments, +such as with inks, so that combining full intensity of cyan, magenta, +and yellow makes black. +</para> +<variablelist><varlistentry><term><literal>cmyk</literal> +</term><listitem><para>A comma-separated list with four real numbers between 0 and 1, +inclusive. The first number is the intensity of cyan, the second is +magenta, and the others are yellow and black. A number value of 0 means +minimal intensity, while a 1 is for full intensity. This model is often +used in color printing. It is a subtractive model. +</para> +</listitem></varlistentry><varlistentry><term><literal>gray</literal> +</term><listitem><para>A single real number between 0 and 1, inclusive. The colors are shades +of grey. The number 0 produces black while 1 gives white. +</para> +</listitem></varlistentry><varlistentry><term><literal>rgb</literal> +</term><listitem><para>A comma-separated list with three real numbers between 0 and 1, +inclusive. The first number is the intensity of the red component, the +second is green, and the third the blue. A number value of 0 means that +none of that component is added in, while a 1 means full intensity. +This is an additive model. +</para> +</listitem></varlistentry><varlistentry><term><literal>RGB</literal> +</term><listitem><para>(<filename>pdftex</filename>, <filename>xetex</filename>, <filename>luatex</filename> drivers) A comma-separated +list with three integers between 0 and 255, inclusive. This model is a +convenience for using <literal>rgb</literal> since outside of &latex; colors are +often described in a red-green-blue model using numbers in this range. +The values entered here are converted to the <literal>rgb</literal> model by +dividing by 255. +</para> +</listitem></varlistentry><varlistentry><term><literal>named</literal> +</term><listitem><para>Colors are accessed by name, such as ‘<literal>PrussianBlue</literal>’. The list of +names depends on the driver, but all support the names ‘<literal>black</literal>’, +‘<literal>blue</literal>’, ‘<literal>cyan</literal>’, ‘<literal>green</literal>’, ‘<literal>magenta</literal>’, ‘<literal>red</literal>’, +‘<literal>white</literal>’, and ‘<literal>yellow</literal>’ (See the <literal>dvipsnames</literal> option in +<link linkend="Color-package-options">Color package options</link>). +</para> +</listitem></varlistentry></variablelist> + +</sect1> +<sect1 label="21.3" id="Commands-for-color"> +<title>Commands for color</title> + +<indexterm role="cp"><primary>color package commands</primary></indexterm> + +<para>These are the commands available with the <filename>color</filename> package. +</para> + + +<sect2 label="21.3.1" id="Define-colors"> +<title>Define colors</title> + +<indexterm role="cp"><primary>color</primary></indexterm> +<indexterm role="cp"><primary>define color</primary></indexterm> +<indexterm role="cp"><primary>color, define</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\definecolor{<replaceable>name</replaceable>}{<replaceable>model</replaceable>}{<replaceable>specification</replaceable>} +</screen> +<para>Give the name <replaceable>name</replaceable> to the color. For example, after +<literal>\definecolor{silver}{rgb}{0.75,0.75,0.74}</literal> you can use that +color name with <literal>Hi ho, \textcolor{silver}{Silver}!</literal>. +</para> +<para>This example gives the color a more abstract name, so it could change and +not be misleading. +</para> +<screen>\definecolor{logocolor}{RGB}{145,92,131} % RGB needs pdflatex +\newcommand{\logo}{\textcolor{logocolor}{Bob's Big Bagels}} +</screen> +<para>Often a document’s colors are defined in the preamble, or in the class +or style, rather than in the document body. +</para> + +</sect2> +<sect2 label="21.3.2" id="Colored-text"> +<title>Colored text</title> + +<indexterm role="cp"><primary>color</primary></indexterm> +<indexterm role="cp"><primary>colored text</primary></indexterm> + +<para>Synopses: +</para> +<screen>\textcolor{<replaceable>name</replaceable>}{...} +\textcolor[<replaceable>color model</replaceable>]{<replaceable>color specification</replaceable>}{...} +</screen> +<para>or +</para> +<screen>\color{<replaceable>name</replaceable>} +\color[<replaceable>color model</replaceable>]{<replaceable>specification</replaceable>} +</screen> +<para>The affected text gets the color. This line +</para> +<screen>\textcolor{magenta}{My name is Ozymandias, king of kings:} Look on my works, ye Mighty, and despair! +</screen> +<para>causes the first half to be in magenta while the rest is in black. You +can use a color declared with <literal>\definecolor</literal> in exactly the same +way that we just used the builtin color ‘<literal>magenta</literal>’. +</para> +<screen>\definecolor{MidlifeCrisisRed}{rgb}{1.0,0.11,0.0} +I'm thinking about getting a \textcolor{MidlifeCrisisRed}{sports car}. +</screen> +<para>The two <literal>\textcolor</literal> and <literal>\color</literal> differ in that the first is +a command form, enclosing the text to be colored as an argument. Often +this form is more convenient, or at least more explicit. The second +form is a declaration, as in <literal>The moon is made of {\color{green} +green} cheese</literal>, so it is in effect until the end of the current group +or environment. This is sometimes useful when writing macros or as +below where it colors everything inside the <literal>center</literal> environment, +including the vertical and horizontal lines. +</para> +<screen>\begin{center} \color{blue} + \begin{tabular}{l|r} + UL &UR \\ \hline + LL &LR + \end{tabular} +\end{center} +</screen> +<para>You can use color in equations. A document might have +<literal>\definecolor{highlightcolor}{RGB}{225,15,0}</literal> in the +preamble, and then contain this equation. +</para> +<screen>\begin{equation} + \int_a^b \textcolor{highlightcolor}{f'(x)}\,dx=f(b)-f(a) +\end{equation} +</screen> +<para>Typically the colors used in a document are declared in a class or style +but sometimes you want a one-off. Those are the second forms in the +synopses. +</para> +<screen>Colors of \textcolor[rgb]{0.33,0.14,0.47}{Purple} and {\color[rgb]{0.72,0.60,0.37} Gold} for the team +</screen> +<para>The format of <replaceable>color specification </replaceable> depends on the color model +(see <link linkend="Color-models">Color models</link>). For instance, while <literal>rgb</literal> takes three +numbers, <literal>gray</literal> takes only one. +</para> +<screen>The selection was \textcolor[gray]{0.5}{grayed out}. +</screen> +<para>Colors inside colors do not combine. Thus +</para> +<screen>\textcolor{green}{kind of \textcolor{blue}{blue}} +</screen> +<para>has a final word that is blue, not a combination of blue and green. +</para> +<!-- xx address coloring a line of a table? --> + + +</sect2> +<sect2 label="21.3.3" id="Colored-boxes"> +<title>Colored boxes</title> + +<indexterm role="cp"><primary>color</primary></indexterm> +<indexterm role="cp"><primary>colored boxes</primary></indexterm> +<indexterm role="cp"><primary>box, colored</primary></indexterm> + +<para>Synopses: +</para> +<screen>\colorbox{<replaceable>name</replaceable>}{...} +\colorbox[<replaceable>model name</replaceable>]{<replaceable>box background color specification</replaceable>}{...} +</screen> +<para>or +</para> +<screen>\fcolorbox{<replaceable>frame color</replaceable>}{<replaceable>box background color</replaceable>}{...} +\fcolorbox[<replaceable>model name</replaceable>]{<replaceable>frame color specification</replaceable>}{<replaceable>box background color specification</replaceable>}{...} +</screen> +<para>Make a box with the stated background color. The <literal>\fcolorbox</literal> +command puts a frame around the box. For instance this +</para> +<screen>Name:~\colorbox{cyan}{\makebox[5cm][l]{\strut}} +</screen> +<para>makes a cyan-colored box that is five centimeters long and gets its +depth and height from the <literal>\strut</literal> (so the depth is +<literal>-.3\baselineskip</literal> and the height is <literal>\baselineskip</literal>). This +puts white text on a blue background. +</para> +<screen>\colorbox{blue}{\textcolor{white}{Welcome to the machine.}} +</screen> +<para>The <literal>\fcolorbox</literal> commands use the same parameters as <literal>\fbox</literal> +(see <link linkend="_005cfbox-and-_005cframebox">\fbox and \framebox</link>), <literal>\fboxrule</literal> and <literal>\fboxsep</literal>, to +set the thickness of the rule and the boundary between the box interior +and the surrounding rule. &latex;’s defaults are <literal>0.4pt</literal> and +<literal>3pt</literal>, respectively. +</para> +<para>This example changes the thickness of the border to 0.8 points. Note +that it is surrounded by curly braces so that the change ends at the end +of the second line. +</para> +<screen>{\setlength{\fboxrule}{0.8pt} +\fcolorbox{black}{red}{Under no circumstances turn this knob.}} +</screen> + +</sect2> +<sect2 label="21.3.4" id="Colored-pages"> +<title>Colored pages</title> + +<indexterm role="cp"><primary>color</primary></indexterm> +<indexterm role="cp"><primary>colored page</primary></indexterm> +<indexterm role="cp"><primary>page, colored</primary></indexterm> +<indexterm role="cp"><primary>background, colored</primary></indexterm> + +<para>Synopses: +</para> +<screen>\pagecolor{<replaceable>name</replaceable>} +\pagecolor[<replaceable>color model</replaceable>]{<replaceable>color specification</replaceable>} +\nopagecolor +</screen> +<para>The first two set the background of the page, and all subsequent pages, +to the color. For an explanation of the specification in the second +form see <link linkend="Colored-text">Colored text</link>. The third returns the background to normal, +which is a transparent background. (If that is not supported use +<literal>\pagecolor{white}</literal>, although that will make a white background +rather than the default transparent background.) +</para> +<screen> ... +\pagecolor{cyan} + ... +\nopagecolor +</screen> + +</sect2> +</sect1> +</chapter> +<chapter label="22" id="Graphics"> +<title>Graphics</title> + +<indexterm role="cp"><primary>graphics</primary></indexterm> +<indexterm role="cp"><primary>graphics package</primary></indexterm> + +<para>You can use graphics such as PNG or PDF files in your &latex; document. +You need an additional package, which comes standard with &latex;. +This example is the short how-to. +</para> +<screen>\include{graphicx} % goes in the preamble + ... +\includegraphics[width=0.5\linewidth]{plot.pdf} +</screen> +<para>To use the commands described here your document preamble must contain +either <literal>\usepackage{graphicx}</literal> or +<literal>\usepackage{graphics}</literal>. Most of the time, <filename>graphicx</filename> is the +better choice. +</para> +<para>Graphics come in two main types, raster and vector. &latex; can use +both. In raster graphics the file contains an entry for each location +in an array, describing what color it is. An example is a photograph, +in JPG format. In vector graphics, the file contains a list of +instructions such as ‘<literal>draw a circle with this radius and that +center</literal>’. An example is a line drawing produced by the Asymptote +program, in PDF format. Generally vector graphics are more useful +because you can rescale their size without pixelation or other problems, +and because they often have a smaller size. +</para> +<para>There are systems particularly well-suited to make graphics for a +&latex; document. For example, these allow you to use the same fonts +as in your document. &latex; comes with a <literal>picture</literal> environment +(see <link linkend="picture">picture</link>) that has simple capabilities. Besides that, there are +other ways to include the graphic-making commands in the document. Two +such systems are the PSTricks and TikZ packages. There are also systems +external to &latex;, that generate a graphic that you include using the +commands of this chapter. Two that use a programming language are +Asymptote and MetaPost. One that uses a graphical interface is Xfig. +Full description of these systems is outside the scope of this document; +see their documentation. +</para> + + +<sect1 label="22.1" id="Graphics-package-options"> +<title>Graphics package options</title> + +<indexterm role="cp"><primary>graphics package options</primary></indexterm> +<indexterm role="cp"><primary>options, graphics package</primary></indexterm> + +<para>Synopsis (must be in the document preamble): +</para> +<screen>\usepackage[<replaceable>comma-separated option list</replaceable>]{graphics} +</screen> +<para>or +</para> +<screen>\usepackage[<replaceable>comma-separated option list</replaceable>]{graphicx} +</screen> +<para>The <literal>graphicx</literal> package has a format for optional arguments to the +<literal>\includegraphics</literal> command that is convenient (it is the key-value +format), so it is the better choice for new documents. When you load +the <filename>graphics</filename> or <filename>graphicx</filename> package with <literal>\usepackage</literal> +there are two kinds of available options. +</para> +<para>The first is that &latex; does not contain information about different +output systems but instead depends on information stored in a +<firstterm>printer driver</firstterm> file. Normally you should not specify the driver +option in the document, and instead rely on your system’s default. One +advantage of this is that it makes the document portable across systems. +</para> +<para>For completeness here is a list of the drivers. The currently relevant +ones are: <filename>dvipdfmx</filename>, <filename>dvips</filename>, <filename>dvisvgm</filename>, <filename>luatex</filename>, +<filename>pdftex</filename>, <filename>xetex</filename>. The two <filename>xdvi</filename> and <filename>oztex</filename> are +essentially aliases for <filename>dvips</filename> (and <filename>xdvi</filename> is monochrome). +Ones that should not be used for new systems are: <filename>dvipdf</filename>, +<filename>dvipdfm</filename>, <filename>dviwin</filename>, <filename>dvipsone</filename>, <filename>emtex</filename>, +<filename>pctexps</filename>, <filename>pctexwin</filename>, <filename>pctexhp</filename>, <filename>pctex32</filename>, +<filename>truetex</filename>, <filename>tcidvi</filename>, <filename>vtex</filename> (and <filename>dviwindo</filename> is an +alias for <filename>dvipsone</filename>). These are stored in files with a +<filename>.def</filename> extension, such as <filename>pdftex.def</filename>. +</para> +<para>The second kind of options are below. +</para> +<variablelist><varlistentry><term><literal>demo</literal> +</term><listitem><para>Instead of an image file, &latex; puts in a 150 pt by 100 pt +rectangle (unless another size is specified in the +<literal>\includegraphics</literal> command). +</para> +</listitem></varlistentry><varlistentry><term><literal>draft</literal> +</term><listitem><para>For each graphic file, it is not shown but instead the file name is +printed in a box of the correct size. In order to determine the size, +the file must be present. +</para> +</listitem></varlistentry><varlistentry><term><literal>final</literal> +</term><listitem><para>(Default) Override any previous <literal>draft</literal> option, so that the +document shows the contents of the graphic files. +</para> +</listitem></varlistentry><varlistentry><term><literal>hiderotate</literal> +</term><listitem><para>Do not show rotated text. (This allows for the possibility that a +previewer does not have the capability to rotate text.) +<!-- what does it show? --> +</para> +</listitem></varlistentry><varlistentry><term><literal>hidescale</literal> +</term><listitem><para>Do not show scaled text. (This allows for the possibility that a +previewer does not have the capability to scale.) +<!-- what does it show? --> +</para> +</listitem></varlistentry><varlistentry><term><literal>hiresbb</literal> +</term><listitem><para>In a PS or EPS file the graphic size may be specified in two ways. The +<literal>%%BoundingBox</literal> lines describe the graphic size using integer +multiples of a PostScript point, that is, integer multiples of 1/72 +inch. A later addition to the PostScript language allows decimal +multiples, such as 1.23, in <literal>%%HiResBoundingBox</literal> lines. This +option has &latex; to read the size from the latter. +</para> +</listitem></varlistentry></variablelist> + +</sect1> +<sect1 label="22.2" id="Graphics-package-configuration"> +<title>Graphics package configuration</title> + +<indexterm role="cp"><primary>graphics</primary></indexterm> +<indexterm role="cp"><primary>graphics package</primary></indexterm> +<indexterm role="cp"><primary>configuration, graphics package</primary></indexterm> +<indexterm role="cp"><primary>EPS files</primary></indexterm> +<indexterm role="cp"><primary>JPEG files</primary></indexterm> +<indexterm role="cp"><primary>JPG files</primary></indexterm> +<indexterm role="cp"><primary>PDF graphic files</primary></indexterm> +<indexterm role="cp"><primary>PNG files</primary></indexterm> + +<para>These commands configure the way &latex; searches the file system for +the graphic. +</para> +<para>The behavior of file system search code is necessarily platform +dependent. In this document we cover Linux, Macintosh, and Windows, as +those systems are typically configured. For other situations consult +the documentation in <filename>grfguide.pdf</filename>, or the &latex; source, or your +&tex; distribution’s documentation. +</para> + + +<sect2 label="22.2.1" id="_005cgraphicspath"> +<title><literal>\graphicspath</literal></title> + +<indexterm role="fn"><primary>\graphicspath</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\graphicspath{<replaceable>list of dir names inside curly brackets</replaceable>} +</screen> +<para>Declare a list of directories to search for graphics files. This allows +you to later say something like <literal>\includegraphics{lion.png}</literal> +instead of having to give its path. +</para> +<para>&latex; always looks for graphic files first in the current directory. +The declaration below tells the system to then look in the subdirectory +<filename>pix</filename>, and then <filename>../pix</filename>. +</para> +<screen>\usepackage{graphicx} % or graphics; put in preamble + ... +\graphicspath{ {pix/} {../pix/} } +</screen> +<para>The <literal>\graphicspath</literal> declaration is optional. If you don’t include +it then &latex;’s default is to search all of the places that it +usually looks for a file (it uses &latex;’s <literal>\input@path</literal>). In +particular, in this case one of the places it looks is the current +directory. +</para> +<para>Enclose each directory name in curly braces; for example, above it says +‘<literal><literal>{pix}</literal></literal>’. Do this even if there is only one directory. +Each directory name must end in a forward slash, <filename>/</filename>. This is true +even on Windows, where good practice is to use forward slashes for all +the directory separators since it makes the document portable to other +platforms. If you have spaces in your directory name then use double +quotes, as with <literal>{"my docs/"}</literal>. Getting one of these rules wrong +will cause &latex; to report <literal>Error: File `<replaceable>filename</replaceable>' not +found</literal>. +</para> +<para>Basically, the algorithm is that with this example, after looking in the +current directory, +</para> +<screen>\graphicspath{ {pix/} {../pix/} } +... +\usepackage{lion.png} +</screen> +<para>for each of the listed directories, &latex; concatenates it with the +file name and searches for the result, checking for <filename>pix/lion.png</filename> +and then <filename>../pix/lion.png</filename>. This algorithm means that the +<literal>\graphicspath</literal> command does not recursively search subdirectories: +if you issue <literal>\graphicspath{{a/}}</literal> and the graphic is in +<filename>a/b/lion.png</filename> then &latex; will not find it. It also means that +you can use absolute paths such as +<literal>\graphicspath{{/home/jim/logos/}}</literal> or +<literal>\graphicspath{{C:/Users/Albert/Pictures/}}</literal>. However, using +these means that the document is not portable. (You could preserve +portability by adjusting your &tex; system settings configuration file +parameter <literal>TEXINPUTS</literal>; see the documentation of your system.) +</para> +<para>You can use <literal>\graphicspath</literal> in the preamble or in the document +body. You can use it more than once. For debugging, show its value +with <literal>\makeatletter\typeout{\Ginput@path}\makeatother</literal>. +</para> +<para>The directories are taken with respect to the base file. That is, +suppose that you are working on a document based on <filename>book/book.tex</filename> +and it contains <literal>\include{chapters/chap1}</literal>. If in +<filename>chap1.tex</filename> you put <literal>\graphicspath{{plots/}}</literal> then +&latex; will not search for graphics in <filename>book/chapters/plots</filename>, but +instead in <filename>book/plots</filename>. +</para> + +</sect2> +<sect2 label="22.2.2" id="_005cDeclareGraphicsExtensions"> +<title><literal>\DeclareGraphicsExtensions</literal></title> + +<indexterm role="fn"><primary>\DeclareGraphicsExtensions</primary></indexterm> + +<para>Synopses: +</para> +<screen>\DeclareGraphicsExtensions{<replaceable>comma-separated list of file extensions</replaceable>} +</screen> +<para>Declare the filename extensions to try. This allows you to specify the +order in which to choose graphic formats when you include graphic files +by giving the filename without the extension, as in +<literal>\includegraphics{functionplot}</literal>. +</para> +<para>In this example, &latex; will find files in the PNG format before PDF +files. +</para> +<screen>\DeclareGraphicsExtensions{.png,PNG,.pdf,.PDF} + ... +\includegraphics{lion} % will find <filename>lion.png</filename> before <filename>lion.pdf</filename> +</screen> +<para>Because the file name <filename>lion</filename> does not have a period, &latex; uses +the extension list. For each directory in the graphics path +(see <link linkend="_005cgraphicspath">\graphicspath</link>), &latex; will try the extensions in the order +given. If it does not find such a file after trying all the directories +and extensions then it reports ‘<literal>! LaTeX Error: File `<filename>lion</filename>' +not found</literal>’. Note that you must include the periods at the start of the +extensions. +</para> +<para>Because Linux and Macintosh filenames are case sensitive, the list of +file extensions is case sensitive on those platforms. The Windows +platform is not case sensitive. +</para> +<para>You are not required to include <literal>\DeclareGraphicsExtensions</literal> in +your document; the printer driver has a sensible default. For example, +the most recent <filename>pdftex.def</filename> has the extension list +‘<literal><literal>.png,.pdf,.jpg,.mps,.jpeg,.jbig2,.jb2,.PNG,.PDF,.JPG,.JPEG,.JBIG2,.JB2</literal></literal>’. +</para> +<para>You can use this command in the preamble or in the document body. You +can use it more than once. For debugging, show its value with +<literal>\makeatletter\typeout{\Gin@extensions}\makeatother</literal>. +</para> + +</sect2> +<sect2 label="22.2.3" id="_005cDeclareGraphicsRule"> +<title><literal>\DeclareGraphicsRule</literal></title> + +<indexterm role="fn"><primary>\DeclareGraphicsRule</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\DeclareGraphicsRule{<replaceable>extension</replaceable>}{<replaceable>type</replaceable>}{<replaceable>size-file extension</replaceable>}{<replaceable>command</replaceable>} +</screen> +<para>Declare how to handle graphic files whose names end in <replaceable>extension</replaceable>. +</para> +<para>This example declares that all files with names have the form +<filename>filename-without-dot.mps</filename> will be treated as output from MetaPost, +meaning that the printer driver will use its MetaPost-handling code to +input the file. +</para> +<screen>\DeclareGraphicsRule{.mps}{mps}{.mps}{} +</screen> +<para>This +</para> +<screen>\DeclareGraphicsRule{*}{mps}{*}{} +</screen> +<para>tells &latex; that it should handle as MetaPost output any file with an +extension not covered by another rule, so it covers <filename>filename.1</filename>, +<filename>filename.2</filename>, etc. +</para> +<para>This describes the four arguments. +</para> +<variablelist><varlistentry><term><replaceable>extension</replaceable> +</term><listitem><para>The file extension to which this rule applies. The extension is anything +after and including the first dot in the filename. Use the Kleene star, +<literal>*</literal>, to denote the default behaviour for all undeclared extensions. +</para> +</listitem></varlistentry><varlistentry><term><replaceable>type</replaceable> +</term><listitem><para>The type of file involved. This type is a string that must be defined +in the printer driver. For instance, files with extensions <filename>.ps</filename>, +<filename>.eps</filename>, or <filename>.ps.gz</filename> may all be classed as type <literal>eps</literal>. +All files of the same type will be input with the same internal command +by the printer driver. For example, the file types that <filename>pdftex</filename> +recognizes are: <literal>jpg</literal>, <literal>jbig2</literal>, <literal>mps</literal>, <literal>pdf</literal>, +<literal>png</literal>, <literal>tif</literal>. +</para> +</listitem></varlistentry><varlistentry><term><replaceable>size-file extension</replaceable> +</term><listitem><para>The extension of the file to be read to determine the size of the +graphic, if there is such a file. It may be the same as <replaceable>extension</replaceable> +but it may be different. +</para> +<para>As an example, consider a PostScript graphic. To make it smaller, it +might be compressed into a <filename>.ps.gz</filename> file. Compressed files are not +easily read by &latex; so you can put the bounding box information in a +separate file. If <replaceable>size-file extension</replaceable> is empty then you must +specify size information in the arguments of <literal>\includegraphics</literal>. +</para> +<para>If the driver file has a procedure for reading size files for +<literal>type</literal> then that will be used, otherwise it will use the procedure +for reading <filename>.eps</filename> files. (Thus you may specify the size of bitmap +files in a file with a PostScript style <literal>%%BoundingBox</literal> line if no +other format is available.) +</para> +</listitem></varlistentry><varlistentry><term><replaceable>command</replaceable> +</term><listitem><para>A command that will be applied to the +file. This is very often left blank. This command must start with a +single backward quote. Thus, +<literal>\DeclareGraphicsRule{.eps.gz}{eps}{.eps.bb}{`gunzip -c +#1}</literal> specifies that any file with the extension <filename>.eps.gz</filename> should +be treated as an <literal>eps</literal> file, with the the BoundingBox information +stored in the file with extension <filename>.eps.bb</filename>, and that the command +<literal>gunzip -c</literal> will run on your platform to decompresses the file. +</para> +<para>Such a command is specific to your platform. In addition, your &tex; +system must allow you to run external commands; as a security measure +modern systems restrict running commands unless you explicitly allow it. +See the documentation for your &tex; distribution. +</para> +</listitem></varlistentry></variablelist> +</sect2> +</sect1> +<sect1 label="22.3" id="Commands-for-graphics"> +<title>Commands for graphics</title> + +<indexterm role="cp"><primary>graphics package commands</primary></indexterm> +<indexterm role="cp"><primary>commands, graphics package</primary></indexterm> + +<para>These are the commands available with the <filename>graphics</filename> and +<filename>graphicx</filename> packages. +</para> + + +<sect2 label="22.3.1" id="_005cincludegraphics"> +<title><literal>\includegraphics</literal></title> + +<indexterm role="cp"><primary>graphics</primary></indexterm> +<indexterm role="cp"><primary>graphics package</primary></indexterm> +<indexterm role="cp"><primary>including graphics</primary></indexterm> +<indexterm role="cp"><primary>importing graphics</primary></indexterm> +<indexterm role="cp"><primary>EPS files</primary></indexterm> +<indexterm role="cp"><primary>JPEG files</primary></indexterm> +<indexterm role="cp"><primary>JPG files</primary></indexterm> +<indexterm role="cp"><primary>PDF graphic files</primary></indexterm> +<indexterm role="cp"><primary>PNG files</primary></indexterm> +<indexterm role="fn"><primary>\includegraphics</primary></indexterm> + +<para>Synopses for <filename>graphics</filename> package: +</para> +<screen>\includegraphics{<replaceable>filename</replaceable>} +\includegraphics[<replaceable>urx</replaceable>,<replaceable>ury</replaceable>]{<replaceable>filename</replaceable>} +\includegraphics[<replaceable>llx</replaceable>,<replaceable>lly</replaceable>][<replaceable>urx</replaceable>,<replaceable>ury</replaceable>]{<replaceable>filename</replaceable>} +\includegraphics*{<replaceable>filename</replaceable>} +\includegraphics*[<replaceable>urx</replaceable>,<replaceable>ury</replaceable>]{<replaceable>filename</replaceable>} +\includegraphics*[<replaceable>llx</replaceable>,<replaceable>lly</replaceable>][<replaceable>urx</replaceable>,<replaceable>ury</replaceable>]{<replaceable>filename</replaceable>} +</screen> +<para>Synopses for <filename>graphicx</filename> package: +</para> +<screen>\includegraphics{<replaceable>filename</replaceable>} +\includegraphics[<replaceable>key-value list</replaceable>]{<replaceable>filename</replaceable>} +\includegraphics*{<replaceable>filename</replaceable>} +\includegraphics*[<replaceable>key-value list</replaceable>]{<replaceable>filename</replaceable>} +</screen> +<para>Include a graphics file. The starred form <literal>\includegraphics*</literal> will +clip the graphic to the size specified, while for the unstarred form any +part of the graphic that is outside the box of the specified size will +over-print the surrounding area. +</para> +<para>This +</para> +<screen>\usepackage{graphicx} % in preamble + ... +\begin{center} + \includegraphics{plot.pdf} +\end{center} +</screen> +<para>will incorporate into the document the graphic in <filename>plot.pdf</filename>, +centered and at its nominal size. You can also give a path to the file, +as with <literal>\includegraphics{graphics/plot.pdf}</literal>. To specify a list +of locations to search for the file, see <link linkend="_005cgraphicspath">\graphicspath</link>. +</para> +<para>If your filename includes spaces then put it in double quotes, as with +<literal>\includegraphics{"sister picture.jpg"}</literal>. +</para> +<para>The <literal>\includegraphics{<replaceable>filename</replaceable>}</literal> command decides on the +type of graphic by splitting <replaceable>filename</replaceable> on the first dot. You can +use <replaceable>filename</replaceable> with no dot, as in <literal>\includegraphics{turing}</literal> +and then &latex; tries a sequence of extensions such as <literal>.png</literal> and +<literal>.pdf</literal> until it finds a file with that extension +(see <link linkend="_005cDeclareGraphicsExtensions">\DeclareGraphicsExtensions</link>). +</para> +<para>If your file name contains dots before the extension then you can hide +them with curly braces, as in +<literal>\includegraphics{{plot.2018.03.12.a}.pdf}</literal>. Or, if you use +the <filename>graphicx</filename> package then you can use the options <literal>type</literal> and +<literal>ext</literal>; see below. This and other filename issues are also handled +with the package <filename>grffile</filename>. +</para> +<para>This example puts a graphic in a figure environment so &latex; can +move it to the next page if fitting it on the current page is awkward +(see <link linkend="figure">figure</link>). +</para> +<screen>\begin{figure} + \centering + \includegraphics[width=3cm]{lungxray.jpg} + \caption{The evidence is overwhelming: don't smoke.} \label{fig:xray} +\end{figure} +</screen> +<para>This places a graphic that will not float, so it is sure to appear at +this point in the document even if makes &latex; stretch the text or +resort to blank areas on the page. It will be centered and will have a +caption. +</para> +<screen>\usepackage{caption} % in preamble + ... +\begin{center} + \includegraphics{pix/nix.png} + \captionof{figure}{The spirit of the night} \label{pix:nix} % if you want a caption +\end{center} +</screen> +<para>This example puts a box with a graphic side by side with one having +text, with the two vertically centered. +</para> +<screen>\newcommand*{\vcenteredhbox}[1]{\begingroup + \setbox0=\hbox{#1}\parbox{\wd0}{\box0}\endgroup} + ... +\begin{center} + \vcenteredhbox{\includegraphics[width=0.4\textwidth]{plot}} + \hspace{1em} + \vcenteredhbox{\begin{minipage}{0.4\textwidth} + \begin{displaymath} + f(x)=x\cdot \sin (1/x) + \end{displaymath} + \end{minipage}} +\end{center} +</screen> +<para>If you use the <filename>graphics</filename> package then the only options involve the +size of the graphic (but see <link linkend="_005crotatebox">\rotatebox</link> and <link linkend="_005cscalebox">\scalebox</link>). +When one optional argument is present then it is +<literal>[<replaceable>urx</replaceable>,<replaceable>ury</replaceable>]</literal> and it gives the coordinates of the top +right corner of the image, as a pair of &tex; dimensions (see <link linkend="Units-of-length">Units +of length</link>). If the units are omitted they default to <literal>bp</literal>. In +this case, the lower left corner of the image is assumed to be at (0,0). +If two optional arguments are present then the leading one is +<literal>[<replaceable>llx</replaceable>,<replaceable>lly</replaceable>]</literal>, specifying the coordinates of the image’s +lower left. Thus, <literal>\includegraphics[1in,0.618in]{...}</literal> calls for +the graphic to be placed so it is 1 inch wide and 0.618 inches +tall and so its origin is at (0,0). +</para> +<para>The <filename>graphicx</filename> package gives you many more options. Specify them +in a key-value form, as here. +</para> +<screen>\begin{center} + \includegraphics[width=1in,angle=90]{lion} + \hspace{2em} + \includegraphics[angle=90,width=1in]{lion} +\end{center} +</screen> +<para>The options are read left-to-right. So the first graphic above is made +one inch wide and then rotated, while the second is rotated and then +made one inch wide. Thus, unless the graphic is perfectly square, the +two will end with different widths and heights. +</para> +<para>There are many options. The primary ones are listed first. +</para> +<para>Note that a graphic is placed by &latex; into a box, which is +traditionally referred to as its bounding box (distinct from the +PostScript BoundingBox described below). The graphic’s printed area may +go beyond this box, or sit inside this box, but when &latex; makes up a +page it puts together boxes and this is the box allocated for the +graphic. +</para> +<variablelist><varlistentry><term><literal>width</literal> +</term><listitem><para>The graphic will be shown so its bounding box is this width. An example +is <literal>\includegraphics[width=1in]{plot}</literal>. You can use the standard +&tex; dimensions (see <link linkend="Units-of-length">Units of length</link>) and also convenient is +<literal>\linewidth</literal>, or in a two-column document, <literal>\columnwidth</literal> +(see <link linkend="Page-layout-parameters">Page layout parameters</link>). An example is that by using the +<filename>calc</filename> package you can make the graphic be 1 cm narrow than +the width of the text with +<literal>\includegraphics[width=\linewidth-1.0cm]{hefferon.jpg}</literal>. +</para> +</listitem></varlistentry><varlistentry><term><literal>height</literal> +</term><listitem><para>The graphic will be shown so its bounding box is this height. You can +use the standard &tex; dimensions (see <link linkend="Units-of-length">Units of length</link>), and also +convenient are <literal>\pageheight</literal> and <literal>\textheight</literal> (see <link linkend="Page-layout-parameters">Page +layout parameters</link>). For instance, +<literal>\includegraphics[height=0.25\textheight]{godel}</literal> will make the +graphic be a quarter of the height of the text area. +</para> +</listitem></varlistentry><varlistentry><term><literal>totalheight</literal> +</term><listitem><para>The graphic will be shown so its bounding box has this height plus +depth. This differs from the height if the graphic was rotated. For +instance, if it has been rotated by -90 then it will have zero height +but a large depth. +</para> +</listitem></varlistentry><varlistentry><term><literal>keepaspectratio</literal> +</term><listitem><para>If set to <literal>true</literal>, or just specified as with +<literal>\includegraphics[...,keepaspectratio,...]{...}</literal> and you give as +options both <literal>width</literal> and <literal>height</literal> (or <literal>totalheight</literal>), +then &latex; will make the graphic is as large as possible without +distortion. That is, &latex; will ensure that neither is the graphic +wider than <literal>width</literal> nor taller than <literal>height</literal> (or +<literal>totalheight</literal>). +</para> +</listitem></varlistentry><varlistentry><term><literal>scale</literal> +</term><listitem><para>Factor by which to scale the graphic. Specifying +<literal>\includegraphics[scale=2.0]{...}</literal> makes the graphic twice its +nominal size. This number may be any value; a number between 1 +and 0 will shrink the graphic and a negative number will reflect +it. +</para> +</listitem></varlistentry><varlistentry><term><literal>angle</literal> +</term><listitem><para>Rotate the picture. The angle is taken in degrees and counterclockwise. +The graphic is rotated about its <literal>origin</literal>; see that option. For a +complete description of how rotated material is typeset, +see <link linkend="_005crotatebox">\rotatebox</link>. +</para> +</listitem></varlistentry><varlistentry><term><literal>origin</literal> +</term><listitem><para>The point of the graphic about which the rotation happens. Possible +values are any string containing one or two of: <literal>l</literal> for left, +<literal>r</literal> for right, <literal>b</literal> for bottom, <literal>c</literal> for center, <literal>t</literal> +for top, and <literal>B</literal> for baseline. Thus, +<literal>\includegraphics[angle=180,origin=c]{moon}</literal> will turn the +picture upside down from the center, while +<literal>\includegraphics[angle=180,origin=lB]{LeBateau}</literal> will turn its +picture upside down about its left baseline. (The character <literal>c</literal> +gives the horizontal center in <literal>bc</literal> or <literal>tc</literal>, but gives the +vertical center in <literal>lc</literal> or <literal>rc</literal>.) The default is <literal>lB</literal>. +</para> +<para>To rotate about an arbitrary point, see <link linkend="_005crotatebox">\rotatebox</link>. +</para> +</listitem></varlistentry></variablelist> +<para>These are lesser-used options. +</para> +<variablelist><varlistentry><term><literal>viewport</literal> +</term><listitem><para>Pick out a subregion of the graphic to show. Takes four arguments, +separated by spaces and given in &tex; dimensions, as with +<literal>\includegraphics[.., viewport=0in 0in 1in 0.618in]{...}</literal>. The +dimensions default to big points, <literal>bp</literal>. They are taken +relative to the origin specified by the bounding box. See also the +<literal>trim</literal> option. +</para> +</listitem></varlistentry><varlistentry><term><literal>trim</literal> +</term><listitem><para>Gives parts of the graphic to not show. Takes four arguments, separated +by spaces, that are given in &tex; dimensions, as with +<literal>\includegraphics[.., trim= 0in 0.1in 0.2in 0.3in, ...]{...}</literal>. +These give the amounts of the graphic not to show, that is, &latex; +will crop the picture by 0 inches on the left, 0.1 inches on +the bottom, 0.2 inches on the right, and 0.3 inches on the +top. See also the <literal>viewport</literal> option. +</para> +</listitem></varlistentry><varlistentry><term><literal>clip</literal> +</term><listitem><para>If set to <literal>true</literal>, or just specified as with +<literal>\includegraphics[...,clip,...]{...}</literal>, then the graphic is +cropped to the bounding box. You can get this effect by instead using +the starred form of the command, as +<literal>\includegraphics*[...]{...}</literal>. +</para> +</listitem></varlistentry><varlistentry><term><literal>page</literal> +</term><listitem><para>Give the page number of a multi-page PDF file. The default is +<literal>page=1</literal>. +</para> +</listitem></varlistentry><varlistentry><term><literal>pagebox</literal> +</term><listitem><para>Specifies which bounding box to use for PDF files from among +<literal>mediabox</literal>, <literal>cropbox</literal>, <literal>bleedbox</literal>, <literal>trimbox</literal>, or +<literal>artbox</literal>. PDF files do not have the BoundingBox that PostScript +files have, but may specify up to four predefined rectangles. The +MediaBox gives the boundaries of the physical medium. The CropBox is the +region to which the contents of the page are to be clipped when +displayed. The BleedBox is the region to which the contents of the page +should be clipped in production. The TrimBox is the intended dimensions +of the finished page. The ArtBox is the extent of the page’s meaningful +content. The driver will set the image size based on CropBox if +present, otherwise it will not use one of the others, with a +driver-defined order of preference. MediaBox is always present. +</para> +</listitem></varlistentry><varlistentry><term><literal>interpolate</literal> +</term><listitem><para>Enable or disable interpolation of raster images by the viewer. Can be +set with <literal>interpolate=true</literal> or just specified as with +<literal>\includegraphics[...,interpolate,...]{...}</literal>. +</para> +</listitem></varlistentry><varlistentry><term><literal>quiet</literal> +</term><listitem><para>Do not write information to the log. You can set it with +<literal>quiet=true</literal> or just specified it with +<literal>\includegraphics[...,quite,...]{...}</literal>, +</para> +</listitem></varlistentry><varlistentry><term><literal>draft</literal> +</term><listitem><para>If you set it with <literal>draft=true</literal> or just specified it with +<literal>\includegraphics[...,draft,...]{...}</literal>, then the graphic will not +appear in the document, possibly saving color printer ink. Instead, +&latex; will put an empty box of the correct size with the filename +printed in it. +</para> +</listitem></varlistentry></variablelist> +<para>These options address the bounding box for Encapsulated PostScript +graphic files, which have a size specified with a line +<literal>%%BoundingBox</literal> that appears in the file. It has four values, +giving the lower <inlineequation><mathphrase>x</mathphrase></inlineequation> coordinate, lower <inlineequation><mathphrase>y</mathphrase></inlineequation> coordinate, upper +<inlineequation><mathphrase>x</mathphrase></inlineequation> coordinate, and upper <inlineequation><mathphrase>y</mathphrase></inlineequation> coordinate. The units are +PostScript points, equivalent to &tex;’s big points, 1/72 inch. +For example, if an <filename>.eps</filename> file has the line <literal>%%BoundingBox 10 +20 40 80</literal> then its natural size is 30/72 inch wide by +60/72 inch tall. +</para> +<variablelist><varlistentry><term><literal>bb</literal> +</term><listitem><para>Specify the bounding box of the displayed region. The argument is four +dimensions separated by spaces, as with <literal>\includegraphics[.., bb= +0in 0in 1in 0.618in]{...}</literal>. Usually <literal>\includegraphics</literal> reads the +BoundingBox numbers from the EPS file automatically, so this option is +only useful if the bounding box is missing from that file or if you want +to change it. +</para> +</listitem></varlistentry><varlistentry><term><literal>bbllx, bblly, bburx, bbury</literal> +</term><listitem><para>Set the bounding box. These four are obsolete, but are retained for +compatibility with old packages. +</para> +</listitem></varlistentry><varlistentry><term><literal>natwidth, natheight</literal> +</term><listitem><para>An alternative for <literal>bb</literal>. Setting +<literal>\includegraphics[...,natwidth=1in,natheight=0.618in,...]{...}</literal> +is the same as setting <literal>bb=0 0 1in 0.618in</literal>. +</para> +</listitem></varlistentry><varlistentry><term><literal>hiresbb</literal> +</term><listitem><para>If set to <literal>true</literal>, or just specified as with +<literal>\includegraphics[...,hiresbb,...]{...}</literal>, then &latex; will look +for <literal>%%HiResBoundingBox</literal> lines instead of <literal>%%BoundingBox</literal> +lines. (The <literal>BoundingBox</literal> lines use only natural numbers while the +<literal>HiResBoundingBox</literal> lines use decimals; both use units equivalent to +&tex;’s big points, 1/72 inch.) To override a prior setting of +<literal>true</literal>, you can set it to <literal>false</literal>. +</para> +</listitem></varlistentry></variablelist> +<para>These following options allow a user to override &latex;’s method of +choosing the graphic type based on the filename extension. An example +is that <literal>\includegraphics[type=png,ext=.xxx,read=.xxx]{lion}</literal> +will read the file <filename>lion.xxx</filename> as though it were +<filename>lion.png</filename>. For more on these, see <link linkend="_005cDeclareGraphicsRule">\DeclareGraphicsRule</link>. +</para> +<variablelist><varlistentry><term><literal>type</literal> +</term><listitem><para>Specify the graphics type. +</para> +</listitem></varlistentry><varlistentry><term><literal>ext</literal> +</term><listitem><para>Specify the graphics extension. +Only use this in conjunction with the option <literal>type</literal>. +</para> +</listitem></varlistentry><varlistentry><term><literal>read</literal> +</term><listitem><para>Specify the file extension of the read file. +Only use this in conjunction with the option <literal>type</literal>. +</para> +</listitem></varlistentry><varlistentry><term><literal>command</literal> +</term><listitem><para>Specify a command to be applied to this file. +Only use this in conjunction with the option <literal>type</literal>. +<!-- write18 and restricted execution. --> +</para> +</listitem></varlistentry></variablelist> + +</sect2> +<sect2 label="22.3.2" id="_005crotatebox"> +<title><literal>\rotatebox</literal></title> + +<indexterm role="cp"><primary>rotation</primary></indexterm> +<indexterm role="cp"><primary>rotating graphics</primary></indexterm> +<indexterm role="cp"><primary>rotating text</primary></indexterm> +<indexterm role="fn"><primary>\rotatebox</primary></indexterm> + +<para>Synopsis for <filename>graphics</filename> package: +</para> +<screen>\rotatebox{<replaceable>angle</replaceable>}{<replaceable>material</replaceable>} +</screen> +<para>Synopses for <filename>graphicx</filename> package: +</para> +<screen>\rotatebox{<replaceable>angle</replaceable>}{<replaceable>material</replaceable>} +\rotatebox[<replaceable>key-value list</replaceable>]{<replaceable>angle</replaceable>}{<replaceable>material</replaceable>} +</screen> +<para>Put <replaceable>material</replaceable> in a box and rotate it <replaceable>angle</replaceable> degrees counterclockwise. +</para> +<para>This example rotates the table column heads forty five degrees. +</para> +<screen>\begin{tabular}{ll} + \rotatebox{45}{Character} &\rotatebox{45}{NATO phonetic} \\ + A &AL-FAH \\ + B &BRAH-VOH +\end{tabular} +</screen> +<para>The <replaceable>material</replaceable> can be anything that goes in a box, including a graphic. +</para> +<screen> \rotatebox[origin=c]{45}{\includegraphics[width=1in]{lion}} +</screen> +<para>To place the rotated material, the first step is that &latex; sets +<replaceable>material</replaceable> in a box, with a reference point on the left baseline. +The second step is the rotation, by default about the reference point. +The third step is that &latex; computes a box to bound the rotated +material. Fourth, &latex; moves this box horizontally so that the left +edge of this new bounding box coincides with the left edge of the box +from the first step (they need not coincide vertically). This new +bounding box, in its new position, is what &latex; uses as the box when +typesetting this material. +</para> +<para>If you use the <filename>graphics</filename> package then the rotation is about the +reference point of the box. If you use the <filename>graphicx</filename> package then +then these are the options that can go in the <replaceable>key-value list</replaceable>, but +note that you can get the same effect without needing this package, +except for the <literal>x</literal> and <literal>y</literal> options (see <link linkend="_005cincludegraphics">\includegraphics</link>). +</para> +<variablelist><varlistentry><term><literal>origin</literal> +</term><listitem><para>The point of the <replaceable>material</replaceable>’s box about which the rotation happens. +Possible values are any string containing one or two of: <literal>l</literal> for +left, <literal>r</literal> for right, <literal>b</literal> for bottom, <literal>c</literal> for center, +<literal>t</literal> for top, and <literal>B</literal> for baseline. Thus, +<literal>\includegraphics[angle=180,origin=c]{moon}</literal> will turn the +picture upside down from the center, while +<literal>\includegraphics[angle=180,origin=lB]{LeBateau}</literal> will turn its +picture upside down about its left baseline. (The character <literal>c</literal> +gives the horizontal center in <literal>bc</literal> or <literal>tc</literal> but gives the +vertical center in <literal>lc</literal> or <literal>rc</literal>.) The default is <literal>lB</literal>. +</para> +</listitem></varlistentry><varlistentry><term><literal>x, y</literal> +</term><listitem><para>Specify an arbitrary point of rotation with +<literal>\rotatebox[x=<replaceable>&tex; dimension</replaceable>,y=<replaceable>&tex; +dimension</replaceable>]{...}</literal> (see <link linkend="Units-of-length">Units of length</link>). These give the offset +from the box’s reference point. +</para> +</listitem></varlistentry><varlistentry><term><literal>units</literal> +</term><listitem><para>This key allows you to change the default of degrees counterclockwise. +Setting <literal>units=-360</literal> changes the direction to degrees clockwise and +setting <literal>units=6.283185</literal> changes to radians counterclockwise. +</para> +</listitem></varlistentry></variablelist> + +</sect2> +<sect2 label="22.3.3" id="_005cscalebox"> +<title><literal>\scalebox</literal></title> + +<indexterm role="cp"><primary>graphics, scaling</primary></indexterm> +<indexterm role="cp"><primary>graphics, resizing</primary></indexterm> +<indexterm role="cp"><primary>scaling</primary></indexterm> +<indexterm role="cp"><primary>resizing</primary></indexterm> +<indexterm role="cp"><primary>text, scaling</primary></indexterm> +<indexterm role="cp"><primary>text, resizing</primary></indexterm> +<indexterm role="fn"><primary>\scalebox</primary></indexterm> +<indexterm role="fn"><primary>\reflectbox</primary></indexterm> + +<para>Synopses: +</para> +<screen>\scalebox{<replaceable>horizontal factor</replaceable>}{<replaceable>material</replaceable>} +\scalebox{<replaceable>horizontal factor</replaceable>}[<replaceable>vertical factor</replaceable>]{<replaceable>material</replaceable>} +\reflectbox{<replaceable>material</replaceable>} +</screen> +<para>Scale the <replaceable>material</replaceable>. +</para> +<para>This example halves the size, both horizontally and vertically, of the +first text and doubles the size of the second. +</para> +<screen>\scalebox{0.5}{DRINK ME} and \scalebox{2.0}{Eat Me} +</screen> +<para>If you do not specify the optional <replaceable>vertical factor</replaceable> then it +defaults to the same value as the <replaceable>horizontal factor</replaceable>. +</para> +<para>You can use this command to resize a graphic, as with +<literal>\scalebox{0.5}{\includegraphics{lion}}</literal>. If you use the +<filename>graphicx</filename> package then you can accomplish the same thing with +optional arguments to <literal>\includegraphics</literal> +(see <link linkend="_005cincludegraphics">\includegraphics</link>). +</para> +<para>The <literal>\reflectbox</literal> command abbreviates +<literal>\scalebox{-1}[1]{<replaceable>material</replaceable>}</literal>. Thus, <literal>Able was +I\reflectbox{Able was I}</literal> will show the phrase ‘<literal>Able was I</literal>’ +immediately followed by its mirror reflection. +</para> + +</sect2> +<sect2 label="22.3.4" id="_005cresizebox"> +<title><literal>\resizebox</literal></title> + +<indexterm role="cp"><primary>graphics, scaling</primary></indexterm> +<indexterm role="cp"><primary>graphics, resizing</primary></indexterm> +<indexterm role="cp"><primary>scaling</primary></indexterm> +<indexterm role="cp"><primary>resizing</primary></indexterm> +<indexterm role="cp"><primary>text, scaling</primary></indexterm> +<indexterm role="cp"><primary>text, resizing</primary></indexterm> +<indexterm role="fn"><primary>\resizebox</primary></indexterm> + +<para>Synopses: +</para> +<screen>\resizebox{<replaceable>horizontal length</replaceable>}{<replaceable>vertical length</replaceable>}{<replaceable>material</replaceable>} +\resizebox*{<replaceable>horizontal length</replaceable>}{<replaceable>vertical length</replaceable>}{<replaceable>material</replaceable>} +</screen> +<para>Given a size, such as <literal>3cm</literal>, transform <replaceable>material</replaceable> to make it +that size. If either <replaceable>horizontal length</replaceable> or <replaceable>vertical length</replaceable> +is an exclamation point <literal>!</literal> then the other argument is used +to determine a scale factor for both directions. +</para> +<para>This example makes the graphic be a half inch wide and scales it +vertically by the same factor to keep it from being distorted. +</para> +<screen>\resizebox{0.5in}{!}{\includegraphics{lion}} +</screen> +<para>The unstarred form <literal>\resizebox</literal> takes <replaceable>vertical length</replaceable> to be +the box’s height while the starred form <literal>\resizebox*</literal> takes it to +be height+depth. For instance, make the text have a height+depth of a +quarter inch with <literal>\resizebox*{!}{0.25in}{\parbox{1in}{This +box has both height and depth.}}</literal>. +</para> +<para>You can use <literal>\depth</literal>, <literal>\height</literal>, <literal>\totalheight</literal>, and +<literal>\width</literal> to refer to the original size of the box. Thus, make the +text two inches wide but keep the original height with +<literal>\resizebox{2in}{\height}{Two inches}</literal>. +</para> + +</sect2> +</sect1> +</chapter> +<chapter label="23" id="Special-insertions"> <title>Special insertions</title> <indexterm role="cp"><primary>special insertions</primary></indexterm> @@ -8455,7 +10594,7 @@ special meaning do not correspond to simple characters you can type. </para> -<sect1 label="21.1" id="Reserved-characters"> +<sect1 label="23.1" id="Reserved-characters"> <title>Reserved characters</title> <indexterm role="cp"><primary>reserved characters</primary></indexterm> @@ -8502,7 +10641,66 @@ split the lines. </para> </sect1> -<sect1 label="21.2" id="Symbols-by-font-position"> +<sect1 label="23.2" id="Upper-and-lower-case"> +<title>Upper and lower case</title> + +<indexterm role="cp"><primary>Upper case</primary></indexterm> +<indexterm role="cp"><primary>Lower case</primary></indexterm> +<indexterm role="cp"><primary>characters, case</primary></indexterm> + +<para>Synopsis: +</para> +<screen>\uppercase{<replaceable>text</replaceable>} +\lowercase{<replaceable>text</replaceable>} +\MakeUppercase{<replaceable>text</replaceable>} +\MakeLowercase{<replaceable>text</replaceable>} +</screen> +<para>Change the case of characters. The &tex; primitives commands +<literal>\uppercase</literal> and <literal>\lowercase</literal> only work for American +characters. The &latex; commands <literal>\MakeUppercase</literal> and +<literal>\MakeLowercase</literal> commands also change characters accessed by +commands such as <literal>\ae</literal> or <literal>\aa</literal>. The commands +<literal>\MakeUppercase</literal> and <literal>\MakeLowercase</literal> are robust but they have +moving arguments (see <link linkend="_005cprotect">\protect</link>). +</para> +<para>These commands do not change the case of letters used in the name of a +command within <replaceable>text</replaceable>. But they do change the case of every other +Latin letter inside the argument <replaceable>text</replaceable>. Thus, +<literal>\MakeUppercase{Let $y=f(x)$</literal>} produces ‘<literal>LET Y=F(X)</literal>’. Another +example is that the name of an environment will be changed, so that +<literal>\MakeUppercase{\begin{tabular} ... \end{tabular}}</literal> will +produce an error because the first half is changed to +<literal>\begin{TABULAR}</literal>. +</para> +<para>&latex; uses the same fixed table for changing case throughout a +document, 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. +</para> +<para>To change the case of text that results from a macro inside <replaceable>text</replaceable> +you need to do expansion. Here the <literal>\Schoolname</literal> produces +‘<literal>COLLEGE OF MATHEMATICS</literal>’. +</para> +<screen>\newcommand{\schoolname}{College of Mathematics} +\newcommand{\Schoolname}{\expandafter\MakeUppercase + <!-- /@w -->\expandafter{\schoolname}} +</screen> +<indexterm role="cp"><primary>package, <literal>textcase</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>textcase</literal> package</primary></indexterm> + +<para>The <filename>textcase</filename> package brings some of the missing feature of the +standard &latex; commands <literal>\MakeUppercase</literal> and +<literal>\MakeLowerCase</literal>. +</para> +<indexterm role="cp"><primary>package, <literal>mfirstuc</literal></primary></indexterm> +<indexterm role="cp"><primary><literal>mfirstuc</literal> package</primary></indexterm> + +<para>To uppercase only the first letter of words, you can use the package +<filename>mfirstuc</filename>. +</para> + +</sect1> +<sect1 label="23.3" id="Symbols-by-font-position"> <title>Symbols by font position</title> <indexterm role="fn"><primary>\symbol</primary></indexterm> @@ -8521,7 +10719,7 @@ example could also be written as <literal>\symbol{'40}</literal> or </para> </sect1> -<sect1 label="21.3" id="Text-symbols"> +<sect1 label="23.4" id="Text-symbols"> <title>Text symbols</title> <indexterm role="cp"><primary>text symbols</primary></indexterm> @@ -8809,7 +11007,7 @@ has the ascender height. </listitem></varlistentry></variablelist> </sect1> -<sect1 label="21.4" id="Accents"> +<sect1 label="23.5" id="Accents"> <title>Accents</title> <indexterm role="cp"><primary>accents</primary></indexterm> @@ -8818,6 +11016,7 @@ has the ascender height. <indexterm role="cp"><primary>package, <literal>babel</literal></primary></indexterm> <indexterm role="cp"><primary><literal>babel</literal> package</primary></indexterm> + <indexterm role="cp"><primary>multilingual support</primary></indexterm> <para>&latex; has wide support for many of the world’s scripts and languages, through the <literal>babel</literal> package and related support. This @@ -8837,7 +11036,7 @@ capital letters. These are not available with OT1. </para> </listitem></varlistentry><varlistentry><term><literal>\'</literal> </term><term><literal>\capitalacute</literal> -</term><listitem><indexterm role="fn"><primary>\’ (acute accent)</primary></indexterm> +</term><listitem><indexterm role="fn"><primary>\' (acute accent)</primary></indexterm> <indexterm role="fn"><primary>\capitalacute</primary></indexterm> <indexterm role="cp"><primary>acute accent</primary></indexterm> <para>Produces an acute accent, as in ó. In the <literal>tabbing</literal> @@ -8869,7 +11068,7 @@ environment, pushes current column to the right of the previous column </para> </listitem></varlistentry><varlistentry><term><literal>\`</literal> </term><term><literal>\capitalgrave</literal> -</term><listitem><indexterm role="fn"><primary>\‘ (grave accent)</primary></indexterm> +</term><listitem><indexterm role="fn"><primary>\` (grave accent)</primary></indexterm> <indexterm role="fn"><primary>\capitalgrave</primary></indexterm> <indexterm role="cp"><primary>grave accent</primary></indexterm> <para>Produces a grave accent over the following, as in ò. In the @@ -8975,7 +11174,7 @@ See also <literal>\b</literal> above. </listitem></varlistentry></variablelist> </sect1> -<sect1 label="21.5" id="Additional-Latin-letters"> +<sect1 label="23.6" id="Additional-Latin-letters"> <title>Additional Latin letters</title> <anchor id="Non_002dEnglish-characters"/><indexterm role="cp"><primary>Latin letters, additional</primary></indexterm> @@ -9076,7 +11275,7 @@ font encoding, such as T1. </listitem></varlistentry></variablelist> </sect1> -<sect1 label="21.6" id="_005crule"> +<sect1 label="23.7" id="_005crule"> <title><literal>\rule</literal></title> <indexterm role="fn"><primary>\rule</primary></indexterm> @@ -9099,7 +11298,7 @@ rectangles. The arguments are: </para></listitem></varlistentry></variablelist> </sect1> -<sect1 label="21.7" id="_005ctoday"> +<sect1 label="23.8" id="_005ctoday"> <title><literal>\today</literal></title> <indexterm role="fn"><primary>\today</primary></indexterm> @@ -9124,13 +11323,14 @@ will output ‘<literal>4 juillet 1976</literal>’: </screen> <indexterm role="cp"><primary>package, <literal>datetime</literal></primary></indexterm> <indexterm role="cp"><primary><literal>datetime</literal> package</primary></indexterm> + <para>The <literal>datetime</literal> package, among others, can produce a wide variety of other date formats. </para> </sect1> </chapter> -<chapter label="22" id="Splitting-the-input"> +<chapter label="24" id="Splitting-the-input"> <title>Splitting the input</title> <indexterm role="cp"><primary>splitting the input file</primary></indexterm> @@ -9150,7 +11350,7 @@ external file to be created with the main document. </para> -<sect1 label="22.1" id="_005cinclude"> +<sect1 label="24.1" id="_005cinclude"> <title><literal>\include</literal></title> <indexterm role="fn"><primary>\include</primary></indexterm> @@ -9174,8 +11374,8 @@ read by another <literal>\include</literal> command. </para> </sect1> -<sect1 label="22.2" id="_005cincludeonly"> -<title>\<literal>includeonly</literal></title> +<sect1 label="24.2" id="_005cincludeonly"> +<title><literal>\includeonly</literal></title> <indexterm role="fn"><primary>\includeonly</primary></indexterm> @@ -9193,7 +11393,7 @@ selection to be effective. </para> </sect1> -<sect1 label="22.3" id="_005cinput"> +<sect1 label="24.3" id="_005cinput"> <title><literal>\input</literal></title> <indexterm role="fn"><primary>\input</primary></indexterm> @@ -9214,12 +11414,12 @@ is tried (‘<literal>foo</literal>’ or ‘<literal>foo.bar</liter </sect1> </chapter> -<chapter label="23" id="Front_002fback-matter"> +<chapter label="25" id="Front_002fback-matter"> <title>Front/back matter</title> -<sect1 label="23.1" id="Tables-of-contents"> +<sect1 label="25.1" id="Tables-of-contents"> <title>Tables of contents</title> <indexterm role="cp"><primary>table of contents, creating</primary></indexterm> @@ -9251,7 +11451,7 @@ as for the table of contents. </para> -<sect2 label="23.1.1" id="_005caddcontentsline"> +<sect2 label="25.1.1" id="_005caddcontentsline"> <title><literal>\addcontentsline</literal></title> <indexterm role="fn"><primary>\addcontentsline</primary></indexterm> @@ -9265,7 +11465,7 @@ as for the table of contents. or table where: </para> <variablelist><varlistentry><term><replaceable>ext</replaceable> -</term><listitem><para>The extension of the file on which information is to be written, +</term><listitem><para>The filename extension of the file on which information is to be written, typically one of: <literal>toc</literal> (table of contents), <literal>lof</literal> (list of figures), or <literal>lot</literal> (list of tables). </para> @@ -9293,7 +11493,7 @@ following, matching the value of the <replaceable>ext</replaceable> argument: </sect2> -<sect2 label="23.1.2" id="_005caddtocontents"> +<sect2 label="25.1.2" id="_005caddtocontents"> <title><literal>\addtocontents</literal></title> <indexterm role="fn"><primary>\addtocontents{<replaceable>ext</replaceable>}{<replaceable>text</replaceable>}</primary></indexterm> @@ -9313,7 +11513,7 @@ figures), or <filename>lot</filename> (list of tables). </sect2> </sect1> -<sect1 label="23.2" id="Glossaries"> +<sect1 label="25.2" id="Glossaries"> <title>Glossaries</title> <indexterm role="cp"><primary>glossaries</primary></indexterm> @@ -9337,7 +11537,7 @@ glossaries. </para> </sect1> -<sect1 label="23.3" id="Indexes"> +<sect1 label="25.3" id="Indexes"> <title>Indexes</title> <indexterm role="cp"><primary>indexes</primary></indexterm> @@ -9381,6 +11581,7 @@ the index. <indexterm role="fn"><primary>\printindex</primary></indexterm> <indexterm role="cp"><primary>package, <literal>makeidx</literal></primary></indexterm> <indexterm role="cp"><primary><literal>makeidx</literal> package</primary></indexterm> + <para>The index is usually generated with the <literal>\printindex</literal> command. This is defined in the <literal>makeidx</literal> package, so <literal>\usepackage{makeidx}</literal> needs to be in the preamble. @@ -9392,12 +11593,14 @@ minus3pt</literal>’. </para> <indexterm role="cp"><primary>package, <literal>showidx</literal></primary></indexterm> <indexterm role="cp"><primary><literal>showidx</literal> package</primary></indexterm> + <para>The <literal>showidx</literal> package causes each index entries to be shown in the margin on the page where the entry appears. This can help in preparing the index. </para> <indexterm role="cp"><primary>package, <literal>multind</literal></primary></indexterm> <indexterm role="cp"><primary><literal>multind</literal> package</primary></indexterm> + <para>The <literal>multind</literal> package supports multiple indexes. See also the &tex; FAQ entry on this topic, <ulink url="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=multind">http://www.tex.ac.uk/cgi-bin/texfaq2html?label=multind</ulink>. @@ -9405,7 +11608,7 @@ preparing the index. </sect1> </chapter> -<chapter label="24" id="Letters"> +<chapter label="26" id="Letters"> <title>Letters</title> <indexterm role="cp"><primary>letters, writing</primary></indexterm> @@ -9492,7 +11695,7 @@ I am not interested in entering a business arrangement with you. </para> -<sect1 label="24.1" id="_005caddress"> +<sect1 label="26.1" id="_005caddress"> <title><literal>\address</literal></title> <indexterm role="fn"><primary>\address</primary></indexterm> @@ -9522,7 +11725,7 @@ formatted as a personal letter. </screen> </sect1> -<sect1 label="24.2" id="_005ccc"> +<sect1 label="26.2" id="_005ccc"> <title><literal>\cc</literal></title> <indexterm role="fn"><primary>\cc</primary></indexterm> @@ -9543,7 +11746,7 @@ backslash <literal>\\</literal>, as in: </screen> </sect1> -<sect1 label="24.3" id="_005cclosing"> +<sect1 label="26.3" id="_005cclosing"> <title><literal>\closing</literal></title> <indexterm role="fn"><primary>\closing</primary></indexterm> @@ -9561,7 +11764,7 @@ is a <literal>\closing</literal> (although this command is optional). For examp </screen> </sect1> -<sect1 label="24.4" id="_005cencl"> +<sect1 label="26.4" id="_005cencl"> <title><literal>\encl</literal></title> <indexterm role="fn"><primary>\encl</primary></indexterm> @@ -9581,7 +11784,7 @@ Separate multiple lines with a double backslash <literal>\\</literal>. </screen> </sect1> -<sect1 label="24.5" id="_005clocation"> +<sect1 label="26.5" id="_005clocation"> <title><literal>\location</literal></title> <indexterm role="fn"><primary>\location</primary></indexterm> @@ -9595,7 +11798,7 @@ appears if the page style is <literal>firstpage</literal>. </para> </sect1> -<sect1 label="24.6" id="_005cmakelabels"> +<sect1 label="26.6" id="_005cmakelabels"> <title><literal>\makelabels</literal></title> <indexterm role="fn"><primary>\makelabels</primary></indexterm> @@ -9623,7 +11826,7 @@ in the argument to the <literal>letter</literal> environment. By default <!-- xxx TODO, align on latex2e-fr.texi, see https://mail.gna.org/public/latexrefman-discuss/2015-10/msg00000.html --> </sect1> -<sect1 label="24.7" id="_005cname"> +<sect1 label="26.7" id="_005cname"> <title><literal>\name</literal></title> <indexterm role="fn"><primary>\name</primary></indexterm> @@ -9637,7 +11840,7 @@ return address. </para> </sect1> -<sect1 label="24.8" id="_005copening"> +<sect1 label="26.8" id="_005copening"> <title><literal>\opening</literal></title> <indexterm role="fn"><primary>\opening</primary></indexterm> @@ -9655,7 +11858,7 @@ text that starts your letter. For instance: </screen> </sect1> -<sect1 label="24.9" id="_005cps"> +<sect1 label="26.9" id="_005cps"> <title><literal>\ps</literal></title> <indexterm role="fn"><primary>\ps</primary></indexterm> <indexterm role="cp"><primary>postscript, in letters</primary></indexterm> @@ -9671,7 +11874,7 @@ text that starts your letter. For instance: </screen> </sect1> -<sect1 label="24.10" id="_005csignature"> +<sect1 label="26.10" id="_005csignature"> <title><literal>\signature</literal></title> <para>Synopsis: @@ -9725,7 +11928,7 @@ preamble). <!-- --> <!-- --> </sect1> -<sect1 label="24.11" id="_005ctelephone"> +<sect1 label="26.11" id="_005ctelephone"> <title><literal>\telephone</literal></title> <indexterm role="fn"><primary>\telephone</primary></indexterm> @@ -9742,7 +11945,7 @@ page. </sect1> </chapter> -<chapter label="25" id="Terminal-input_002foutput"> +<chapter label="27" id="Terminal-input_002foutput"> <title>Terminal input/output</title> <indexterm role="cp"><primary>input/output, to terminal</primary></indexterm> @@ -9750,7 +11953,7 @@ page. -<sect1 label="25.1" id="_005ctypein"> +<sect1 label="27.1" id="_005ctypein"> <title><literal>\typein[<replaceable>cmd</replaceable>]{<replaceable>msg</replaceable>}</literal></title> <indexterm role="fn"><primary>\typein</primary></indexterm> @@ -9769,7 +11972,7 @@ redefined to be the typed input. </para> </sect1> -<sect1 label="25.2" id="_005ctypeout"> +<sect1 label="27.2" id="_005ctypeout"> <title><literal>\typeout{<replaceable>msg</replaceable>}</literal></title> <indexterm role="fn"><primary>\typeout</primary></indexterm> @@ -9792,7 +11995,7 @@ printed, independent of surrounding spaces. A <literal>^^J</literal> in </sect1> </chapter> -<chapter label="26" id="Command-line"> +<chapter label="28" id="Command-line"> <title>Command line</title> <indexterm role="cp"><primary>command line</primary></indexterm> @@ -9807,7 +12010,7 @@ error: </para> <screen>latex '\nonstopmode\input foo.tex' </screen> -<indexterm role="fn"><primary>–help command-line option</primary></indexterm> +<indexterm role="fn"><primary>--help command-line option</primary></indexterm> <para>With many, but not all, implementations, command-line options can also be specified in the usual Unix way, starting with ‘<literal>-</literal>’ or ‘<literal>--</literal>’. For a list of those options, try ‘<literal>latex --help</literal>’. |