Take the 2-minute tour ×
TeX - LaTeX Stack Exchange is a question and answer site for users of TeX, LaTeX, ConTeXt, and related typesetting systems. It's 100% free, no registration required.

I didn't find anything about this issue, but if I missed something, please point me to it.

The documentation on the ctan.org site is usually about how to use the packages in a LaTeX document, but what if I want to edit the package itself? Is there documentation available?

And on a related note: is it advisable/OK to edit the package or rather try first tweaking the document and only later edit the package?

Editing the package certainly would affect all documents that use it in the future, so I suppose that it would be better to try changing the document options first, rather than go straight to edit the package.

share|improve this question
    
Related: tex.stackexchange.com/questions/2416/… –  Martin Schröder Mar 31 '12 at 13:19
add comment

4 Answers

up vote 19 down vote accepted

All or nearly all packages in the TeX world (e.g., those on CTAN) have a license attached to it. Depending on the license you are allowed to modify the package, but the license may pose restrictions upon you on how you do that.

If the license is LPPL (which is the case for many packages in the LaTeX world and beyond) then yes it is allowed to modify the package but the license requires you to obey the following important point (beside others):

§6a. 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 the good old days the common understanding was (and still is) that "if you change something that is used with TeX then change its file name" because then it can be distinguished from the original and doesn't pose any exchange problems, e.g., if you produce a variant of, say, my array package, call it array-xyz so that a document that uses your package immediately shows this fact as it would contain \usepackage{array-xyz} and not \usepackage{array} which might result in different formatting.

