What are best practices for package authors to deal with package conflicts?

Question

One occasionally encountered problem with LaTeX is incompatibility between packages. What are best practices for package authors to deal with package conflicts?

For example:

• What is the best way to deal with package option conflicts?
• How should package conflicts be documented? (Is there a uniform/recommended way for presenting this in package documentation? I think thre isn't.)
• There is \PassOptionsToPackage.
• Is there a way of throwing an error if a particular package has already been loaded?
• Is there a standard way of telling the user (via a warning or error) to change the package loading order?
• How can a package detect an incorrect package loading order upon being loaded (if the respective dependencies are known to that package's author)?
• Is there a recommended way/interface for packages to communicate with regard to indicating or checking whether/how a certain command has already been patched/modified?
• Is there a recommended way for packages to document or warn other packages against what sorts of patches to existing commands they are executing?

(I have a suspicion that the "best" answer to some of these questions is "wait for LaTeX3", but this doesn't mean one can't or shouldn't document workarounds in the meantime. In fact I am asking these questions partly to provide a record of documentation.)

Some questions on TeX.SE constituting partial answers or asking for related information:

• Two conflicting packages in one document — doable?
• choosing macro names so as to avoid namespace conflicts
• Could using different packages cause a contradiction for the compiler?
• Creating a dependency tree (\RequirePackage) for packages used in my document
• Package options and \RequirePackage: order of commands and option conflicts?

Answer 1

Option processing (From source2e documentation)

When the options are processed, they are divided into two types: local and global:

• For a class, the options in the \documentclass command are local.
• For a package, the options in the \usepackage command are local, and the options in the \documentclass command are global.

The options for \documentclass and \usepackage are processed in the following way:

1. The local and global options that have been declared using \DeclareOption are processed first.

   • In the case of \ProcessOptions, they are processed in the order that they were declared in the class or package.
   • In the case of \ProcessOptions*, they are processed in the order that they appear in the option-lists. First the global options, and then the local ones.

2. Any remaining local options are dealt with using the default option (declared using the \DeclareOption*). For document classes, this usually does nothing, but records the option on a list of unused options. For packages, this usually produces an error.

In a practical way this means that when the same option is required it is good practise to make it global, for example language option that is required by a number of package

\documentclass[english]{article}
\usepackage{babel}%------ Uses global english
\usepackage{varioref}%--- Uses global english
\usepackage{refstyle}%--- Uses global english

Another example is amsmath that is loaded by a lot of packages. Sometimes the only way to set options is to make them global. For a package writer it is a way to get past conflicts by specifying global options.

Package loading order

If it is vital that your package must be loaded before another package then there are internal commands to test and mechanisms to throw an error or warning:

• \@ifpackageloaded{<package>}{<true>}{<false>}: To find out if a package has already been loaded
• \@ifpackagewith{<package>}{<options>}{<true>}{<false>}: To find out if a package has already been loaded with at least the options <options>

For example in the package declaration:

\ProvidesPackage{MYpackage}
\@ifpackageloaded{ABCpackage}%
   {\PackageError{MYpackage}{You must load MYpackage before ABCpackage}{}}%
   {}

Note that it is not good practise to enforce a loading order. As a package writer you can avoid conflicts in 98% of the cases by using \AtBeginDocument{} to test or to set something

\AtBeginDocument{%
    \@ifpackageloaded{graphicx}%
        {}%
        {\PackageError{MYpackage}{You must load the graphicx package}{}}}

Checking for patches

There is a Latex command \CheckCommand to test if a command was changed. It is again good to put this into a \AtBeginDocument{} to make tests and change commands. There are a number of problems, see for example this discussion

If you are patching a command it is good practice to inform users by writing it to the log file:

\PackageInfo{MYpackage}{The command ... was redefined}

But please do not redefine internal Latex command!