LaTeX2ε for class and package writers

1 LATEX 2 for class and package writersCopyright 1995 2006 The LATEX ProjectAll rights reserved15 February 2006 Contents1 Writing classes and packages for LATEX 2 .. Overview .. Further information .. Policy on standard classes ..42 Writing classes and Old versions .. Using docstrip and doc .. Is it a class or a package ? .. Command names .. Box commands and colour .. Defining text and math characters .. General style ..73 The structure of a class or Identification .. Using classes and packages .. Declaring options .. A minimal class file .. Example: a local letter class .. Example: a newsletter class .. 144 Commands for class and package Identification .. Loading files .. Option declaration .. Commands within option code .. Moving options around .. Delaying code.

2 Option processing .. Safe file commands .. Reporting errors, etc .. Defining commands .. Moving arguments .. 255 Miscellaneous commands, Layout parameters .. Case changing .. The openany option in the book class .. Better user-defined math display environments .. Normalising spacing .. 276 Upgrading LATEX classes and Try it first! .. Troubleshooting .. Accommodating compatibility mode .. Font commands .. Obsolete commands .. 301 IntroductionThis document is an introduction to writing classes and packages for LATEX, withspecial attention given to upgrading existing LATEX packages to LATEX 2 .The latter subject is also covered in an article by Johannes Braams publishedin TUGboat Writing classes and packages for LATEX 2 LATEX is a document preparation system that enables the document writer toconcentrate on the contents of their text, without bothering too much aboutthe formatting of it.

3 For example, chapters are indicated by\chapter{ title }rather than by selecting 18pt file that contains the information about how to turn logical structure (like \chapter ) into formatting (like 18pt bold ragged right ) is adocument addition, some features (such as colour or included graphics) are independentof the document class and these are contained of the largest differences between LATEX and LATEX 2 is in the com-mands used to write packages and classes. In LATEX , there was very littlesupport for , and so writers had to resort to using 2 provides high-level commands for structuring packages . It is also mucheasier to build classes and packages on top of each other, for example writing alocal technical report classcetechr(for the Chemical Engineering department)based OverviewThis document contains an overview of how to write classes and packages forLATEX. It doesnotintroduce all of the commands necessary to write packages :these can be found in eitherLATEX: A Document Preparation SystemorTheLATEX Companion.

4 But it does describe the new commands for structuringclasses and some general advice about writing classes and describes the difference between classes and packages , the commandnaming conventions, the use ofdocanddocstrip, how TEX s primitivefile and box commands interact with LATEX. It also contains some hintsabout general LATEX 3describes the structure of classes and packages . This includes build-ing classes and packages on top of other classes and packages , declaringoptions and declaring commands. It also contains example 4lists the new class and package 6gives detailed advice on how to upgrade existing LATEX classesand packages to LATEX 2 . Further informationFor a general introduction to LATEX, including the new features of LATEX 2 , youshould readLATEX: A Document Preparation Systemby Leslie Lamport [2].A more detailed description of the new features of LATEX, including an overviewof more than 200 packages and nearly 1000 ready to run examples, is to befound inThe LATEX Companion second editionby Frank Mittelbach and MichelGoossens [3].

5 The LATEX system is based on TEX, which is described inThe TEXbookbyDonald E. Knuth [1].There are a number of documentation files which accompany every copy ofLATEX. A copy ofLATEX Newswill come out with each six-monthly release ofLATEX, and is found in the filesltnews*.tex. The author s guideLATEX 2 forAuthorsdescribes the new LATEX document features; it is guideLATEX 2 Font Selectiondescribes the LATEX font selection scheme forclass- and package - writers ; it is Configuring LATEX is coveredby the guideConfiguration options for LATEX 2 thephilosophy behind our policy on modifying LATEX is described documented source code (from the files used to produce the kernel ) is now available asThe LATEX 2 Sources. This very large doc-ument also includes an index of LATEX commands. It can be typeset from theLATEX thebasedirectory, using the source files and theclass this more information about TEX and LATEX, please contact your local TEX UsersGroup, or the international TEX Users Group.

