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