LaTeX/Creating Packages

From Wikibooks, open books for an open world
Jump to: navigation, search
LaTeX logo.svg

LaTeX

Getting Started
  1. Introduction
  2. Installation
  3. Installing Extra Packages
  4. Basics

Common Elements

  1. Document Structure
  2. Text Formatting
  3. Paragraph Formatting
  4. Colors
  5. Fonts
  6. List Structures
  7. Special Characters
  8. Internationalization
  9. Rotations
  10. Tables
  11. Title creation
  12. Page Layout
  13. Importing Graphics
  14. Floats, Figures and Captions
  15. Footnotes and Margin Notes
  16. Hyperlinks
  17. Labels and Cross-referencing

Mechanics

  1. Errors and Warnings
  2. Lengths
  3. Counters
  4. Boxes
  5. Rules and Struts

Technical Texts

  1. Mathematics
  2. Advanced Mathematics
  3. Theorems
  4. Chemical Graphics
  5. Algorithms
  6. Source Code Listings
  7. Linguistics

Special Pages

  1. Indexing
  2. Glossary
  3. Bibliography Management
  4. More Bibliographies

Special Documents

  1. Letters
  2. Presentations
  3. Teacher's Corner
  4. Curriculum Vitae

Creating Graphics

  1. Introducing Procedural Graphics
  2. MetaPost
  3. Picture
  4. PGF/TikZ
  5. PSTricks
  6. Xy-pic
  7. Creating 3D graphics

Programming

  1. Macros
  2. Plain TeX
  3. Creating Packages
  4. Themes

Miscellaneous

  1. Modular Documents
  2. Collaborative Writing of LaTeX Documents
  3. Export To Other Formats

Help and Recommendations

  1. FAQ
  2. Tips and Tricks

Appendices

  1. Authors
  2. Links
  3. Package Reference
  4. Sample LaTeX documents
  5. Index
  6. Command Glossary

edit this boxedit the TOC

If you define a lot of new environments and commands, the preamble of your document will get quite long. In this situation, it is a good idea to create a LaTeX package or class containing all your command and environment definitions. It can be made dynamic enough to fit to all your future documents.

Classes are .cls files, package are stored in .sty files. They are very similar, the main difference being that you can load only one class per document.

makeatletter and makeatother[edit]

By default, LaTeX will allow the use of the '@' characters for control sequences from within package and class files, but not from within an end-user document. This way it is possible to protect commands, i.e. to make them accessible from packages only.

However it is possible to override this security with the duo \makeatletter and \makeatother. These commands only make sense in a regular document, they are not needed in package or class files.

\documentclass{...}
%...

\begin{document}

\makeatletter
\@author
\makeatother

\end{document
}

Creating your own package[edit]

Your package can be made available in your document just like any other package: using the \usepackage command. Writing a package basically consists of copying the contents of your document preamble into a separate file with a name ending in .sty.

Let's write a first custom.sty file as example:

\NeedsTeXFormat{LaTeX2e}[1994/06/01]
\ProvidesPackage{custom}[2013/01/13 Custom Package]

\RequirePackage{lmodern
}

%% 'sans serif' option
\DeclareOption{sans}{
  \renewcommand{\familydefault}{\sfdefault}
}

%% 'roman' option
\DeclareOption{roman}{
  \renewcommand{\familydefault}{\rmdefault}
}

%% Global indentation option
\newif\if@neverindent\@neverindentfalse
\DeclareOption{neverindent}{
  \@neverindenttrue
}

\ExecuteOptions{roman
}

\ProcessOptions\relax

%% Traditional LaTeX or TeX follows...
% ...

\newlength{\pardefault}
\setlength{\pardefault}{\parindent}
\newcommand{\neverindent}{ \setlength{\parindent}{0pt} }
\newcommand{\autoindent}{ \setlength{\parindent}{\pardefault}
}

\if@neverindent
\neverindent
\fi

% ...

\endinput

  • \NeedsTeXFormat{...} specifies which version of TeX or LaTeX is required at least to run your package. The optional date may be used to specify the version more precisely.
  • \ProvidesPackage has to have the same name of the file without the extension. It tells LaTeX the name of the package and will allow it to issue a sensible error message when you try to include a package twice. The date is important since it can be used by other package to specify the minimum version requirement they need to use your package.
  • Next you may write some TeX or LaTeX code like loading package, but write only the bare minimum needed for the package options set below.
  • \RequirePackage is equivalent to \usepackage.
  • \DeclareOptions are end-user parameters. Each option is declared by one such command.
  • \ExecuteOptions{...} tells which are the default.
  • \ProcessOptions\relax terminates the option processing.
  • Write whatever you want in it using all the LaTeX commands you know. Normally you should define new commands or import other packages.
  • \endinput: this must be the last command.

Once your package is ready, we can use it in any document. Import your new package with the known command \usepackage{mypack}. The file custom.sty and the LaTeX source you are compiling must be in the same directory.

\documentclass{...}
\usepackage[neverindent,sans]{custom
}
%...

\begin{document}

Blah...

\end{document
}


For a more convenient use, it is possible to place the package within $TEXMFHOME (which is ~/texmf by default) accoding to the TeX Directory Structure (TDS). That would be

$TEXMFHOME/tex/latex/custom/custom.sty

On Windows '~' is often C:\Users\username.

You may have to run texhash (or equivalent) to make your TeX distribution index the new file, thus making it available for use for any document. It will allow you to use your package as detailed above, but without it needing to be in the same directory as your document.

Creating your own class[edit]

It is also possible to create your own class file. The process is similar to the creation of your own package, you can call your own style file in the preamble of any document by the command:

\documentclass{myclass}

The name of the class file is then myclass.cls. Let's write a simple example:

\NeedsTeXFormat{LaTeX2e}
\ProvidesClass{myclass
}[2011/12/23 My Class]

%% Article options
\DeclareOption{10pt}{
  \PassOptionsToClass{\CurrentOption}{article}
}

%% Custom package options
\DeclareOption{sansserif}{
  \PassOptionsToPackage{\CurrentOption}{paxcommands}
}
\DeclareOption{neverindent}{
  \PassOptionsToPackage{\CurrentOption}{paxcommands}
}

%% Fallback
\DeclareOption*{
  \ClassWarning{myclass}{Unknown option '\CurrentOption'}
}

%% Execute default options
\ExecuteOptions{10pt}

%% Process given options
\ProcessOptions\relax

%% Load base
\LoadClass[a4paper]{article}

%% Load additional packages and commands.
\RequirePackage{custom}

%% Additional TeX/LaTeX code...

\endinput


  • \ProvidesClass is the counterpart of \ProvidesPackage.
  • \PassOptionsToClass and \PassOptionsToPackage are used to automatically invoke the corresponding options when the class or the package is loaded.
  • \DeclareOption*: the starred version lets you handle non-implemented options.
  • \ClassWarning will show the corresponding message in the TeX compiler output.
  • \LoadClass specifies the unique parent class, if any.

Hooks[edit]

There are also hooks for classes and packages.

  • \AtEndOfPackage
  • \AtEndOfClass

They behave as the document hooks. See LaTeX Hooks.


Previous: Plain TeX Index Next: Themes