path: root/Master/texmf-dist/doc/latex/texshade/tsfaq.tex

\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}