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

[Robert Knight]

------- You are receiving this mail because: -------
You are the assignee for the bug, or are watching the assignee.
         
http://bugs.kde.org/show_bug.cgi?id=88880         




------- Additional Comments From robertknight gmail com  2006-10-24 01:57 -------
> 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.