Команды классов и пакетов

Эти команды предназначены для авторов классов или пакетов.

\AtBeginDvi{specials} ¶

Сохраняет в регистр ящиков информацию, которая записывается в файл .dvi в начале вывода первой страницы документа.

\AtEndOfClass{code}

\AtEndOfPackage{code} ¶

Привязка для вставки кода, который будет выполнен, когда LaTeX завершит обработку текущего класса или пакета. Вы можете использовать эти привязки несколько раз; code будут выполнены в порядке вызова.

См. также \AtBeginDocument.

\CheckCommand{cmd}[num][default]{definition}

\CheckCommand*{cmd}[num][default]{definition} ¶

Подобно \newcommand (см. \newcommand & \renewcommand), но не определяет cmd; вместо этого проверяет, что текущее определение cmd точно соответствует заданному definition и является или не является длинным, как ожидалось. Длинная команда — это команда, которая принимает \par внутри аргумента. Команда cmd должна быть длинной с незвёздочным вариантом \CheckCommand. Вызывает ошибку при неудачной проверке. Это позволяет проверить перед переопределением cmd самим, что ни один другой пакет не переопределил эту команду.

\ClassError{class name}{error text}{help text}

\PackageError{package name}{error text}{help text}

\ClassWarning{class name}{warning text}

\PackageWarning{package name}{warning text}

\ClassWarningNoLine{class name}{warning text}

\PackageWarningNoLine{package name}{warning text}

\ClassInfo{class name}{info text}

\PackageInfo{package name}{info text}

\ClassInfoNoLine{class name}{info text}

\PackageInfoNoLine{package name}{info text} ¶

Выводит сообщение об ошибке, предупреждение или информационное сообщение.

Для \ClassError и \PackageError сообщение представляет собой текст ошибки, за которым следует приглашение для ввода ошибки TeX’а ?. Если пользователь затем запросит помощь, набрав h, он увидит текст справки.

Четыре команды предупреждения аналогичны, за исключением того, что они выводят текст предупреждения на экран без приглашения для ввода ошибки. Четыре команды информации записывают текст информации только в файл протокола. Версии NoLine не показывают номер строки, генерирующей сообщение, в то время как другие версии показывают этот номер.

Для форматирования сообщений, включая текст справки: используйте \protect для остановки расширения команды, получите перевод строки с помощью \MessageBreak, и получите пробел с помощью \space, когда пробел не разрешён, как после команды. Обратите внимание, что LaTeX добавляет точку к сообщениям.

\CurrentOption ¶

Выводит имя текуще обрабатываемого параметра. Может использоваться только внутри аргумента код команды \DeclareOption или \DeclareOption*.

\DeclareOption{option}{code}

\DeclareOption*{code} ¶

Делает параметр доступным для пользователя для вызова в команде \documentclass. Например, класс smcmemo может иметь параметр \documentclass[logo]{smcmemo}, позволяющий пользователям размещать логотип организации на первой странице. Файл класса должен содержать \DeclareOption{logo}{code} (и позже \ProcessOptions).

Если вы запрашиваете параметр, который не был объявлен, по умолчанию это вызовет предупреждение, подобное Unused global option(s): [badoption].. Измените это поведение с помощью звёздочного варианта \DeclareOption*{code}. Например, многие классы расширяют существующий класс, используя команду, такую как \LoadClass{article}, и для передачи дополнительных параметров в базовый класс используют код, подобный этому.

\DeclareOption*{%
\PassOptionsToClass{\CurrentOption}{article}%
}

Другой пример заключается в том, что класс smcmemo может позволять пользователям хранить списки получателей заметок во внешних файлах. Затем пользователь может вызвать \documentclass[math]{smcmemo} и он прочитает файл math.memo. Этот код обрабатывает файл, если он существует, в противном случае передает параметр классу article.

\DeclareOption*{\InputIfFileExists{\CurrentOption.memo}{}{%
    \PassOptionsToClass{\CurrentOption}{article}}}

\DeclareRobustCommand{cmd}[num][default]{definition}

