File indexing completed on 2024-11-24 04:34:43
0001 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 0002 <html> 0003 <!-- This document is an unofficial reference manual for LaTeX, a 0004 document preparation system, version of November 2018. 0005 0006 This manual was originally translated from LATEX.HLP v1.0a in the 0007 VMS Help Library. The pre-translation version was written by 0008 George D. Greenwade of Sam Houston State University. The 0009 LaTeX 2.09 version was written by Stephen Gilmore. The 0010 LaTeX2e version was adapted from this by Torsten Martinsen. Karl 0011 Berry made further updates and additions, and gratefully acknowledges 0012 using Hypertext Help with LaTeX, by Sheldon Green, and 0013 LaTeX Command Summary (for LaTeX 2.09) by 0014 L. Botway and C. Biemesderfer (published by the TeX Users 0015 Group as TeXniques number 10), as reference material. We also 0016 gratefully acknowledge additional material appearing in 0017 latex2e-reference by Martin Herbert Dietze. (From these references no 0018 text was directly copied.) 0019 0020 Copyright 2007, 2008, 2009, 2010, 2011, 2012, 2013, 0021 2014, 2015, 2016, 2017, 2018 Karl Berry. 0022 0023 Copyright 1988, 1994, 2007 Stephen Gilmore. 0024 0025 Copyright 1994, 1995, 1996 Torsten Martinsen. 0026 0027 Permission is granted to make and distribute verbatim copies of 0028 this manual provided the copyright notice and this permission notice 0029 are preserved on all copies. 0030 0031 0032 Permission is granted to copy and distribute modified versions of this 0033 manual under the conditions for verbatim copying, provided that the entire 0034 resulting derived work is distributed under the terms of a permission 0035 notice identical to this one. 0036 0037 Permission is granted to copy and distribute translations of this manual 0038 into another language, under the above conditions for modified versions. --> 0039 <!-- Created by GNU Texinfo 6.5, http://www.gnu.org/software/texinfo/ --> 0040 <head> 0041 <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 0042 <title>Class and package commands (LaTeX2e unofficial reference manual (November 2018))</title> 0043 0044 <meta name="description" content="Class and package commands (LaTeX2e unofficial reference manual (November 2018))"> 0045 <meta name="keywords" content="Class and package commands (LaTeX2e unofficial reference manual (November 2018))"> 0046 <meta name="resource-type" content="document"> 0047 <meta name="distribution" content="global"> 0048 <meta name="Generator" content="makeinfo"> 0049 <link href="index.html#Top" rel="start" title="Top"> 0050 <link href="IndexDocument.html#Index" rel="index" title="Index"> 0051 <link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> 0052 <link href="Class-and-package-construction.html#Class-and-package-construction" rel="up" title="Class and package construction"> 0053 <link href="Fonts.html#Fonts" rel="next" title="Fonts"> 0054 <link href="Class-and-package-structure.html#Class-and-package-structure" rel="prev" title="Class and package structure"> 0055 <style type="text/css"> 0056 <!-- 0057 /* $Id: latex2e.css 690 2018-09-15 15:20:19Z jimhefferon $ 0058 Minor css for latexrefman. Public domain. 0059 Originally written by Jim Hefferon and Karl Berry, 2018. */ 0060 0061 /* So you can style for yourself */ 0062 @import url("/css/latexreflocal.css"); 0063 0064 0065 0066 a.summary-letter {text-decoration: none} 0067 blockquote.indentedblock {margin-right: 0em} 0068 blockquote.smallindentedblock {margin-right: 0em; font-size: smaller} 0069 blockquote.smallquotation {font-size: smaller} 0070 div.display {margin-left: 3.2em} 0071 div.example {margin-left: 3.2em} 0072 div.lisp {margin-left: 3.2em} 0073 div.smalldisplay {margin-left: 3.2em} 0074 div.smallexample {margin-left: 3.2em} 0075 div.smalllisp {margin-left: 3.2em} 0076 kbd {font-style: oblique} 0077 pre.display {font-family: inherit} 0078 pre.format {font-family: inherit} 0079 pre.menu-comment {font-family: serif} 0080 pre.menu-preformatted {font-family: serif} 0081 pre.smalldisplay {font-family: inherit; font-size: smaller} 0082 pre.smallexample {font-size: smaller} 0083 pre.smallformat {font-family: inherit; font-size: smaller} 0084 pre.smalllisp {font-size: smaller} 0085 span.nolinebreak {white-space: nowrap} 0086 span.roman {font-family: initial; font-weight: normal} 0087 span.sansserif {font-family: sans-serif; font-weight: normal} 0088 ul.no-bullet {list-style: none} 0089 BODY { 0090 margin-top: 1em; 0091 margin-left: 1em; /* auto results in two-digit <ol> lost off left */ 0092 margin-right: 1em; 0093 margin-bottom: 1em; 0094 /* the idea is to use the whole window, unless it is ridiculously 0095 wide, probably with too-small fonts, too. */ 0096 max-width: 64em; 0097 } 0098 0099 /* Because we want @math{... @code ...} to be upright, not slanted, 0100 and Texinfo won't fix it. */ 0101 code {font-style:normal; font-family:monospace; } 0102 0103 /* We put a link to our own home page at the bottom. */ 0104 div.referenceinfo {font-size:small;} 0105 0106 --> 0107 </style> 0108 0109 0110 </head> 0111 0112 <body lang="en"> 0113 <a name="Class-and-package-commands"></a> 0114 <div class="header"> 0115 <p> 0116 Previous: <a href="Class-and-package-structure.html#Class-and-package-structure" accesskey="p" rel="prev">Class and package structure</a>, Up: <a href="Class-and-package-construction.html#Class-and-package-construction" accesskey="u" rel="up">Class and package construction</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="IndexDocument.html#Index" title="Index" rel="index">Index</a>]</p> 0117 </div> 0118 <hr> 0119 <a name="Class-and-package-commands-1"></a> 0120 <h4 class="subsection">3.3.2 Class and package commands</h4> 0121 <a name="index-class-and-package-commands"></a> 0122 <a name="index-commands_002c-class-and-package"></a> 0123 0124 <p>These are the commands designed to help writers of classes or packages. 0125 </p> 0126 <dl compact="compact"> 0127 <dt><code>\AtBeginDvi{specials}</code></dt> 0128 <dd><a name="index-_005cAtBeginDvi"></a> 0129 <p>Save in a box register things that are written to the <samp>.dvi</samp> file 0130 at the beginning of the shipout of the first page of the document. 0131 </p> 0132 </dd> 0133 <dt><code>\AtEndOfClass{<var>code</var>}</code></dt> 0134 <dt><code>\AtEndOfPackage{<var>code</var>}</code></dt> 0135 <dd><a name="index-_005cAtEndOfClass"></a> 0136 <a name="index-_005cAtEndOfPackage"></a> 0137 <p>Hook to insert <var>code</var> to be executed when LaTeX finishes 0138 processing the current class or package. You can use these hooks 0139 multiple times; the <code>code</code> will be executed in the order that you 0140 called it. See also <a href="_005cAtBeginDocument.html#g_t_005cAtBeginDocument">\AtBeginDocument</a>. 0141 </p> 0142 </dd> 0143 <dt><code>\CheckCommand{<var>cmd</var>}[<var>num</var>][<var>default</var>]{<var>definition</var>}</code></dt> 0144 <dt><code>\CheckCommand*{<var>cmd</var>}[<var>num</var>][<var>default</var>]{<var>definition</var>}</code></dt> 0145 <dd><a name="index-_005cCheckCommand"></a> 0146 <a name="index-_005cCheckCommand_002a"></a> 0147 <a name="index-new-command_002c-check"></a> 0148 <p>Like <code>\newcommand</code> (see <a href="_005cnewcommand-_0026-_005crenewcommand.html#g_t_005cnewcommand-_0026-_005crenewcommand">\newcommand & \renewcommand</a>) but does 0149 not define <var>cmd</var>; instead it checks that the current definition of 0150 <var>cmd</var> is exactly as given by <var>definition</var> and is or is not 0151 <a name="index-long-command"></a> 0152 <em>long</em> as expected. A long command is a command that accepts 0153 <code>\par</code> within an argument. The <var>cmd</var> command is expected to be 0154 long with the unstarred version of <code>\CheckCommand</code>. Raises an 0155 error when the check fails. This allows you to check before you start 0156 redefining <code>cmd</code> yourself that no other package has already 0157 redefined this command. 0158 </p> 0159 </dd> 0160 <dt><code>\ClassError{<var>class name</var>}{<var>error text</var>}{<var>help text</var>}</code></dt> 0161 <dt><code>\PackageError{<var>package name</var>}{<var>error text</var>}{<var>help text</var>}</code></dt> 0162 <dt><code>\ClassWarning{<var>class name</var>}{<var>warning text</var>}</code></dt> 0163 <dt><code>\PackageWarning{<var>package name</var>}{<var>warning text</var>}</code></dt> 0164 <dt><code>\ClassWarningNoLine{<var>class name</var>}{<var>warning text</var>}</code></dt> 0165 <dt><code>\PackageWarningNoLine{<var>package name</var>}{<var>warning text</var>}</code></dt> 0166 <dt><code>\ClassInfo{<var>class name</var>}{<var>info text</var>}</code></dt> 0167 <dt><code>\PackageInfo{<var>package name</var>}{<var>info text</var>}</code></dt> 0168 <dt><code>\ClassInfoNoLine{<var>class name</var>}{<var>info text</var>}</code></dt> 0169 <dt><code>\PackageInfoNoLine{<var>package name</var>}{<var>info text</var>}</code></dt> 0170 <dd><a name="index-_005cClassError"></a> 0171 <a name="index-_005cPackageError"></a> 0172 <a name="index-_005cClassWarning"></a> 0173 <a name="index-_005cPackageWarning"></a> 0174 <a name="index-_005cClassWarningNoLine"></a> 0175 <a name="index-_005cPackageWarningNoLine"></a> 0176 <a name="index-_005cClassInfo"></a> 0177 <a name="index-_005cPackageInfo"></a> 0178 <a name="index-_005cClassInfoNoLine"></a> 0179 <a name="index-_005cPackageInfoNoLine"></a> 0180 <p>Produce an error message, or warning or informational messages. 0181 </p> 0182 <p>For <code>\ClassError</code> and <code>\PackageError</code> the message is 0183 <var>error text</var>, followed by TeX’s <code>?</code> error prompt. If the 0184 user then asks for help by typing <code>h</code>, they see the <var>help 0185 text</var>. 0186 </p> 0187 <p>The four warning commands are similar except that they write 0188 <var>warning text</var> on the screen with no error prompt. The four info 0189 commands write <var>info text</var> only in the transcript file. The 0190 <code>NoLine</code> versions do not show the number of the line generating the 0191 message, while the other versions do show that number. 0192 </p> 0193 <p>To format the messages, including the <var>help text</var>: use 0194 <code>\protect</code> to stop a command from expanding, get a line break with 0195 <code>\MessageBreak</code>, and get a space with <code>\space</code> when a space 0196 character does not allow it, like after a command. Note that LaTeX 0197 appends a period to the messages. 0198 </p> 0199 </dd> 0200 <dt><code>\CurrentOption</code></dt> 0201 <dd><a name="index-_005cCurrentOption"></a> 0202 <p>Expands to the name of the currently-being-processed option. Can only 0203 be used within the <var>code</var> argument of either <code>\DeclareOption</code> 0204 or <code>\DeclareOption*</code>. 0205 </p> 0206 </dd> 0207 <dt><code>\DeclareOption{<var>option</var>}{<var>code</var>}</code></dt> 0208 <dt><code>\DeclareOption*{<var>code</var>}</code></dt> 0209 <dd><a name="index-_005cDeclareOption"></a> 0210 <a name="index-_005cDeclareOption_002a"></a> 0211 <a name="index-class-options-2"></a> 0212 <a name="index-package-options-1"></a> 0213 <a name="index-options_002c-class"></a> 0214 <a name="index-options_002c-package-1"></a> 0215 <p>Make an option available to a user to invoke in their 0216 <code>\documentclass</code> command. For example, the <code>smcmemo</code> class 0217 could have an option <code>\documentclass[logo]{smcmemo}</code> allowing 0218 users to put the institutional logo on the first page. The class file 0219 must contain <code>\DeclareOption{logo}{<var>code</var>}</code> (and later, 0220 <code>\ProcessOptions</code>). 0221 </p> 0222 <p>If you request an option that has not been declared, by default this 0223 will produce a warning like <code>Unused global option(s): [badoption].</code> 0224 Change this behaviour with the starred version 0225 <code>\DeclareOption*{<var>code</var>}</code>. For example, many classes extend 0226 an existing class, using a declaration such as 0227 <code>\LoadClass{article}</code>, and for passing extra options to the 0228 underlying class use code such as this. 0229 </p> 0230 <div class="example"> 0231 <pre class="example">\DeclareOption*{% 0232 \PassOptionsToClass{\CurrentOption}{article}% 0233 } 0234 </pre></div> 0235 0236 <p>Another example is that the class <code>smcmemo</code> may allow users to keep 0237 lists of memo recipients in external files. Then the user could invoke 0238 <code>\documentclass[math]{smcmemo}</code> and it will read the file 0239 <code>math.memo</code>. This code handles the file if it exists and otherwise 0240 passes the option to the <code>article</code> class. 0241 </p> 0242 <div class="example"> 0243 <pre class="example">\DeclareOption*{\InputIfFileExists{\CurrentOption.memo}{}{% 0244 \PassOptionsToClass{\CurrentOption}{article}}} 0245 </pre></div> 0246 0247 </dd> 0248 <dt><code>\DeclareRobustCommand{<var>cmd</var>}[<var>num</var>][<var>default</var>]{<var>definition</var>}</code></dt> 0249 <dt><code>\DeclareRobustCommand*{<var>cmd</var>}[<var>num</var>][<var>default</var>]{<var>definition</var>}</code></dt> 0250 <dd><a name="index-_005cDeclareRobustCommand"></a> 0251 <a name="index-_005cDeclareRobustCommand_002a"></a> 0252 <a name="index-new-command_002c-definition"></a> 0253 <p>Like <code>\newcommand</code> and <code>\newcommand*</code> (see <a href="_005cnewcommand-_0026-_005crenewcommand.html#g_t_005cnewcommand-_0026-_005crenewcommand">\newcommand & \renewcommand</a>) but these declare a robust command, even if some code 0254 within the <var>definition</var> is fragile. (For a discussion of robust and 0255 fragile commands see <a href="_005cprotect.html#g_t_005cprotect">\protect</a>.) Use this command to define new 0256 robust commands or to redefine existing commands and make them 0257 robust. Unlike <code>\newcommand</code> these do not give an error if macro 0258 <var>cmd</var> already exists; instead, a log message is put into the 0259 transcript file if a command is redefined. 0260 </p> 0261 <p>Commands defined this way are a bit less efficient than those defined 0262 using <code>\newcommand</code> so unless the command’s data is fragile and the 0263 command is used within a moving argument, use <code>\newcommand</code>. 0264 </p> 0265 <a name="index-package_002c-etoolbox"></a> 0266 <a name="index-etoolbox-package"></a> 0267 <p>The <samp>etoolbox</samp> package offers the commands 0268 <code>\newrobustcmd</code>, <code>\newrobustcmd*</code>, as well as the commands 0269 <code>\renewrobustcmd</code>, <code>\renewrobustcmd*</code>, and the commands 0270 <code>\providerobustcmd</code>, and <code>\providerobustcmd*</code>. These are 0271 similar to <code>\newcommand</code>, <code>\newcommand*</code>, 0272 <code>\renewcommand</code>, <code>\renewcommand*</code>, <code>\providecommand</code>, and 0273 <code>\providecommand*</code>, but define a robust <var>cmd</var> with two 0274 advantages as compared to <code>\DeclareRobustCommand</code>: 0275 </p><ol> 0276 <li> They use the low-level e-TeX protection mechanism rather than the 0277 higher level LaTeX <code>\protect</code> mechanism, so they do not incur 0278 the slight loss of performance mentioned above, and 0279 </li><li> They make the same distinction between <code>\new…</code>, 0280 <code>\renew…</code>, and <code>\provide…</code>, as the standard 0281 commands, so they do not just make a log message when you redefine 0282 <var>cmd</var> that already exists, in that case you need to use either 0283 <code>\renew…</code> or <code>\provide…</code> or you get an error. 0284 </li></ol> 0285 0286 0287 </dd> 0288 <dt><code>\IfFileExists{<var>file name</var>}{<var>true code</var>}{<var>false code</var>}</code></dt> 0289 <dt><code>\InputIfFileExists{<var>file name</var>}{<var>true code</var>}{<var>false code</var>}</code></dt> 0290 <dd><a name="index-_005cIfFileExists"></a> 0291 <a name="index-_005cInputIfFileExists"></a> 0292 <p>Execute <var>true code</var> if LaTeX finds the file <samp><var>file 0293 name</var></samp> or <var>false code</var> otherwise. In the first case it executing 0294 <var>true code</var> and then inputs the file. Thus the command 0295 </p> 0296 <div class="example"> 0297 <pre class="example">\IfFileExists{img.pdf}{% 0298 \includegraphics{img.pdf}}{\typeout{!! img.pdf not found} 0299 </pre></div> 0300 0301 <p>will include the graphic <samp>img.pdf</samp> if it is found and otherwise 0302 give a warning. 0303 </p> 0304 <p>This command looks for the file in all search paths that LaTeX uses, 0305 not only in the current directory. To look only in the current 0306 directory do something like <code>\IfFileExists{./filename}{<var>true 0307 code</var>}{<var>false code</var>}</code>. If you ask for a filename without a 0308 <code>.tex</code> extension then LaTeX will first look for the file by 0309 appending the <code>.tex</code>; for more on how LaTeX handles file 0310 extensions see <a href="_005cinput.html#g_t_005cinput">\input</a>. 0311 </p> 0312 </dd> 0313 <dt><code>\LoadClass[<var>options list</var>]{<var>class name</var>}[<var>release date</var>]</code></dt> 0314 <dt><code>\LoadClassWithOptions{<var>class name</var>}[<var>release date</var>]</code></dt> 0315 <dd><a name="index-_005cLoadClass"></a> 0316 <a name="index-_005cLoadClassWithOptions"></a> 0317 <p>Load a class, as with <code>\documentclass[<var>options 0318 list</var>]{<var>class name</var>}[<var>release info</var>]</code>. An example is 0319 <code>\LoadClass[twoside]{article}</code>. 0320 </p> 0321 <p>The <var>options list</var>, if present, is a comma-separated list. The 0322 <var>release date</var> is optional. If present it must have the form 0323 <var>YYYY/MM/DD</var>. 0324 </p> 0325 <p>If you request a <var>release date</var> and the date of the package 0326 installed on your system is earlier, then you get a warning on the 0327 screen and in the log like this. 0328 </p> 0329 <div class="example"> 0330 <pre class="example">You have requested, on input line 4, version `2038/01/19' of 0331 document class article, but only version `2014/09/29 v1.4h 0332 Standard LaTeX document class' is available. 0333 </pre></div> 0334 0335 <p>The command version <code>\LoadClassWithOptions</code> uses the list of 0336 options for the current class. This means it ignores any options passed 0337 to it via <code>\PassOptionsToClass</code>. This is a convenience command 0338 that lets you build classes on existing ones, such as the standard 0339 <code>article</code> class, without having to track which options were passed. 0340 </p> 0341 </dd> 0342 <dt><code>\ExecuteOptions{<var>options-list</var>}</code></dt> 0343 <dd><a name="index-_005cExecuteOptions"></a> 0344 <p>For each option <var>option</var> in the <var>options-list</var>, in order, this command 0345 executes the command <code>\ds@<var>option</var></code>. If this command is not 0346 defined then that option is silently ignored. 0347 </p> 0348 <p>It can be used to provide a default option list before 0349 <code>\ProcessOptions</code>. For example, if in a class file you want the 0350 default to be 11pt fonts then you could specify 0351 <code>\ExecuteOptions{11pt}\ProcessOptions\relax</code>. 0352 </p> 0353 </dd> 0354 <dt><code>\NeedsTeXFormat{<var>format</var>}[<var>format date</var>]</code></dt> 0355 <dd><a name="index-_005cNeedsTeXFormat"></a> 0356 <p>Specifies the format that this class must be run under. Often issued 0357 as the first line of a class file, and most often used as: 0358 <code>\NeedsTeXFormat{LaTeX2e}</code>. When a document using that class is 0359 processed, the format name given here must match the format that is 0360 actually being run (including that the <var>format</var> string is case 0361 sensitive). If it does not match then execution stops with an error 0362 like ‘<samp>This file needs format `LaTeX2e' but this is `xxx'.</samp>’ 0363 </p> 0364 <p>To specify a version of the format that you know to have certain 0365 features, include the optional <var>format date</var> on which those features 0366 were implemented. If present it must be in the form <code>YYYY/MM/DD</code>. 0367 If the format version installed on your system is earlier than 0368 <var>format date</var> then you get a warning like this. 0369 </p> 0370 <div class="example"> 0371 <pre class="example">You have requested release `2038/01/20' of LaTeX, but only 0372 release `2016/02/01' is available. 0373 </pre></div> 0374 0375 </dd> 0376 <dt><code>\OptionNotUsed</code></dt> 0377 <dd><a name="index-_005cOptionNotUsed"></a> 0378 <p>Adds the current option to the list of unused options. Can only be used 0379 within the <var>code</var> argument of either <code>\DeclareOption</code> or 0380 <code>\DeclareOption*</code>. 0381 </p> 0382 0383 </dd> 0384 <dt><code>\PassOptionsToClass{<var>option list</var>}{<var>class name</var>}</code></dt> 0385 <dt><code>\PassOptionsToPackage{<var>option list</var>}{<var>package name</var>}</code></dt> 0386 <dd><a name="index-_005cPassOptionsToClass"></a> 0387 <a name="index-_005cPassOptionsToPackage"></a> 0388 <p>Adds the options in the comma-separated list <var>option list</var> to the 0389 options used by any future <code>\RequirePackage</code> or <code>\usepackage</code> 0390 command for package <var>package name</var> or the class <var>class name</var>. 0391 </p> 0392 <p>The reason for these commands is: you may load a package any number of 0393 times with no options but if you want options then you may only supply 0394 them when you first load the package. Loading a package with options 0395 more than once will get you an error like <code>Option clash for package 0396 foo.</code> (LaTeX throws an error even if there is no conflict between the 0397 options.) 0398 </p> 0399 <p>If your own code is bringing in a package twice then you can collapse 0400 that to once, for example replacing the two 0401 <code>\RequirePackage[landscape]{geometry}</code> and 0402 <code>\RequirePackage[margins=1in]{geometry}</code> with the single command 0403 <code>\RequirePackage[landscape,margins=1in]{geometry}</code>. 0404 </p> 0405 <p>However, imagine that you are loading <samp>firstpkg</samp> and inside that 0406 package it loads <samp>secondpkg</samp>, and you need the second package to be 0407 loaded with option <code>draft</code>. Then before doing the first package 0408 you must queue up the options for the second package, like this. 0409 </p> 0410 <div class="example"> 0411 <pre class="example">\PassOptionsToPackage{draft}{secondpkg} 0412 \RequirePackage{firstpkg} 0413 </pre></div> 0414 0415 <p>(If <code>firstpkg.sty</code> loads an option in conflict with what you want 0416 then you may have to alter its source.) 0417 </p> 0418 <p>These commands are useful for general users as well as class and package 0419 writers. For instance, suppose a user wants to load the <code>graphicx</code> 0420 package with the option <code>draft</code> and also wants to use a class 0421 <code>foo</code> that loads the <code>graphicx</code> package, but without that 0422 option. The user could start their LaTeX file with 0423 <code>\PassOptionsToPackage{draft}{graphicx}\documentclass{foo}</code>. 0424 </p> 0425 </dd> 0426 <dt><code>\ProcessOptions</code></dt> 0427 <dt><code>\ProcessOptions*<var>\@options</var></code></dt> 0428 <dd><a name="index-_005cProcessOptions"></a> 0429 <a name="index-_005cProcessOptions_002a"></a> 0430 <p>Execute the code for each option that the user has invoked. Include it 0431 in the class file as <code>\ProcessOptions\relax</code> (because of the 0432 existence of the starred command). 0433 </p> 0434 <p>Options come in two types. <em>Local options</em> have been specified for this 0435 particular package in the <var>options</var> argument of 0436 <code>\PassOptionsToPackage{<var>options</var>}</code>, 0437 <code>\usepackage[<var>options</var>]</code>, or 0438 <code>\RequirePackage[<var>options</var>]</code>. <em>Global options</em> are those given 0439 by the class user in <code>\documentclass[<var>options</var>]</code> (If an option 0440 is specified both locally and globally then it is local.) 0441 </p> 0442 <p>When <code>\ProcessOptions</code> is called for a package <samp>pkg.sty</samp>, the 0443 following happens: 0444 </p><ol> 0445 <li> For each option <var>option</var> so far declared 0446 with <code>\DeclareOption</code>, it looks to see if that option is either a 0447 global or a local option for <code>pkg</code>. If so then it executes the 0448 declared code. This is done in the order in which these options were 0449 given in <samp>pkg.sty</samp>. 0450 </li><li> For each remaining local option, it executes the command 0451 <code>\ds@</code><var>option</var> if it has been defined somewhere (other than by 0452 a <code>\DeclareOption</code>); otherwise, it executes the default option code 0453 given in <code>\DeclareOption*</code>. If no default option code has been 0454 declared then it gives an error message. This is done in the order in 0455 which these options were specified. 0456 </li></ol> 0457 0458 <p>When <code>\ProcessOptions</code> is called for a class it works in the same 0459 way except that all options are local, and the default <var>code</var> for 0460 <code>\DeclareOption*</code> is <code>\OptionNotUsed</code> rather than an error. 0461 </p> 0462 <p>The starred version <code>\ProcessOptions*</code> executes the 0463 options in the order specified in the calling commands, rather than in 0464 the order of declaration in the class or package. For a package this 0465 means that the global options are processed first. 0466 </p> 0467 </dd> 0468 <dt><code>\ProvidesClass{<var>class name</var>}[<var>release date</var> <var>brief additional information</var>]</code></dt> 0469 <dt><code>\ProvidesClass{<var>class name</var>}[<var>release date</var>]</code></dt> 0470 <dt><code>\ProvidesPackage{<var>package name</var>}[<var>release date</var> <var>brief additional information</var>]</code></dt> 0471 <dt><code>\ProvidesPackage{<var>package name</var>}[<var>release date</var>]</code></dt> 0472 <dd><a name="index-_005cProvidesClass"></a> 0473 <a name="index-_005cProvidesPackage"></a> 0474 <p>Identifies the class or package, printing a message to the screen and 0475 the log file. 0476 </p> 0477 <p>When you load a class or package, for example with 0478 <code>\documentclass{smcmemo}</code> or <code>\usepackage{test}</code>, LaTeX 0479 inputs a file. If the name of the file does not match the class or 0480 package name declared in it then you get a warning. Thus, if you invoke 0481 <code>\documentclass{smcmemo}</code>, and the file <samp>smcmemo.cls</samp> has 0482 the statement <code>\ProvidesClass{xxx}</code> then you get a warning like 0483 <code>You have requested document class `smcmemo', but the document 0484 class provides 'xxx'.</code> This warning does not prevent LaTeX from 0485 processing the rest of the class file normally. 0486 </p> 0487 <p>If you include the optional argument then you must include a date, 0488 before any spaces, of the form <code>YYYY/MM/DD</code>. The rest of the 0489 optional argument is free-form, although it traditionally identifies the 0490 class, and is written to the screen during compilation and to the log 0491 file. Thus, if your file <samp>smcmemo.cls</samp> contains the line 0492 <code>\ProvidesClass{smcmemo}[2008/06/01 v1.0 SMC memo class]</code> and 0493 your document’s first line is <code>\documentclass{smcmemo}</code> then you 0494 will see <code>Document Class: smcmemo 2008/06/01 v1.0 SMC memo class</code>. 0495 </p> 0496 <p>The date in the optional argument allows class and package users to ask 0497 to be warned if the version of the class or package is earlier than 0498 <var>release date</var>. For instance, a user could enter 0499 <code>\documentclass{smcmemo}[2018/10/12]</code> or 0500 <code>\usepackage{foo}[[2017/07/07]]</code> to require a class or package 0501 with certain features by specifying that it must be released no earlier 0502 than the given date. (Although, in practice package users only rarely 0503 include a date, and class users almost never do.) 0504 </p> 0505 </dd> 0506 <dt><code>\ProvidesFile{<var>file name</var>}[<var>additional information</var>]</code></dt> 0507 <dd><a name="index-_005cProvidesFile"></a> 0508 <p>Declare a file other than the main class and package files, such as 0509 configuration files or font definition files. Put this command in that 0510 file and you get in the log a string like <code>File: test.config 0511 2017/10/12 config file for test.cls</code> for <var>file name</var> equal to 0512 ‘<samp>test.config</samp>’ and <var>additional information</var> equal to 0513 ‘<samp>2017/10/12 config file for test.cls</samp>’. 0514 </p> 0515 </dd> 0516 <dt><code>\RequirePackage[<var>option list</var>]{<var>package name</var>}[<var>release date</var>]</code></dt> 0517 <dt><code>\RequirePackageWithOptions{<var>package name</var>}[<var>release date</var>]</code></dt> 0518 <dd><a name="index-_005cRequirePackage"></a> 0519 <a name="index-_005cRequirePackageWithOptions"></a> 0520 <p>Load a package, like the command <code>\usepackage</code> (see <a href="Additional-packages.html#Additional-packages">Additional packages</a>). The LaTeX development team strongly recommends use of 0521 these commands over Plain TeX’s <code>\input</code>; see the Class 0522 Guide. An example is 0523 <code>\RequirePackage[landscape,margin=1in]{geometry}</code>. 0524 </p> 0525 <p>The <var>option list</var>, if present, is a comma-separated list. The 0526 <var>release date</var>, if present, must have the form <var>YYYY/MM/DD</var>. If 0527 the release date of the package as installed on your system is earlier 0528 than <var>release date</var> then you get a warning like <code>You have 0529 requested, on input line 9, version `2017/07/03' of package jhtest, but 0530 only version `2000/01/01' is available</code>. 0531 </p> 0532 <p>The <code>\RequirePackageWithOptions</code> version uses the list of options 0533 for the current class. This means it ignores any options passed to it 0534 via <code>\PassOptionsToClass</code>. This is a convenience command to allow 0535 easily building classes on existing ones without having to track which 0536 options were passed. 0537 </p> 0538 <p>The difference between <code>\usepackage</code> and <code>\RequirePackage</code> is 0539 small. The <code>\usepackage</code> command is intended for the document file 0540 while <code>\RequirePackage</code> is intended for package and class files. 0541 Thus, using <code>\usepackage</code> before the <code>\documentclass</code> command 0542 causes LaTeX to give error like <code>\usepackage before 0543 \documentclass</code>, but you can use <code>\RequirePackage</code> there. 0544 </p></dd> 0545 </dl> 0546 0547 0548 0549 0550 <hr/><div class='referenceinfo'> <a href='https://latexref.xyz/'> <i>Unofficial LaTeX2e reference manual</i></a></div> 0551 </body> 0552 </html>