Why is it preferable to put inclusions of commonly used packages and user defined commands in a .sty
file instead of putting them in an ordinary .tex
file?
[Tex/LaTex] Why use .sty files
best practicespackages
Related Solutions
License considerations
The ledmac
package as well as many other packages in the LaTeX world isdistributed under the LaTeX Project Public License (LPPL). That means that you can use the code and you can modify it but for modification there are rules that you have to obey. The most important one is
If you are not the Current Maintainer of the Work, you may distribute a Derived Work provided the following conditions are met for every component of the Work unless that component clearly states in the copyright notice that it is exempt from that condition. Only the Current Maintainer is allowed to add such statements of exemption to a component of the Work.
(a) If a component of this Derived Work can be a direct replacement for a component of the Work when that component is used with the Base Interpreter, then, wherever this component of the Work identifies itself to the user when used interactively with that Base Interpreter, the replacement component of this Derived Work clearly and unambiguously identifies itself as a modified version of this component to the user when used interactively with that Base Interpreter.
In a nutshell this means that whenever you make changes you make them in a way that any other user that happens to use your modified file will be immediately aware of the fact that it was modified (and not only by searching in some comments inside the package). The typical way this is done in the TeX world is by simply renaming the file since the name is part of tthe interface, e.g., you say \usepackage{ledmac}
.
The reason for this requirement by LPPL is that LaTeX is a laguage for communication not just a typesetting system and to be able to communicate both side have to have a common understanding about the language. For some further information see the article about the history of LPPL that appeared in TUGboat.
Thus the LPPL is there to protect you and the community and even if you never intend to distributed your modification it is best not to violate the LPPL. After all your changes may escape easily (just a fact of life). The LPPL makes the following recommendations here:
It is wise never to modify a component of the Work, even for your own personal use, without also meeting the above conditions for distributing the modified component. While you might intend that such modifications will never be distributed, often this will happen by accident — you may forget that you have modified that component; or it may not occur to you when allowing others to access the modified version that you are thus distributing it and violating the conditions of this license in ways that could have legal implications and, worse, cause problems for the community. It is therefore usually in your best interest to keep your copy of the Work identical with the public one. Many works provide ways to control the behavior of that work without altering any of its licensed components.
Modification approaches
Suitable methods of modifying a package have already been discussed but to put everything into one answer, here is a quick summary from my perspective:
One time changes
Modifications that are intended to be done only for a single document are best placed in the preamble of the document. In most cases you have to surround your redefinitions with \makeatletter
and \makeatother
in order to be able to access or modify commands that contain an @
sign in their names.
A possible alternative to redefinitions is to use the \patchcmd
from the package etoolbox
that allows you to replace some code of a command with some other code, e.g., from your question
\usepackage{etoolbox}
\makeatletter
\patchcmd{\l@dlinenumR}{\numlabfont}{\numlabfontR}%
{\typeout{*** SUCCESS ***}}%
{\ERRORpatchfailed} % stop with error (undefined csname) if patch fails
\makeatother
You still need \makeatletter
because you modify a command with @
in its name but you restrict the modification to the necessary places which is usually helpful.
Modification intended for reuse on several documents
In that case using the document preamble is not necessarily a good idea because that means you repeat the same code over and over again. In that case the bes solution is to place your modifications into a small package and load this after the main package (unless of course the package itself doesn'T come with some configuration possibilities, as some do).
Note that if you use the package approach then do not use \makeatletter
inside: in style files the @
sign is automatically available for command names.
Bug fixes
Finally, if your change is more of a bug fix than a configuration, approach the author to provide an official update of the package. Of course as long as the bug persists you need to use one of the other approaches from above. In that case I would always propose to use the \patchcmd
solution in the preamble because then you will be automatically alerted if the package finally changes (because your patch then fails).
First, save the clashing identifiers:
\usepackage{keystroke}
\let\keystroke@Return\Return
\let\Return\undefined
\usepackage{algorithm2e}
\let\algorithmtwoe@Return\Return
\let\Return\undefined
Then defined two macros to setup the correct bindings.
\def\keystroke@setupbindings{%
\let\Return\keystroke@Return
}
\def\algorithmtwoe@setupbindings{%
\let\Return\algorithmtwoe@Return
}
Last patch the entry points using \Return
so that they start with the appropriate @setupbindings
macro. You can do this programatically by loading the replacement text of that entry point in a token register and refefining the entrypoint with \edef
:
% Some code that loads the expansion text of \entrypoint in toks0
\edef\entrypoint{\noexpand\keystroke@setupbindings\the\toks0}
It is impossible to attain the largest level of genericity because, to the best of my knowledge, it is not possible to recover the application template of a macro in TeX. But if you really need this, you can write \patch
macro so that
\patch\entrypoint\keystroke@setupbindings
does the same thing as the pseudo-code above. Dealing with \long
and \outer
modificators and macros having arguments can be a bit tedious, though, so it might be suitable to semi-manually patch the relevant macros.
EDIT — Well, it is actually possible to recover the application template of a macro and I should know this pretty good since I included a macro doing this in my Bhrìd TeX format! :-) Here is an untested translation for plain TeX:
\begingroup
\edef\next{%
\gdef\noexpand\toksloadmeaning@A
##1\noexpand\and##2\expandafter
\ignore\string\macro:##3->##4\noexpand\stop{%
##1{##3}##2{##4}%
}}
\next
\endgroup
\def\toksloadcsmeaning#1\to#2\and#3{%
\begingroup
\toks0={#2}%
\toks2={#3}%
\edef\next{\noexpand\toksloadmeaning@A\the\toks0 \noexpand\and\the\toks2 %
\meaning#1\noexpand\stop
}%
\expandafter\endgroup\next
}
After \toksloadcsmeaning\controlsequence\to{\toks1}\and{\toks3}
the token register \toks1
contains the application template and \toks3
the meaning of the macro. With this in hand, writing a \patch
macro should be a piece of cake.
Best Answer
First of all: never use
\include
to load a file with personal definitions and packages to use.The choice is thus between
\input
and\usepackage
; for the first it's better to use the extension.tex
for the file, for the second.sty
is mandatory.What are the pros of the latter solution? Many. For instance you can define options that can change the behavior of your macros or selectively load parts of it (see example below).
In a
.sty
file@
is assumed to be a letter, so no\makeatletter
or\makeatother
command is needed to access "private macros", which is often the case for complex macros.If you don't need options nor access to private macros, loading your definitions and package with
\input{mymacros}
is exactly equivalent to\usepackage{mymacros}
(provided that the file ismymacros.tex
in the first case andmymacros.sty
in the second one).As noticed by Andrew Stacey, there is one more pro in using a
.sty
file: it won't be loaded twice, even if called twice in a document (maybe frome some other loaded file or package). This is important because\newcommand
would raise errors on the second loading (and other definitions might lead to infinite loops).Example: Suppose you have a macro that must change its behavior when the
draft
option is enabled in the\documentclass
line; for instance it should have an argument that's emphasized in the text and is also written in the margin for draft copies.If a document does
then "TERM: foo" will be written in the margin. If
draft
is removed, the same source will only emphasize "foo" in the text.