\DeclareRobustCommand*{cmd}[num][default]{definition} ¶

Подобно \newcommand и \newcommand* (см. \newcommand & \renewcommand), но эти объявляют надёжную команду, даже если некоторый код внутри definition хрупкий. (Для обсуждения надёжных и хрупких команд см. \protect.) Используйте эту команду для определения новых надёжных команд или для переопределения существующих команд и придания им надёжности. В отличие от \newcommand, они не выдадут ошибку, если макрос cmd уже существует; вместо этого в файл протокола будет помещено сообщение журнала, если команда переопределена.

Команды, определённые таким образом, немного менее эффективны, чем те, которые определены с помощью \newcommand, поэтому, если данные команды хрупкие и команда используется в перемещаемом аргументе, используйте \newcommand.

Пакет etoolbox предлагает команды \newrobustcmd, \newrobustcmd*, а также команды \renewrobustcmd, \renewrobustcmd*, и команды \providerobustcmd, и \providerobustcmd*. Они похожи на \newcommand, \newcommand*, \renewcommand, \renewcommand*, \providecommand, и \providecommand*, но определяют надёжный cmd с двумя преимуществами по сравнению с \DeclareRobustCommand:

1. Они используют механизм защиты e-TeX низкого уровня, а не механизм LaTeX более высокого уровня \protect, поэтому они не несут незначительной потери производительности, упомянутой выше, и
2. Они делают то же различие между \new…, \renew…, и \provide…, что и стандартные команды, поэтому они не просто выдают сообщение журнала, когда вы переопределяете cmd, который уже существует; в этом случае вам нужно использовать либо \renew… или \provide…, иначе вы получите ошибку.

\IfFileExists{filename}{true code}{false code}

\InputIfFileExists{filename}{true code}{false code} ¶

Выполняет true code, если LaTeX находит файл file name, или false code в противном случае. В первом случае выполняется true code, а затем выполняется ввод файла. Таким образом, команда

