
Xterm-Title mini-HOWTO                     Winfried Trümper <winni@xpilot.org>
----------------------                     Version 1.3             22 Oct 1996



"Isn't this boring?" most people will ask. I just do a

	xterm -T "Rent this place for your advertisement" \
	      -n "The name of the icon could be yours, too" &


to place arbitary strings into the titlebar of the xterm. Ok, that's
right but you may want to change it after startup ...

To change the title while the xterm is running, you just send a
special sequence of characters to it. Such a special sequence is named
"escape sequence" and usally not displayed on the screen but causing
certain actions. 
For example, if you press <ctrl-v> <Esc> <c> <Enter>, your xterm
should reset (e.g. clear the screen). The <ctrl-v> and <enter> are only
needed to make the bash printing the actual sequence <esc> <c>.

Note that I refer to keystrokes by enclosing the label of that key
by <>.

Now, to change the titlebar and icon of the xterm you just use the
escape-sequences

        <esc> <]> <2> <;>	sets a new title
        <esc> <]> <1> <;>	sets a new icon-name


To send those sequences to the xterm, we no longer type them on the
command-line, but we use the program `echo':

	echo -e "\033]2; You can rent this place for a commercial. \007"

As you might have guessed `\033' is the octal representation of the
escape-character and '-e' enables this syntax.
You must terminate the string that should show up in the title with a
<ctrl-g> aka "the lovely beep".


One useful application for those features is to move the information
usally found in the command-prompt into the xterm-title: lets assume
you have defined you command-prompt as

        export PS1='\u@\h:\w> '

so it looks like

        winni@FeilSurf:~/mail>
        
What happens, if you change to the directory "/afs/rrz.uni-koeln.de
/pub/packages/linux/kernel/v2.0"? Right, the prompt gets longer and
leaves less space for typing commands:

        winni@FeilSurf:/afs/rrz.uni-koeln.de/pub/packages/linux/kernel/v2.0>


This is odd. But - if you put this information into the title-bar,
everything is fine:

        export PS1='\033]2; \u@\h:\w \007bash> '

The command above echoes the needed escape-sequences and leaves as
prompt:

        bash> _


Unfortunatly the maximum length of the value of PS1 is limited to
somewhat around 60 (?) chars and so it's not suited in all
cases. Another  idea is to re-define shell-builtins like "cd" to echo
the escape-sequences but this has the ugly side-effect of a nervous
title-bar when running shell-scripts ... (yes, every "cd" changes the
title).

The most reliable approach seems to me the usage of the
environment-variable "PROMPT_COMMAND". The content of this variable is
executed after a program has finished and before the bash prompts at
you again. The following is very useful in a networked environment
with many xterms opened:

        export PROMPT_COMMAND='echo -ne "\033]2;$LOGNAME@$HOST     Directory: $PWD\007\033]1;$LOGNAME@$HOST\007"'


... especially when you look at the "window list" of your
window-manager. And to make it perfect, we only set this variable when
we are in an xterm:

        if [ "$TERM" = "xterm" -o "$TERM" = "xterm-color" -o \
             "$TERM" = "rxvt"  -o "$TERM" = "vs100" ]
        then
          PS1='bash> '
          PS2='bash>> '
          PS3='bash>>> '
          export PROMPT_COMMAND='echo -ne "\033]2;$LOGNAME@$HOST     Directory: $PWD\007\033]1;$LOGNAME@$HOST\007"'
        fi


Note that the prompt "bash> " makes the command-line somewhat more
consistent because many programs put their name in the front (gnuplot,
ncftp, gap, kash, ...).
But even this has the drawback of messing up some programs that spawn
up sub-shells like "ytalk". If you get bitten by it, issue 

        unset PROMPT_COMMAND



Happy Linuxing
-Winfried Trümper <winni@xpilot.org>


CREDITS:

    Ville Voutilainen <vvoutila@raita.oulu.fi>
        Noticed the ;s are missing from the escape-sequences in the
        "first half" of the document.


PS:
---

Don't ever use raw "escape-sequences" in any of your programs! Let the
program »tput« choose the right sequences from the environment-variable
'$TERM' plus your symbolic description of the action to perform. See
tput(1) for details (enter »man 1 tput« at the command prompt).

The escape-sequences for the xterm-titlebar are the only exception from
the above rule.


PS2:
----

If you want to know the "escape-sequences" an xterms understand, then have
a look at the sources for »rxvt«, it contains the file "xterm.seq" in the
"doc/"-directory.