Now if you look at the quote above from the current LPPL this restriction has been softened and the LPPL now only requires that your variant package clearly identifies itself to the user as changed, e.g., which could be done through the \ProvidesPackage argument that could state [with additions by XYZ to fix ABC]. However, the usual practice (for good reason) is to stick to the rule that modification should be provided in a separate file with a new name as that is the easiest and best way to ensure compatibility and processability of documents across different installation (since if the file is not there this is immediately appearent, if it just slightly behaves differently then this may not be noticed until it is too late.

I should say that the above quote is only directly relevant to the situation where one intends to distribute the modification. But distribution can happen faster than one thinks, e.g., if you send the file to somebody else for processing your document you are already distributing even if only in a limited sense.

LPPL lists the following advice 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.

Finally to learn a bit more on the background of licenses in the TeX world and why the LPPL has the clauses it has and limits modification I suggest reading my TUG paper: "Reflections on the history of the LaTeX Project Public License (LPPL) - A software license for LaTeX and more".

share|improve this answer
    
Wow, I'm glad I asked! From the current answers it seem this wasn't as "trivial" as it originally seemed. I think I'll rather work on my document. By the way, if I understood well, I can upload my own packages? I mean, if I change a package I could update the one in the repository by mistake? That would be a huge problem. –  Alenanno Mar 31 '12 at 14:31
    
The main repository for TeX related packages is CTAN, and the submission process prevents arbitrary replacement of existing package code. So the worst you could do if you edited a package and kept the same name would be to change your system. Furthermore, depending on how your system is set up, /usr/local/ requires admin access to write to, so you likely can't replace an existing package unwittingly, even on your own system. –  Alan Munn Mar 31 '12 at 17:12
    
In general this is good practise to change the file name, but there are times when this is not possible. A number of packages have compatibility code in them that does, eg, \@ifpackageloaded{natbib}, and if you change the file name, this compatibility code no longer gets loaded. –  Lev Bishop Mar 31 '12 at 19:11
1  
@Lev see my comment to your answer --- it is only a problem if you do a file copy for which there is no real need and in fact which is less desiriable than only adjusting what is necessary. But if you really need to then you can still pretend that, say, natbib was loaded by defining \ver@natbib.sty. –  Frank Mittelbach Mar 31 '12 at 20:10
    
@FrankMittelbach think of my comment as a warning about a potential issue that might come up when you change the name of the package file. Thanks for pointing out that \ver@package.sty is the macro that needs defining. –  Lev Bishop Mar 31 '12 at 21:37
show 1 more comment

It's never a good idea to edit a package directly. If you feel that you must edit a package you should make a new copy of it and give it a different name, and save it in your local texmf folder.

That being said, however, it's rarely necessary to make new copies of packages to change them. There are various tools available for patching individual commands (see e.g. the etoolbox package) and it's also possible to copy just a small part of the code of a package into your document preamble and change it there.

As for documentation, some package authors provide separate code documentation, some include it in the user documentation, some add comments to the package itself and others (unfortunately) leave no trace.

share|improve this answer
add comment

Although the LPPL doesn't prohibit to modify a package, this is strongly discouraged from the practical point of view: if you modify the "original" in the main distribution tree, a later update might destroy your modifications.

Actually I myself did something like that, but for bugs that were due to be corrected in a few days.

The first thing to try when something with a package goes wrong is to patch it in the document or in a personal .sty file. There are many ways, which one to choose depends mostly on the patch to apply.

However, sometimes it's impossible to do a patch in this way. The best thing to do is to copy the package under another name and modify the copy. You will thus have the possibility to choose between the old version and the new one.

Never put such a modified package in the main distribution tree, as an update might destroy the new package. Use the "personal" tree (~/texmf on GNU/Linux systems and ~/Library/texmf on Mac OS X when using TeX Live), or the "local" tree rooted (for TeX Live) at /usr/local/texlive/texmf-local.

share|improve this answer
add comment

In decreasing order of preference:

  1. Tweak the document;
  2. Persuade the author of the package in question to make the changes you desire (you can help by sending them a patch, or at least a testcase and justification for the change). This way everyone gets to benefit and you don't have to worry about future updates to the package breaking your edits. Most package authors are very happy to include your suggested changes;
  3. Change the package filename and edit it with your changes;
  4. Make your changes on a copy of the file, but without changing the filename (sometimes this is necessary if other packages specifically check for the package by name in order to activate compatibility code for it). Put the copy of the file in a local tree (if you'll use the changes more than once), or in the document's directory (if the changes are specific to that document). The local version of the file will be found first, and the changed version won't be overridden by subsequent updates of the distribution. (Which of course means that you won't pick up any bugfixes, etc).

The only time I've gone as far as to make changes without changing the filename is with natbib, because of its structure it's difficult to make changes from your document to deep within its macros, the author is not receptive to bug reports from me, and since it completely revamps the latex citation mechanism, many packages contain compatibility code that specifically checks for it. As Frank Mittelbach points out, even then I probably should have spent a bit more effort and given my fixed version a different name and had it pretend to have loaded the original natbib.

share|improve this answer
3  
Point 4 is not necessary not even for the case you outlined. You can always write a package natbib-fixed which first does \RequirePackage{natbib} and then does any modification you deem needed. On a lower level you could even pretend to \@ifpackageloaded that a certain package is loaded if that is really necessary but with a little care it shouldn't. –  Frank Mittelbach Mar 31 '12 at 20:09
    
@FrankMittelbach sure, it's not necessary, but at some point, it's the easiest thing to do. In fact none of my points beyond point 1 are necessary, because one could always copy the entire package contents into the preamble of the document (with some tweaks to pretend to \@ifpackageloaded and such) and make the changes there.... Anyway, I'm in complete agreement with you that making local changes to a package is highly undesirable and almost never the right thing to do. I edited my answer a little to emphasize this. –  Lev Bishop Mar 31 '12 at 21:30
    
thanks for the edit. Yes it is not necessary but more than desirable. The TeX world has an unsurpased record of document (language) compatibility and that is largely due to the fact that we do not do in situ changes that potentially alter the language in an unsuspected way. We we should keep with this tradition if possible. –  Frank Mittelbach Mar 31 '12 at 21:37
    
Thanks for your insight, @LevBishop! :) –  Alenanno Apr 5 '12 at 12:37
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.