6 Addresses and other details canbe found at: Policy on standard classesMany of the problem reports we receive concerning the standard classes are notconcerned with bugs but are suggesting, more or less politely, that the designdecisions embodied in them are not optimal and asking us to modify are several reasons why we should not make such changes to these files. However misguided, the current behaviour is clearly what was intendedwhen these classes were designed. It is not good practice to change such aspects of standard classes becausemany people will be relying on have therefore decided not to even consider making such modifications, norto spend time justifying that decision. This does not mean that we do not agreethat there are many deficiencies in the design of these classes, but we have manytasks with higher priority than continually explaining why the standard classesfor LATEX cannot be would, of course, welcome the production of better classes, or of packagesthat can be used to enhance these classes.

7 So your first thought when youconsider such a deficiency will, we hope, be what can I do to improve this? Similar considerations apply to those parts of the kernel that are implementingdesign decisions, many of which should be left to the class file but are not inthe current system. We realise that in such cases it is much more difficult foryou to rectify the problem yourself but it is also the case that making suchchanges in the kernel would probably be a major project for us; therefore suchenhancements will have to wait for Writing classes and packagesThis section covers some general points concerned with writing LATEX classesand Old versionsIf you are upgrading an existing LATEX style file then we recommend freezingthe version and no longer maintaining it. Experience with the variousdialects of LATEX which existed in the early 1990 s suggests that maintainingpackages for different versions of LATEX is almost impossible.

8 It will, of course,4be necessary for some organisations to maintain both versions in parallel forsome time but this is not essential for those packages and classes supported byindividuals: they should support only the new standard LATEX 2 , not obsoleteversions of Using docstrip and doc If you are going to write a large class or package for LATEX then you shouldconsider using thedocsoftware which comes with LATEX. LATEX classes andpackages written using this can be processed in two ways: they can be runthrough LATEX, to produce documentation ; and they can be processed withdocstrip, to produce can automatically generate indexes of definitions, indexesof command use, and change-log lists. It is very useful for maintaining anddocumenting large TEX documented sources of the LATEX kernel itself, and of the standard classes,etc, aredocdocuments; they are in in the distribution.

9 You can,in fact, typeset the source code of the kernel as one long document, completewith index, by running LATEX Typesetting these documentsuses the class more information ondocanddocstrip, consult the , , andThe LATEX Companion. For examples of its use, look at Is it a class or a package ?The first thing to do when you want to put some new LATEX commands in a fileis to decide whether it should be adocument classor apackage. The rule ofthumb is:If the commands could be used with any document class , then makethem a package ; and if not, then make them a are two major types of class : those likearticle,reportorletter,which are free-standing; and those which are extensions or variations of otherclasses for example, theprocdocument class , which is built on thearticledocument , a company might have a localownletclass for printing letters withtheir own headed note-paper. Such a class would build on top of the exist-ingletterclass but it cannot be used with any other document class , so , in contrast, provides commands for including imagesinto a LATEX document.

10 Since these commands can be used with any documentclass, we Command namesLATEX has three types of are the author commands, such as\section,\emphand\times: mostof these have short names, all in lower are also the class and package writer commands: most of these have longmixed-case names such as the following.\InputIfFileExists \RequirePackage \PassOptionsToClassFinally, there are the internal commands used in the LATEX implementation, suchas\@tempcnta,\@ifnextcharand\@eha: most of these commands contain@in their name, which means they cannot be used in documents, only in classand package , for historical reasons the distinction between these commands isoften blurred. For example,\hboxis an internal command which should onlybe used in the LATEX kernel, whereas\m@neis the constant 1 and could havebeen\ , this rule of thumb is still useful: if a command has@in its name thenit is not part of the supported LATEX language and its behaviour may changein future releases!