A "Tip of the Day" exist for what you wants.

What does this tip of the day say?

Here it is:

...that you can let Konsole set the current directory as the session name? For Bash, put 'export PS1=$PS1"\[\e]30;\H:\w\a\]"' in your ~/.bashrc . 

...that if you let your shell pass the current directory to Konsole within the prompt variable, e.g. for Bash with 'export PS1=$PS1"\[\e]31;\w\a\]"' in your ~/.bashrc, then Konsole can bookmark it, and session management will remember your current working directory on non-Linux systems too? 

A tip of the day is not an obvious place to look for such documentation though.  I personally don't think "Tip of the Day" should be enabled by default in Konsole either - although I need to do some research on that.

Part of the problem is, that what was supposed to be the technical
documentation is buried deep in a subdirectory of the sources.

See konsole/doc/VT100/techref.html

The technical reference was hooked into the "Help" menu, originally,
today it is not even distributed with the binaries (at least in debian).

It never got a final redaction, is not maintained, and slightly out of sync.
I originally planned to make a mechanism to keep the documentation of
the supported codes in sync with the ones actually recognised, which is
one of the reasons, why this particular subdirectory appears like a
complete mess.

To some degree such a reference is vital, partially, because there
is no real standard (beside perhaps ECMA), and some extensions
and modifications by various implementations. Terminal codes are
a misery in that each terminal is a bit different in respects of which
codes it accepts and the konsole is an exception here only in that
it did not add its own private codes.

The konsole merges material from VT100/VT220/Linux console and xterm
collected such that it is pretty compatible with all of them in many respects.
Parts of the documentation was an attempt to track the individual (sub)codes
back to its origin to allow a compatibility statement.

Now not having such a list is indeed anything but a good style especially
in the light of the compatibility problems inherent in this particular trade.

The codes, Slava asks for, originate from xterm and are documented there.
This documentation (of the xterm codes) is also not distributed with the
binaries but can be found with the xterm sources in a file named "ctlseqs.ms"
(which can be typeset e.g. to a postscript file using nroff/groff).

> The technical reference was hooked into the "Help" menu, originally,
> today it is not even distributed with the binaries (at least in debian). 

I suggest that we provide a small subset of that in the actual docbook help - covering the most useful features for end-users, and then provide a more comprehensive reference on konsole.kde.org

> I suggest that we provide a small subset of that in the actual docbook help
> - covering the most useful features for end-users, and then provide a more
> comprehensive reference on konsole.kde.org 


I believe it would be enough to simply include the techref into the 'install' ending
in /usr/share/doc/konsole, together with a statement that the techref is out of date
and needs to be reorganised.

The original plan to bind the documentation to the code was to generate the
body of TEmuvt102::tau from the documentation or let the body of tau become
in a likely generated table. See konsole/doc/VT100/Table.Codes.

Another source is TEScreen, where (most of) the routines used in tau finally
end, often having a one-to-one relation to some esc code. Thus one could
use some scripting putting together the documentation distributed in the
various routines.

The tokenizer would need to be described separately.

At least this was the latest plan. Prior to that, the techref (and the related material
in doc/VT100) was to sort apart the codes from various emulations and to balance
them.

The central routine is "genDocument" which produces "techref.html" from everything
else in this directory. Clearly, all the material in doc/VT100 is a very bad hack and
absolutely unmaintainable because it uses a weird mixture of tools and models. Let's
say its a kind of laboratory structure.

Neverthenless, i hold the idea to intimately link the documentation of the escape
codes with its interpretation good. It was simply never fully implemented, though,
and bringing it as far as it right now is was quite some work. I estimate 2 weeks
of work at least to finalise it or to bring it at least to a maintainable and useful
state. I hesitate to offer to pick this part up again, since i have very few spared
time.

But clearly, this and a decent documentation of the konsole's core would definitely
improve the konsole quite a bit, making its maintainace and adaption more simple.
The work would best be done in a review of the konsole's core, straightening the
code and sorting apart stuff that went into wrong files. Some newer material became
badly layered over time, and is completely undocumented. In particular, the XIM
material badly needs to be sorted apart from the displaying operation. The marking
material needs a review.

Anyway, i can take the technical reference / program documentation onto my agenda.
I could work up from Screen/Emulation (which are referenced in the techref) and later
pave ways into the Widget. It will take some time and i cannot guarantee to actually
make it.

For now, best thing is perhaps to be clear, that this is an open issue and this could be
clearly stated with the work-around proposed above.

-lars

> I believe it would be enough to simply include the techref into 
> the 'install' ending in /usr/share/doc/konsole, together with a 
> statement that the techref is out of date and needs to be reorganised. 

There are two groups of users who I see as needing documentation on Konsole's terminal features:

- Power users, sysadmins and developers who write small scripts to help automate common tasks and customise their terminal environment
- Developers of terminal applications 

Including the techref doesn't help the first group - who are the subject of this bug report, because it will be hard for them to find the relevant parts (producing coloured output, setting window titles, setting icon titles etc.).  It may not be obvious where this documentation is either.
I personally fall into this first catagory of user, and would expect to find the documentation somewhere in the Help manual. 
This documentation can be quite short (no more than a few screens) and would ideally include a few example scripts which users can copy and paste into Konsole and observe the effects. 

Including the techref does help the second group, although since an application developer will probably want to write an application that works well in all terminals, it would probably be better to point them to http://vt100.net - which contains an 'official' definition of the terminal which Konsole is supposed to emulate, and then only document Konsole's specific extensions separately.


> The work would best be done in a review of the konsole's core, 
> straightening the code and sorting apart stuff that went into wrong files

At the moment I am trying to do this incrementally, by adding doxygen comments to the classes and using more descriptive variable names and helpful comments as I make changes in the backend.  

It is possible to spent a lot of time reorganising the code while not actually delivering improvements to the user.

> Anyway, i can take the technical reference / program documentation 
> onto my agenda. I could work up from Screen/Emulation (which are 
> referenced in the techref) and later pave ways into the Widget.

I think it would be best to do documentation updates nearer the release, when Konsole is feature-complete for KDE 4.

hmm, i don't know if this feature has been documented, already.
but the feature itself is sure missing in Konsole from KDE4

please put this back

see bug #179142 for details