13

I'd like to propose an improvement for the FAQ. It was suggested I should post a question here to get things started.

Many problems (and therefore questions) can be avoided if the poster updates their packages/classes. I think it would be good to add a comment about that in the FAQ. For example, the following may be a good addition.

  • LaTeX is very stable but many problems are cause by classes and packages that are out of date.
  • If your question is bug-related then you should consider updating your classes and packages to the most recent version.
  • How to update depends on your LaTeX installation and operating system. If it's TeX Live then you can updatee by running tlmgr from the command line, or running the tlmrg GUI.

Of course there could be link from the last sentence to a page that explains how to update for Mac/Windows/Unix and all the possible distributions.

What do you think?

  • 1
    +1, but are you purposely using upgrade instead of update? It seems to me that update is more commonly used. Addition: Let's make sure there are good How do I update my [TeX Live / MiKTeX / XYZ] system? references to link to, either questions on here or external guides. – doncherry Jan 26 '12 at 10:17
  • @doncherry I thought upgrade was better but I changed to update. – user10274 Jan 26 '12 at 10:21
  • 1
    and so in true Carollian fashion, you wrote "updade". I suspect that mome raths updade frequently. – Loop Space Jan 26 '12 at 12:55
  • 5
    there are times when it's a bad idea to update, for example, you've been working on your dissertation for two years, and the problem arises just one week before it's due. at that point, it's better to find a workaround than to start over from a new base. and update immediately after the dissertation has been accepted and the final copy turned in. – barbara beeton Jan 26 '12 at 13:49
  • 3
    @barbarabeeton Sure, but the FAQ could provide a link to a page explaining the advantages/disadvantages of updating and how to do it. – user10274 Jan 26 '12 at 14:02
  • 2
    It's a nice idea, but as barbara mentioned, I'm also quite reticent to suggest a full distro update in the wild at first. Maybe the FAQ could have an entry on how to query/display engines/packages versions; then the OP could say, "I use the foo package, version 1.2. – Paulo Cereda Jan 27 '12 at 18:20
  • @PauloCereda I never intended advising to update the entire distribution. Just a bit of common sense is what I meant. Check your version with the most recent version, that's all/ – user10274 Jan 27 '12 at 18:25
  • @MarcvanDongen: ah sorry, I see your point now. :) In that case, I don't see any potential harms, only if the package depends on other packages like expl3. :) – Paulo Cereda Jan 27 '12 at 18:31
4

We currently have

To help people answer your question quickly and precisely, remember to ask clear questions and, if possible, to include a small example of code that shows the problem that you want to solve.

Perhaps we should add to the end

If you are having an issue with a specific package, document class or program, it's a good idea to include in your question which version you are using. For LaTeX classes and packages, adding \listfiles to your preamble will give you a handy list of all the files used by your example: you can then copy this into your question from your .log file. Also please mention which operating system you are using.

Finally, it should be noted that many problems and bugs are caused by classes and packages that are out of date. Before positing a question to TeX.sx about your bug, you may consider updating your relevant class and packages. Before updating, it is always a good idea to back up your previous installation.

If you're using TeX Live, you may update classes and packages with the tlmgr program. You may update the entire TeX Live installation by running tlmgr update --all from the command line. (This may take a while.) On windows and the mac, you may also run tlmgr with a graphical user interface.

  • CS answer: please edit as needed – Joseph Wright Feb 11 '12 at 10:34
  • 2
    even though the suggestion is given to back up before updating, it's still possible to get burned if a new version doesn't solve the problem. the tactic i employ is to install the new version into a test area with the project files and only do a "library" installation once it's been demonstrated that the new files do solve the problem without causing bad side effects. this is probably too much to explain in a faq entry, but (having suffered from too many near disasters) i think the backup warning should be stronger, with maybe a pointer to help if something does go wrong. – barbara beeton Feb 11 '12 at 15:40
  • Like @barbarabeeton, I am not comfortable with having 'update' in the FAQ. At the very least, we'd need to link to a question detailing how to do this. That was the reason I limited my text to 'tell us what version you have'. – Joseph Wright Feb 11 '12 at 17:13
  • I added the comment about making a backup to address the issue of getting burned. Omitting the last two paragraphs doesn't address my proposal. Personally, I think that with the current state of TeX Live it's almost impossible to get wrong if you do a full update. If you feel otherwise, please suggest some wording that addresses getting burned, and how to properly go about a complete update and/or package reinstall. As suggested by Joseph, we can put all these comments in a separate page and provide a link. – user10274 Feb 12 '12 at 7:24
  • @barbarabeeton/@JosephWright I'm happy the way it's phrased at the moment. If you want a different text/formulation, the ball's in your court. – user10274 Feb 15 '12 at 19:17
  • Not all TeX Live installations have tlmgr; if it is packaged by a Linux distribution, they will prefer their own ways of updating packages (through the package management system). – Andrey Vihrov Feb 15 '12 at 19:43
  • @AndreyVihrov That's why I wrote if you're using TeX Live .... BTW I'm using ubuntu and I wouldn't want to live without TeX Live. – user10274 Feb 15 '12 at 20:44
  • @MarcvanDongen: Note that I wrote TeX Live installations, not TeX installations. – Andrey Vihrov Feb 15 '12 at 20:46
  • @AndreyVihrov Thanks for that. I thought that tlmgr came with TeX Live. For example tug.org/texlive/tlmgr.html suggests it is included in TeX Live. Can you give an example? – user10274 Feb 16 '12 at 5:05
  • @MarcvanDongen: 1 2 3 have no tlmgr or don't have it in PATH, because they are intended to be updated through the corresponding Linux distribution's package manager. – Andrey Vihrov Feb 16 '12 at 6:36
  • @AndreyVihrov Ah, now I understand. Usually, relying on your package manager to install TeX Live means that you're hopefully out of date. I really meant a user-installed TeX Live installation. – user10274 Feb 16 '12 at 7:26
  • @MarcvanDongen: As you can see from the links, the only one outdated is Ubuntu's version ;-) – Andrey Vihrov Feb 16 '12 at 8:30
  • This is not making progress. – user10274 Feb 22 '12 at 20:29
  • This is my final comment about this stalemate discussion. Please do whatever you feel is best. – user10274 Mar 5 '12 at 7:04
  • @MarcvanDongen Well, as there are upvotes for this and no further comments, I feel I have to act. So I will make the edit. – Joseph Wright Mar 5 '12 at 8:59
2

Do you have any suggestions on the wording?

Once the wording for the note is settled, I (or a moderator) can update the FAQ. :)

You must log in to answer this question.