\documentclass[12pt]{article} \begin{document} \noindent Eric Beitz \hfill March 2005 \section*{\TeX{}shade: frequently asked questions } \bigskip This is the sixth update of the FAQ list for \TeX{}shade. Feel free to contact me if you have problems, questions or suggestions about the package. I will post them and provide hopefully helpful hints in future issues of this list. \bigskip \noindent \qquad email: \texttt{eric.beitz@uni-tuebingen.de} \smallskip \noindent \TeX{}shade: \texttt{http://homepages.uni-tuebingen.de/beitz/tse.html} \subsection*{A. Increasing \TeX{}'s memory settings} \medskip If you are using \TeX{}shade to align several large sequences (about 1000 residues/sequence), LaTeX will probably stop compiling and quit with one of the following messages: \texttt{!\ TeX capacity exceeded, sorry [main memory size=384000]} or \texttt{!\ TeX capacity exceeded, sorry [stack size=300]}. Due to several requests I want to start a list of protocols how to increase the standard \TeX{} memory settings for bigger alignments. Please contribute to this list by sending me the procedure for your particular system. \begin{enumerate} \item \textbf{Oz\TeX{} 4.0 for the Macintosh:} Find the file `OzTeX:TeX:Configs:Default'. This file contains all memory settings. Look for the section `\% TeX parameters' and increase the values that \TeX{} complains about during the run. You will have to restart Oz\TeX{} before the changes are active. For older versions of Oz\TeX{} the configuration file has the same name but the path is somewhat different. \item \textbf{te\TeX{} for *NIX:} (contributed by Joerg Daehn) Find the file: `/usr/share/texmf/web2c/texmf.cnf' or use \verb|locate texmf.cnf| at the command prompt to find it. Login as super user. Backup `texmf.cnf' in case you destroy something and then open the `texmf.cnf' file in your favorite text editor and use its search function to locate \verb|main_memory|. This variable is set to 384000. Change this to some higher value, i.e. 4000000 (works fine for me!). The total amount of memory should not exceed 8000000, so check the other values in that section. Next, you want to change the stack size. Search for \verb|stack_size|. This will be set to 300. I changed it to 4000 and it works fine. There might be complains by \TeX{} about further specific parameters such as \verb|stack_size|. You find all those in the same file. After this you have to run `texconfig init'. Logout as root. After this all should be set for large alignments. Happy \TeX{}ing! The information on how to achieve this was derived from a mail in the te\TeX{} mail archive. The original question was posted by Pascal Francq and answered by Rolf Nieprasch. \item \textbf{MiK\TeX{} for Windows:} The MiK\TeX{} documentation describes very detailed how the memory settings can be changed. In brief, you must locate the configuration file `miktex/config/miktex.ini'. In the [MiKTeX] section of this file you find all the parameters you need, e.\,g.\ \verb|mem_min|, \verb|mem_max|, \verb|buf_size|, \verb|stack_size| etc. It appears, that the standard settings of MiK\TeX{} are bigger than that of other \TeX{} installations, so it may not always be necessary to increase the values. \end{enumerate} \subsection*{B. Problems using \TeX{}shade} \medskip \begin{enumerate} \item \textbf{I cannot \TeX{} the manual because I get the error message `\texttt{!\ TeX capacity exceeded, sorry \ldots}'.} \TeX{}shade needs a lot of memory for setting and shading alignments. The manual is a good test for your memory settings because it uses many alignments and fingerprints, which are in particular memory consuming. If you do not know how to increase \TeX's memory settings, and you do not know a \TeX{} wizard either, then visit the \TeX{}shade homepage at \texttt{http://homepages.uni-tuebingen.de/beitz/tse.html} for downloading the manual in either of three formats: DVI, PDF or PostScript. \item \textbf{I can set my alignment only when I reduce the number of base-pairs by about 11,000. Otherwise I get the `\texttt{!\ TeX capacity exceeded, sorry \ldots}' error.} There are several parameters defining \TeX's usable space. If you are a \TeX{} wizard (or you know one) increase the values that \TeX{}shade complains about during the run in order to set bigger alignments. But do not be disappointed when your \TeX{} system will not set an alignment containing thousands of residues. There is definitely an upper limit (probably the new \LaTeX3 will allow you to use even more memory). Setting alignments is a big job for a typesetting system! \item \textbf{I want to align 80 sequences but I get the `\texttt{!\ No room for a new count}' message.} For each sequence two counter variables are used by \TeX{}shade, further 14 counters for other purposes are needed (and \TeX{} can handle only 255 counters). This limits the amount of sequences to about 100 in theory. But \LaTeX{} itself and each of the loaded packages allocates more counters further reducing the maximum number of sequences. \item \textbf{I receive error messages `\texttt{!\ Missing \$ inserted}' when \TeX{}ing my alignment. What is wrong?} At least one of the sequence names in the alignment file contains an underscore `\_' symbol. This makes \TeX{} to believe you missed to enter math mode because subscript initiated by an underscore is only allowed in math. You need to change the sequence name(s) either in the alignment file using the `find \& replace' option of your editor or by using the \verb|\nameseq| command in the \TeX{}shade environment. Nevertheless, subscript and superscript are permitted in sequence names, e.\,g. \verb|\nameseq{1}{Name$_{sub}^{super}$}| will result in Name$_{sub}^{super}$. Since v1.3b \TeX{}shade{} is much more tolerant concering special characters. Get it and read the section about sequence names. \item \textbf{My sequence names start out with a number in the alignment file. Why are they ignored by \TeX{}shade?} \TeX{}shade analyzes the first character of each line in the alignment file in order to decide whether it is a comment, a ruler or a sequence line etc. All lines starting out with a non-letter character are interpreted as non-sequence lines. Hence, you have to change those names in the alignment file. If you want to have sequence names starting with a number you can use the \verb|\nameseq| command in the \TeX{}shade environment to introduce the number, e.\,g. \verb|\nameseq{1}{57th sequence}|. \item \textbf{Only a fraction of the residues which are supposed to be shaded actually are. Why?} Make sure that \TeX{}shade knows when protein sequences are to be set. Align\-ments in the ALN-format do not contain information about the sequence type (DNA or protein). In such cases DNA sequences are assumed by \TeX{}shade leading to a shading of only A's, C's, G's, R's, T's and Y's. A simple solution is to say \verb|\seqtype{P}| in the \verb|texshade| environment. \item \textbf{Functional shading does not work and I get an error message. Why?} Same problem as discussed in the point before this one. Functional shading is permitted only on protein sequences. So, tell \TeX{}shade that you are using a protein alignment. \item \textbf{There is an incompatiblity between \TeX{}shade (v1.2) and the multi-language package `\texttt{babel}'!} You are right! The command \verb|\language| is defined in both packages which leads to error messages. This bug is fixed since the release of \TeX{}shade version 1.3 from March 2000. In this version \verb|\language| is replaced by two commands: \verb|\germanlanguage| and \verb|\englishlanguage|. \item \textbf{\TeX{}shade crashes when dashes ``-'' are used as gap symbols in alignment input files.} Yes. Be careful with all kinds of characters that are ``active'' in \TeX{}, such as \verb|$ _ ^ & % " \|. The dash is not really active but two or three consecutive dashes are amalgamated to one longer dash in \TeX. Having those characters in an input file might result in unforeseen errors or even crashes. \item \textbf{I have problems using PHD predictions in \TeX{}shade. An empty \texttt{.top} or \texttt{.sec} file is created.} When you do the PHD run do not restrict the calculation to either secondary structure or topology prediction. Turn on everything. Otherwise the output will have some ambiguous lines which can not be interpreted by \TeX{}shade. Result is an empty \texttt{.top} or \texttt{.sec} file. \end{enumerate} \subsection*{C. Changing the output} \medskip \begin{enumerate} \item \textbf{How can I force \TeX{}shade to print more residues per line?} Use the \verb|\residuesperline*| command with the `\verb|*|' extension. This will allow you to set any number of residues per line that is desired, e.\,g. \verb|\residuesperline*{97}|. But then expect numerous `\texttt{!\ Overfull hbox}' errors due to printing lines that are broader than the preset \verb|\textwidth|. The same command without the `\verb|*|' will calculate the highest number of residues fitting in one line and round it to be divisible by five. \item \textbf{Is it possible to add a caption to the \TeX{}shade output?} Yes, it is. Since \TeX{}shade v1.5 the \verb|\showcaption| command is available to add captions on the top or the bottom of the alignment. The caption behaves exactly as a figure caption including the style, numbering and appearance in the list of figures. \medskip Example: \verb|\showcaption{Nice alignment!}|. \item \textbf{I want a short version of the caption for the `List of Figures'. Is this possible?} Yes, with \TeX{}shade v1.9 short captions have been introduced. In addition to \verb|showcaption| use the command \verb|shortcaption{|\emph{text}\verb|}|. \medskip Example: \verb|\showcaption{Nice alignment!}|\ \verb|\shortcaption{Nice}|. \item \textbf{My alignment file contains the letters `B' and `Z' for Asx and Glx, respectively. How can I apply a special shading for these?} Use \verb|\funcgroup| to define `B' and `Z' as functional groups and assign the colors and the printing style, e.\,g. \medskip \verb|\funcgroup{B}{White}{Blue}{upper}{up}| \smallskip \verb|\funcgroup{Z}{White}{Red}{upper}{up}| \medskip or add the new residues to an existing group, e.\,g. \medskip \verb|\funcgroup{acidic/amide}{DENQBZ}{Black}{Green}{upper}{up}|. \item \textbf{How can I build a legend using the `\texttt{shadebox}' command?} The \verb|\shadebox| command simply prints a color-filled box at the very location it occurs in the text. This means you have to use \verb|\shadebox| in the normal text after the \TeX{}shade environment or inside the caption. You find a minimal example below: \medskip \qquad\vbox{% \verb|\begin{texshade}{alignmentfile.MSF}| \medskip \qquad \verb|\showcpation{Red box: \shadebox{Red}}| \medskip \qquad \emph{further commands, if needed} \medskip \verb|\end{texshade}| } \medskip Legend: \qquad\verb|\shadebox{conserved}|: conserved residues \qquad\verb|\shadebox{White}|: boring residues \qquad\verb|\shadebox{Red}|: exciting residues \item \textbf{I do not like the spacing between the feature lines. How can I change it?} Employ the respective space controlling command from the following list \verb|\ttopspace|, \verb|\topspace|, \verb|\bottomspace|, \verb|\bbottomspace|. Those are available since \TeX{}shade v1.5 (see manual). \item \textbf{How can I change gap and match symbols in diverse mode?} Since \TeX{}shade version 1.7, standard definitions for \verb|diverse| mode are: \begin{verbatim} \nomatchresidues{Black}{White}{lower}{up} \similarresidues{Black}{White}{lower}{up} \conservedresidues{Black}{White}{{.}}{up} \allmatchresidues{Black}{White}{{.}}{up} \gapchar{-} \end{verbatim} After calling \verb|\shadingmode{diverse}| these commands can be used to redefine the \verb|diverse| mode settings (mind the double curly braces around the dot-symbol!). \item \textbf{I want to rotate the alignment on the page. Is this possible?} Yes. Stefan Vogt has found this solution: use pdflscape.sty and activate it in the preamble with \verb|\usepackage{pdflscape}|. Then put your \TeX{}shade environment inside a \verb|landscape|-environment. You also need to adjust the number of residues per line with \verb|\residuesperline*{number}| to make them fill the rotated page. \medskip \qquad\vbox{% \verb|\begin{landscape}| \verb|\centering| \qquad \verb|\begin{texshade}{alignmentfile.MSF}| \qquad \verb|\residuesperline*{|\emph{number}\verb|}| \medskip \qquad \qquad \emph{further commands, if needed} \medskip \qquad \verb|\end{texshade}| \verb|\end{landscape}| } \item \textbf{I want use the \TeX{}shade and \TeX{}topo logos in my text. How?} Use the commands: \verb|\TeXshade| and \verb|\TeXtopo|. \end{enumerate} \end{document}