\IfFileExists{img.pdf}{%
  \includegraphics{img.pdf}}{\typeout{!! img.pdf not found}

включит графику img.pdf, если она найдена, и в противном случае выдаст предупреждение.

Эта команда ищет файл во всех путях поиска, которые использует LaTeX, а не только в текущем каталоге. Для поиска только в текущем каталоге выполните что-то вроде \IfFileExists{./filename}{true code}{false code}. Если вы запрашиваете имя файла без .tex расширения, LaTeX сначала ищет файл, добавляя .tex; для получения дополнительной информации о том, как LaTeX обрабатывает расширения файлов, см. \input.

\LoadClass[options list]{class name}[release date]

\LoadClassWithOptions{class name}[release date] ¶

Загружает класс, как и в \documentclass[options list]{class name}[release info]. Пример: \LoadClass[twoside]{article}.

Список параметров, если он есть, — это список, разделённый запятыми. Дата выпуска необязательна. При наличии она должна иметь вид ГГГГ/ММ/ДД.

Если вы запрашиваете дату выпуска, а дата установленного пакета на вашей системе — более ранняя, то на экране и в журнале появляется предупреждение такого типа.

You have requested, on input line 4, version `2038/01/19' of
document class article, but only version `2014/09/29 v1.4h
Standard LaTeX document class' is available.

Команда версия \LoadClassWithOptions использует список параметров для текущего класса. Это означает, что она игнорирует любые параметры, переданные ей через \PassOptionsToClass. Это удобная команда, которая позволяет создавать классы на основе существующих, таких как стандартный класс article без необходимости отслеживать, какие параметры были переданы.

\ExecuteOptions{options-list} ¶

Для каждого параметра option в options-list, по порядку, эта команда выполняет команду \ds@option. Если эта команда не определена, этот параметр игнорируется.

Её можно использовать для предоставления списка параметров по умолчанию перед \ProcessOptions. Например, если в файле класса вы хотите установить шрифты по умолчанию 11pt, вы можете указать \ExecuteOptions{11pt}\ProcessOptions\relax.

\NeedsTeXFormat{format}[format date] ¶

Указывает формат, в котором должен быть запущен этот класс. Часто выводится в первой строке файла класса и чаще всего используется как: \NeedsTeXFormat{LaTeX2e}. Когда обрабатывается документ, использующий этот класс, имя формата, указанное здесь, должно совпадать с форматом, который фактически выполняется (включая то, что строка format чувствительна к регистру). Если они не совпадают, выполнение останавливается с ошибкой типа «Этот файл требует формат `LaTeX2e', но это `xxx'.»

Чтобы указать версию формата, которая, как вам известно, имеет определённые функции, включите необязательную дату формата, на которую были реализованы эти функции. Если она присутствует, она должна иметь вид YYYY/MM/DD. Если версия формата, установленная на вашей системе, старше даты формата, то вы получите предупреждение такого типа.

You have requested release `2038/01/20' of LaTeX, but only
release `2016/02/01' is available.

\OptionNotUsed ¶

Добавляет текущий параметр в список неиспользованных параметров. Может использоваться только внутри аргумента код команды \DeclareOption или \DeclareOption*.

\PassOptionsToClass{option list}{class name}

\PassOptionsToPackage{option list}{package name} ¶

Добавляет опции из перечисления через запятую option list к опциям, используемым любыми последующими командами \RequirePackage или \usepackage для пакета package name или класса class name.

Причина этих команд заключается в следующем: вы можете загрузить пакет любое количество раз без опций, но если вам нужны опции, то вы можете указать их только при первой загрузке пакета. Загрузка пакета с опциями более одного раза приведет к ошибке, подобной Option clash for package foo. (LaTeX выдает ошибку даже если между опциями нет конфликта).

Если ваш собственный код импортирует пакет дважды, вы можете объединить это в одну команду, например, заменив две команды \RequirePackage[landscape]{geometry} и \RequirePackage[margins=1in]{geometry} одной командой \RequirePackage[landscape,margins=1in]{geometry}.

Однако, представьте, что вы загружаете firstpkg, и внутри этого пакета загружается secondpkg, а вам нужно, чтобы второй пакет загружался с опцией draft. Тогда перед загрузкой первого пакета необходимо добавить опции для второго пакета, как показано ниже.

\PassOptionsToPackage{draft}{secondpkg}
\RequirePackage{firstpkg}

(Если firstpkg.sty загружает опцию, конфликтующую с вашей, то вам, возможно, придется изменить ее исходный код).

Эти команды полезны как для обычных пользователей, так и для авторов классов и пакетов. Например, предположим, что пользователь хочет загрузить пакет graphicx с опцией draft и также хочет использовать класс foo, который загружает пакет graphicx, но без этой опции. Пользователь может начать свой файл LaTeX с \PassOptionsToPackage{draft}{graphicx}\documentclass{foo}.

\ProcessOptions

\ProcessOptions*\@options ¶

Выполняет код для каждой опции, которую вызвал пользователь. Включите его в файл класса как \ProcessOptions\relax (из-за существования звёздчатой команды).

Опции бывают двух типов. Локальные опции были указаны для данного пакета в аргументе options команды \PassOptionsToPackage{options}, \usepackage[options], или \RequirePackage[options]. Глобальные опции задаются пользователем класса в \documentclass[options] (Если опция указана как локально, так и глобально, то она считается локальной).

Когда вызывается \ProcessOptions для пакета pkg.sty, происходит следующее:

1. Для каждой опции option, объявленной до сих пор с помощью \DeclareOption, проверяется, является ли она глобальной или локальной опцией для pkg. Если да, то выполняется объявленный код. Это делается в порядке, в котором эти опции были указаны в pkg.sty.
2. Для каждой оставшейся локальной опции выполняется команда \ds@option, если она определена где-либо (кроме как в \DeclareOption); в противном случае выполняется код по умолчанию для этой опции, указанный в \DeclareOption*. Если код по умолчанию не объявлен, то выводится сообщение об ошибке. Это делается в порядке указания этих опций.

При вызове \ProcessOptions для класса всё происходит аналогично, за исключением того, что все опции являются локальными, а код по умолчанию code для \DeclareOption* равен \OptionNotUsed, а не сообщению об ошибке.

Звездообразная версия \ProcessOptions* выполняет опции в порядке их указания в вызывающих командах, а не в порядке объявления в классе или пакете. Для пакета это означает, что глобальные опции обрабатываются первыми.

\ProvidesClass{class name}[release date brief additional information]

\ProvidesClass{class name}[release date]

\ProvidesPackage{package name}[release date brief additional information]

\ProvidesPackage{package name}[release date] ¶

Определяет класс или пакет, выводит сообщение на экран и в журнал.

При загрузке класса или пакета, например, с помощью \documentclass{smcmemo} или \usepackage{test}, LaTeX вводит файл. Если имя файла не совпадает с именем класса или пакета, объявленного в нем, вы получите предупреждение. Таким образом, если вы вызываете \documentclass{smcmemo}, а файл smcmemo.cls содержит оператор \ProvidesClass{xxx}, то вы получите предупреждение, подобное You have requested document class `smcmemo', but the document class provides 'xxx'.. Это предупреждение не препятствует LaTeX обрабатывать остальную часть файла класса.

Если вы используете необязательный аргумент, вы должны указать дату в формате YYYY/MM/DD, перед любыми пробелами. Остальной необязательный аргумент может быть произвольным, хотя традиционно он идентифицирует класс и отображается на экране во время компиляции, а также в журнале. Так, если ваш файл smcmemo.cls содержит строку \ProvidesClass{smcmemo}[2008/06/01 v1.0 SMC memo class], а первая строка вашего документа — \documentclass{smcmemo}, то вы увидите Document Class: smcmemo 2008/06/01 v1.0 SMC memo class.

Дата в необязательном аргументе позволяет пользователям классов и пакетов требовать предупреждения, если версия класса или пакета старше указанной release date. Например, пользователь может ввести \documentclass{smcmemo}[2018/10/12] или \usepackage{foo}[[2017/07/07]] для того, чтобы требовать класс или пакет с определенными функциями, указав, что он должен быть выпущен не ранее указанной даты. (Хотя на практике пользователи пакетов редко включают дату, а пользователи классов практически никогда не делают этого).

\ProvidesFile{filename}[additional information] ¶

Объявляет файл, отличный от основных файлов класса и пакета, например, файлы конфигурации или определения шрифтов. Поместите эту команду в этот файл, и вы получите в журнале строку, подобную File: test.config 2017/10/12 config file for test.cls для filename равного ‘test.config’ и additional information равного ‘2017/10/12 config file for test.cls’.

\RequirePackage[option list]{package name}[release date]

\RequirePackageWithOptions{package name}[release date] ¶

Загружает пакет, как и команда \usepackage (см. Дополнительные пакеты). Команда LaTeX Development team настоятельно рекомендует использовать эти команды вместо команд Plain TeX \input; см. Руководство по классам. Пример: \RequirePackage[landscape,margin=1in]{geometry}.

Если присутствует option list, то это перечисление через запятую. Если присутствует release date, то она должна иметь формат YYYY/MM/DD. Если дата выпуска пакета, установленного на вашей системе, раньше release date, то вы получите предупреждение, подобное You have requested, on input line 9, version `2017/07/03' of package jhtest, but only version `2000/01/01' is available.

Версия \RequirePackageWithOptions использует список опций для текущего класса. Это означает, что она игнорирует любые опции, переданные ей через \PassOptionsToClass. Эта команда удобна для лёгкого создания классов на основе существующих, без необходимости отслеживания переданных опций.

Различие между \usepackage и \RequirePackage незначительно. Команда \usepackage предназначена для файла документа, в то время как \RequirePackage предназначена для файлов пакетов и классов. Таким образом, использование \usepackage перед командой \documentclass заставит LaTeX выдать ошибку, подобную \usepackage before \documentclass, но вы можете использовать \RequirePackage там.