[Konsole-devel] [Bug 88880] please document control characters for title bar and tab text

[lars.doelle at on-line.de]

> 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