Am Dienstag, 23. September 2014, 19:53:09 schrieb T.C. Hollingsworth: > On Tue, Sep 16, 2014 at 11:20 AM, Luigi Toscano > > <luigi.toscano at tiscali.it> wrote: > > Moreover, the contents of Fundamentals talks about both components and > > behaviors which are provided by different sources: Qt, various frameworks > > or directly Plasma. That's why I'm asking about rethinking and splitting > > fundamentals. Some sections should be moved down (some even here in > > KDocTools). But I really need help from you who wrote it for this. > Let's rethink it then. :-) > > Currently we have two manuals that provide a basic introduction to our > applications and workspaces. There's Fundamentals, which covers basic > stuff like widgets, file dialogs, installation, etc. and is intended > to be useful for people using Plasma as well as other platforms. And > there's the Plasma handbook, which just covers the desktop shell. > > People not using KDE should really refer to their desktop's > documentation for much of that sort of stuff, because e.g. KDE > applications running in GNOME will be rendered with GTK and get GTK > file dialogs, so that part of fundamentals is useless to them already. > (Not to mention the type of person who really runs GNOME, and runs KDE > applications on top of it, is really not the type of person who is > going to read documentation like Fundamentals anyway. ;-) And, IMHO > people using KDE shouldn't have to look between two manuals for stuff > implemented on the library side vs. stuff implemented in the desktop > shell, because most of them really don't understand/care about this > difference. > > For these reasons, I really don't think the fundamentals/plasma split > is really that useful to our users. So IMHO we should do away with > it. > > Let's split off unique KDE Frameworks features like Custom Shortcuts > off into their own little DocBook <article>s shipped along with the > framework, so any application depending on such frameworks can safely > and easily link to the documentation for using those features. The > remainder should be merged with the existing Plasma handbook that > covers solely the desktop shell into one grand unified Plasma Handbook > that covers everything you need to know to use Plasma the Workspace. > > Fundamentals would be split as follows: > > 1. Introduction -> N/A (new guides will get new ones) > 2. Installing the KDE Software Collection -> Plasma > 3. Finding Your Way Around -> Plasma > A Visual Dictionary > Common Menus > Common Keyboard Shortcuts > 4. Common Tasks > Navigating Documents -> Plasma > Opening and Saving Files -> Plasma > Check Spelling -> sonnet* > Find and Replace -> ktextwidgets > Choosing Fonts -> kwidgetsaddons* > Choosing Colors -> Plasma (this is done with pure Qt in KF5) > 5. Customizing KDE Software > Customizing Toolbars -> kxmlgui > Using and Customizing Shortcuts -> kxmlgui > 6. Credits and License -> eveywhere ;-) > > *These are Tier 1 Frameworks and cannot depend on KDocTools. So we'd > either need to knock them down or figure out something else to do with > their documentation (ship them in KDocTools?). :-( > > Comments/suggestions/criticism welcome as always. :-) > I am fine with merging the content of plasma handbook and fundamentals, but fail to see the benefits of this split.
>From a technical pov I agree with your proposal, documentation should be in the same repo as the corresponding code, e.g Toolbars/Shortcuts -> kxmlgui But looking from a documentation readers pov all docbooks are only usable via the help ioslave, and the help ioslave is afaik only used and usable in khelpcenter and konqueror. That means a user without khelpcenter or konquerer can not display any docbook help. So the repo with khelpcenter code is the my preferred location for this documentation. Thanks -- Burkhard L?ck
