Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdebase@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 433 insertions, 0 deletions

diff --git a/khelpcenter/DESIGN b/khelpcenter/DESIGN
new file mode 100644
index 000000000..003423f5a
--- /dev/null
+++ b/khelpcenter/DESIGN
@@ -0,0 +1,433 @@
+Design for a possible reimplementation of the KDE help center
+=============================================================
+
+Preludium
+---------
+This document presents an alternative design for a 'help center' applicaiton
+in KDE. Lines which start with a # are supposed to be thoughts I had while
+writing this, much like the stuff you write on the side of a page when reading
+a book.
+
+Lines starting with ## were added by my as further comments - Cornelius
+
+And I'll have the ### lines - Lauri
+
+General
+-------
+- main() instantiates a KHC::Application
+- KHC::Application() deals with parsing the commandline parameters and
+  instantiates a KHC::MainWindow
+- KHC::MainWindow creates the main UI, setting up actions, using a QSplitter
+  as it's mainwidget to separate a KHC::Navigator at the left from a KHC::View
+  at the right
+
+That's the simple part. ;-)
+
+## Apparently already done ;-)
+
+KHC::Navigator
+--------------
+
+KHC::Navigator inherits QTabWidget and provides, on two tabs, a
+KHC::ContentsTab object and a KHC::SearchTab object.
+
+## KHC::Navigator shouldn't inherit from QTabWidget. This limits flexibility.
+## It can create a QTabWidget instance as aggregate just as well.
+
+# I fear premature generalization ("We could need that bit of flexibility one
+# day), aggregation adds a level of indirection through a pointer variable as
+# well. I would prefer not making the system more complex as long as we cannot
+# predict changes which justify doing so.
+
+1.) KHC::ContentsTab provides the following entires:
+	- Welcome to KDE
+	- KDE user's manual
+	- KDE FAQ
+	- Contact information
+	- Supporting KDE
+
+# Should we create an extra item for these five and put them in there?
+# Something like "General KDE" or so? OTOH that makes them less visible, and
+# these are really ought to be seen. - Frerich
+
+## The items are ok, in principle, but we should have a look at the content of
+## the documents they point at. This document could benefit from some attention.
+
+### Yes, they would.  Also, there are license issues with one of them.
+### I'd personally like to do an entire rewrite of the User Manual,
+### without GPL encumbrance and sans the content that hasn't changed since
+### KDE 1.x days.  The odds of me getting this done before KDE 3.1, slim to fair.
+
+
+	- Application manuals
+	- Tutorials
+	- UNIX man pages
+	- UNIX info pages
+	- Glossary
+
+# Do we really need this "Tutorials" item at all? right now it holds only two
+# items, perhaps we can get rid of it. - Frerich
+
+## Yes, please.
+
+### There should be a "General" area, where documentation that isn't
+### attached directly to an application can go.  Tutorials might not be
+### the best name for it I agree, but there is now some further content to
+### add (the DCOP tutorial, for example, or any of the numerous tutorials
+### on the websites, documenting things that aren't in the handbooks.q
+
+# Alright, after some talk on IRC this structure evolved:
+#
+# - Tasks - contains short, three to four paragraph documents about how to
+#	        solve an everyday task, examples:
+#		Browsing the web
+#		Send and receive email
+#		How to view images
+#		Playing sound files
+#		Installing new KDE themes
+#		How to configure KDE fonts
+#		Getting in touch with KDE contributors
+#		Supporting the KDE team
+#
+# - Guides - slightly longer, Mini-HOWTO style guides (about three to four
+#            pages long, perhaps) which talk about tackling jobs which don't
+#			 occur very often, examples:
+### I don't know about limiting the length.  Some of these topics can stand
+### a much longer document, but one of the things that differentiates them 
+### from the references is that they are not specific to a single application, 
+### nor are they complete references in the manner of the "KDE User Guide"
+### Specificaly, the dcop tutorial we have is about 15 pages already, but if 
+### the user is interested in the topic, that isn't over much, and it's full of
+### examples
+#		How to debug KDE programs
+#		Sending useful KDE bug reports
+#		Extending KDE's service menus
+#		Taking advantage of KDE's DCOP facilities
+#		Creating panel applets
+#		Phrasing questions most effectively
+#
+# - References - references. :-)
+#		KDE API reference
+#		KDE application manuals
+#		Info pages
+#		Man pages
+#		FAQ
+#		User's manual
+#
+# - Glossary - same as always.
+#		- By topic
+#		- Alphabetically
+#
+# My primary argument for such a structure is that it resembles a
+# task-oriented interface much more closely than the simple list of
+# application manuals. Imagine a user new to KDE who has a fairly precise
+# description of what he's trying to do in mind (think "I want to view an
+# image file") but no idea what tool to use for the job. The current list of
+# application manuals requires the user to browse all the manuals which seem
+# relevant, searching for the information he seeks. A task-oriented list
+# solves that issue.
+# This effectively enables people new to KDE in less time to become productive
+# (a task-oriented list isn't so useful for peoplew ho are familiar with KDE's
+# applications, of course).
+# Implementation-wise, we should perhaps stop using a KListView and use a
+# KOffice-style component selection widget like koshell has at the left?
+
+The first five items are generated by KHC::Navigator itself and are direct
+links to KDE documentations. The work of generating each of the last four
+items is (with one exception) delegated to four helper classes, which inherit a
+'KHC::TreeBuilder' class which has the following interface:
+
+class KHC::TreeBuilder
+	virtual void build( KListViewItem *parent ) = 0;
+
+## What about the trees generated as children of the contents list view?
+
+# Oops, that's a typo, what you mean is what I originally intented: a
+# TreeBuilder should take a 'KListView' as it's parent, subclasses can then
+# overload that method (such as the KHC::TOCBuilder which will want to provide
+# a build( KListViewItem *parent ) method).
+
+# This concept of using a TreeBuilder baseclass might make it possible to turn
+# all the classes which use that interface into plugins. That way we could
+# e.g. have a ScrollKeeper plugin. - Frerich
+
+## What exactly do you mean by plugin? A shared library loaded at run time or
+## the desktop file based insertion of documents into the help center?
+
+# The former.
+
+The classes which inherit this interface are:
+	- KHC::ManualTreeBuilder: responsible for generating the tree below the
+	  "Application manuals" item
+	- KHC::TOCBuilder: responsible for generating a TOC tree below each of the
+	  manual trees items, so that you can choose Application
+	  Manuals->Editors->KWrite->Using KWrite->Menu bar transparently. This is
+	  the only builder which is not instantiated by KHC::ContentsTab but
+	  instead instantiated by KHC::ManualTreeBuilder
+	- KHC::TutorialTreeBuilder: responsible for generating the tree below the
+	  "Tutorials" item
+	- KHC::ManTreeBuilder: responsible for building the tree below the "UNIX
+	  man pages" item
+	- KHC::InfoTreeBuilder: responsible for building the tree below the "UNIX
+	  info pages" item
+	- KHC::GlossaryTreeBuilder: guess what
+
+## - KHC::ScrollkeeperTreeBuilder
+
+## It's certainly a good idea to move stuff like the info and man pages and
+## scrollkeeper support to its own classes. What  I consider as important is
+## that the concept of representing the documentation by desktop meta files is
+## used as far as possible. This makes the system very flexible and extandable.
+
+2.) KHC::SearchTab provides a widget which lets the search through all
+available help repositories, also defining some flags such as 'Search by
+regexp' or 'Search case sensitive'.
+
+# I think this means that we have to create a 'DataCollection' class which
+# gets inherited by all classes which are "searchable". DataCollections should
+# also be able to contains multiple child DataCollection, so that we have e.g.
+# one DataCollection per application manual, and one "Manuals" collection
+# which contains all the application manual collections.
+# We'd probably also need a DataCollection for the info pages and man pages.
+# And later, in the far future, we might extent this concept to web searches,
+# so that e.g. Google represents a DataCollection which we can query.
+# I'm not yet decided how to do that properly, perhaps using multiple
+# inheritance, so that each TOCBuilder is a DataCollection - naw, we'd rather
+# have a "TableOfContents" class which contains a TOCBuilder, and is a
+# datacollection? Hm, not sure.
+# In any case DataCollections should some sort of plugins, so that we can add
+# e.g. new web search interfaces lateron.
+# - Frerich
+
+## What you call a DataCollection is currently represented by the DocEntry
+## objects. Each DocEntry object represents a document or a collection of
+## documents. It has information about the name and description of the
+## document, the location and how it can be searched.
+##
+## Currently this information is based on URLs or file names and is optimized
+## to be used by scripts, e.g. CGI scripts. A little exception from this is
+## the htdig support where just a keyword "SearchMethod=htdig" is put in the
+## desktop file and the help center figures out how to perform that search by
+## using a special class. This could be extended to cover other search methods
+## like web searches or special search methods optimized for certain kind of
+## documents.
+
+# I just thought about it - isn't that a bit overkill for the web search
+# stuff? I just thought about it - all we need to do is to copy the .desktop
+# files (at least some of them, like the ones for google, yahoo and excite)
+# from the enhanced browsing thing and treat those as plugin .desktop files.
+# We could show them in a listview on the Search tab, each found search engine
+# being represented by a checkable listview item. So, we just let the user
+# enter a term, replace the \{@} placeholder in the URIs specified in the
+# selected .desktop files with that term, send out a request via KIO and show
+# the results in our KHTMLPart (after all KHC::View is a KHTMLPart already). A
+# problem with this: How to display the multiple HTML pages returned by the
+# selected search engines? Using a QSplitter to split multiple KHTMLParts?
+# Hmm... just wondered... perhaps we can work around that by not showing the
+# returned HTML data at all but rather use a XSLT script (that is, one XSLT
+# script per web search) which transforms the returned search results into a
+# common format - that way, we could also filter out duplicates and then
+# transform that filtered output into a nice, uniform HTML page. How about
+# that?
+
+# I like this idea very much, I just thought it and noticed you wrote this
+# down already. What I thought of was having a .desktop/.xslt file pair per
+# search engine: each .desktop file holds at least the name of the engine (for
+# the listview) and a search URI with a placeholder, just like in your scenario.
+# In additionl there could be a X-KHelpCenter-XSLT key which defines which .xslt
+# stylesheet to use for that particular search engine. We then query that search
+# engine by replacing the placeholder in the URI with whatever the user entered
+# and hand it to KIO. All the HTML returned by the various search engines gets
+# then transformed into a custom, intermediate, XML dialect, using the XSLT
+# stylesheets define in the .desktop files. Using that intermediate step we
+# can nicely drop duplicate hits, for example, or create a list of hits in the
+# sidebar (much like http://www.copernic.com does). After that, we can use
+# another XSLT stylesheet to transform that cleaned XML tree into HTML which
+# we then feed to our KHTMLView. Since we then have one unified output, we don't
+# need to worry about having multiple KHTMLParts, and it's also nice because
+# the user doesn't see which search engine returned which hit.
+
+# A problem with this would be that we cannot tell how a particular search
+# engine treats boolean expressions (e.g. some search engines use 'foo AND bar',
+# others use '+foo +bar', a third variation is '"foo bar"'). We thus cannot
+# replace the placeholder in the URI but first have to translate the syntax
+# entered by the user into a syntax which is appropriate for each single news
+# engine. Right now I don't know how we could do this with just a .desktop/.xslt
+# pair. We could always use fullblown C++ plugins which hold code which is able
+# to do that translation, but I would really prefer to stick with .desktop files
+# now since they're much easier to create.
+
+# Another thing which would speak in favor of C++ plugins: different search
+# engines support different features (like, google can search more than just the
+# web, and you can sometimes tell a search engine to list only results in a
+# certain language, or with a certain encoding), so it would be nice if we could
+# let the user access those features: through a dialog which has to be tailored
+# to the possibilities of the respective search engine. I wonder whether we
+# could have some sort of XML tree which defines how an UI should look like, and
+# then let KHelpCenter create a dialog using that XML markup, but that idea is
+# very vague right now.
+
+# Hmm, I just tried it and the XSLT idea didn't really take off: the problem
+# is that many HTML pages returned by Google, Yahoo & co. don't seem to be 
+# valid XML, which is why tools such as meinproc or xsltproc refuse to process
+# themm. :-/
+
+KHC::View
+---------
+KHC::View inherits KHTMLPart and does the actual job of showing some sort of
+document. Most importantly, it has a slot which passes it a KURL pointing to a
+document to show. KHC::View will invoke kio_help if necessary (if the URL's
+protocol == "help") by itself and otherwise use the plain URL.
+
+# TODO: Things I didn't really think about yet: the interface between the
+# navigator and the view. I think this has to be a bidirectional association
+# since the navigator can change the view (e.g. by clicking on a manual which
+# shows it in the view), but the view can also change the navigator (think of
+# clicking on a 'See also' link in the glossary which should also scroll to
+# the corresponding entry in the navigator).
+
+## That's a very important aspect. We should have one central place where all
+## document requests are processed and the necessary actions (like updating
+## the navigator, loading a new page, caching the search results, etc.) are
+## done.
+##
+## The TreeBuilder might need some interface to tell, if a certain URL exist
+## in their tree, to make it possible to select content entries which aren't
+## created yet, because they are only created on demand (like the application
+## manuals).
+
+# Very good idea. Perhaps I think iterating over a list of TreeBuilder
+# instances and doing something like 'if ((*it)->canHandle(url))
+# (*it)->selectItem(url)' which checks whether a TreeBuilder provides an item
+# which corresponds to an URL (hmm, this makes me think, TreeBuilder is a bad
+# name. Perhaps just 'Tree'?) and selects it (using
+# QListView::ensureItemVisible() or so) if requested. This probably implies.
+# that a TreeBuilder needs an internal QMap<KURL, QListViewItem *>.
+
+# Also, the whole search engine needs more thought, that DataCollection idea
+# seems promising to me but I'm not yet decided on how to do it properly.
+
+## See above. We already have something which isn't too bad, I think.
+
+# I just thought about this a bit, I think KHC::MainWindow should act as the
+# interface between KHC::Navigator and KHC::View.
+
+## I would prefer to have an extra class which does no GUI stuff, but passes
+## URL requests around, does the needed processing and stores data, if needed
+## (e.g. caching search results).
+
+# Agreed.
+
+## One very important aspect of the help center is that it has to be fast. It's
+## not acceptable to wait several seconds after clicking on the Help menu of an
+## application. We should think about that. Perhaps we can do some tricks like
+## showing the main window before creating the other widgets and processing data
+## or something similar. We could also think about creating more stuff only on
+## demand.
+
+# My perception is that filling the Navigator's listview takes a significant
+# amount of time, just like setting up the KHTML view (loading the stylesheet,
+# showing the welcome page). We could easily do taht in the background - show
+# the mainwindow, then tell the TreeBuilders to start populating (using a
+# QTimer with a timeout of 0, for a snappy GUI). Since they're collapsed at
+# the start, the users won't even notice (and we can "fake" that they're
+# already populated by calling setExpandable(true) for all of them (or letting
+# them do that themselves) at the start.
+
+## Finally a crazy idea: Wouldn't it be cool, if we would make the manuals more
+## interactive. So when you read about a certain menu or a certain dialog of an
+## application you can click on a link in the manual and the menu or dialog gets
+## opened in the real application, or some widgets get highlghted in the real
+## application. Such a feature could also be used to create interactive
+## tutorials, where you have a small helpcenter window and the application next
+## to each other on the screen and you can go through the tutorial step by step
+## and practice with the real application while reading the instructions.
+## With the help of DCOP it shouldn't be too hard to implement such an
+## interactive help system. Maybe it's even possible to do it in a general way
+## in the libs, so that application authors don't have to think about that
+## feature.
+
+# Hmm, that's an interesting idea. That takes KHelpCenter way beyond what it's
+# currently doing. I can imagine this: we introduce a virtual "dcop" protocol,
+# so that e.g. <ulink url="dcop:/kfortune/KFortuneIface/nextFortune"/>
+# represents the DCOP call 'dcop kfortune KFortuneIface nextfortune'.
+# KHelpCenter catches that protocol (oh dear, a lot of special cases with
+# gloss, info etc. already - guess another one won't hurt). That looks like a
+# good way for encapsulating DCOP calls.
+# Now, the problem is - the application has to provide a dedicated
+# "documentation" DCOP interface for this, with lots of calls for highlighting
+# the various widgets (hm, this probably means taht we can skip the first two
+# parts in our 'dcop' URL syntax, the application is known anyway, and the
+# interface is hardcoded in KHelpCenter).
+# So, what could happen is this: We have a piece of HTML in the documentation
+# for our SuperApp application which goes like 'The
+# <a href="dcop:highlightConnectButton">button labelled Connect</a> makes
+# SuperApp establish a connection.' - the user clicks on that link,
+# KHelpCenter catches a dcop: URL, checks whether SuperApp has already been
+# started. If not, it starts a SuperApp process and does the dcop call 'dcop
+# SuperApp DocIface highlightConnectButton' and SuperApp starts highlighting
+# that connect button. The thing is that this requires a lot of work on the
+# application side. The idea is very cool, but we'd have to think about
+# outsourceing parts of that functionality, either to KHelpCenter, or to
+# kdelibs.
+
+## And another idea: The WhatsThis help texts describe all widgets of an
+## application (provided that the texts are set by the developers). Currently
+## they aren't accessible very easily. You have to go to a special mode and
+## can then click on one widget after another to get the help, if there is one.
+## There is no visual indication which widgets have help and which not. But the
+## application knows about the WhatsThis helps. Perhaps it's possible to use
+## the Qt object inspection stuff to extract all the texts and put them on an
+## automatically generated screenshot of the corresponding dialog and put this
+## graphic into the docs. Maybe it's even possible to do this at run-time and
+## decorate dialogs with all WhatsThis helps at once, if the user triggers this
+## mode.
+
+# Hmm yes, that should be possible. Take the toplevel widget, use
+# QObject::children() and iterate over all children, use QToolTip::textFor() to
+# check whether the given qwidget has a tooltip and if so, use QToolTip::tip()
+# to show the tooltip.
+# One could probably add a standard dcop call to KMainWindow, like
+# "showAllToolTips". KSnapShot could get a QCheckBox "Show all tooltips", and
+# if that box is checked it tells the selected window to show all it's
+# tooltips via that DCOP call right before it does the snapshot. The thing is
+# - is it possible to map the WinID of the window the user clicked on to
+# the process name we should send your DCOP call to?
+
+## One thing we should also keep in mind is that it might be useful to provide
+## the help center as a component. FOr example KDevelop has a very similar
+## thing. It would be much nicer, if it could reuse the KHelpcenter code. This
+## would probbaly also mean to at a DoxygenTreeBuilder or something similar.
+
+# That probably implies that instead of a QSplitter which holds the Navigator
+# and the View, we'd have a KHC::MainWidget KPart which in turn aggregates the
+# splitter. The DoxygenTreeBuilder sounds like a reason to make TreeBuilders
+# real plugins, with dynamically loaded libraries, so that KDevelop or other
+# "IDE"-like applications (perhaps a KOffice help system?) can have their
+# customized tree builders.
+
+Font Configuration
+------------------
+
+### Many bug reports on KHelpCenter not honouring KHTML font settings,
+### which is odd, because the stylesheet is intentionally loose,
+### specifying only "sans-serif" as the font face.
+
+### Ideas to fix: 
+
+### Help pages already make heavy use of the cascading feature of CSS, we
+### ought to be able to leverage that by writing to perhaps the
+### kde-localized.css file or a copy of it in $KDEHOME.  There is already
+### code in KControl to create a user CSS stylesheet, and we probably only
+### need to configure the size and the face for KHC.
+
+### Or, fix whatever is the reason KHC doesn't follow the rules.  It could
+### be encoding related, the help pages specify utf-8 as the encoding, and
+### previous incarnations of the KHTML settings allowed fonts set on a 
+### per-encoding basis (at which time, this was apparently working, the bug 
+### reports dropped off, and only returned post KDE 3.0
+
+# FWIW I added a simple font configuration facility a while back, which should
+# IMHO be sufficient for the vast majority of users.
+
+// vim:tw=78