diff options
Diffstat (limited to 'khelpcenter/DESIGN')
| -rw-r--r-- | khelpcenter/DESIGN | 433 |
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 |