[kde-doc-english] Building blocks

[Burkhard Lück]

Hi,

thanks to T.C. Hollingsworth and the Google Code-In 2011 participants we have 
the building blocks in branches/work/doc/buildingblocks/, see also 
http://lists.kde.org/?l=kde-i18n-doc&m=123461844907311&w=2

I watched the commits for the buildingblocks the last weeks and I am really 
impressed what we have already now, especially because I had to deal with some 
toolbar/shortcuts docs the last week. 
It would have been much easier for me if i just could have replaced outdated 
docbook content with a link to the building blocks.
So I am really interested to get that into kde asap, maybe into 4.8.1 already?

Some minor nitpicks from my pov:

* Screenshot should be taken with default setting of kde compiled from sources 
-> retake some screenshots with 4.8 (e.g. toolbars.png, shortcuts-set.png - 
yellow background for tooltipd in 4.8 here)
* Same for any other customizable stuff, use the default.
* Add action pngs e.g. for toolbar buttons or menu items?

What we have so far in building blocks:
1. Introduction
2. Common Menus
3. Customizing Toolbars
4. Opening and Saving Files
5. Using and Customizing Shortcuts

Just placeholders, but it makes a lot of sense to fill them with content:
6. Spelling Tools (relation to sonnet kcm doc?)
7. Find and Replace
8. Choosing Fonts
9. Choosing Colors

What should be added here too?

* Breadcrumb location bar - used in dolphin/gwenview/file dialog etc
* Common elements of config dialog ?
* Stuff from kdelibs/kdoctools/customization/[lang]/entities/*docbook + rm it 
in kdelibs? definitely yes!
* a11y.docbooks (from calligra/koffice) reviewed + updated to kde4?
* Navigation in documents (scrollbar context menu, automatic scrolling 
okular+konqueror browser)?
* Visuell dictionary (consistent wording in documentation + translation!)
* Mini tutorials for typical + common tasks?
* Your ideas here please...

Some more questions to discuss:

* Each topic/chapter in only one HTML page?
* Source module for building blocks docbooks?
  In kdelibs where most of the code for building blocks topics is? 
  Afaik these docbooks are currently only visible/accessible via khelpcenter
  in kde-runtime, via konqueror ("help:appname") in kdebase apps etc.
  So the docbooks could be just as well in kde-runtime?
* Visible in KHelpcenters navigation tree? As toplevel item? Name for it? 
  Or should it be invisible in KHC navigation and only accessible from
  application docs?
* kdelibs/kde-runtime version problem
  Most (?) apps in extragear/playground/calligra/koffice don't require the
  latest released version of kdelibs to build. So using links to building
  blocks from the last kde release for these docbooks will generate dead
  links, if the apps are build with an older kde version.

I'd encourage everybody working with docbooks:
* if you read a section which could be probably part of building blocks, 
please add a comment with link there
* if you remove a topic from application docbooks and replace it with a link 
to building blocks, please check if some of the stuff you remove could be 
usefull for improving the corresponding topic in building blocks (text 
snippets, pgns, a concept or an idea)
* if you find topics in apps docbooks which should be replaced with a link to 
building blocks currently written and not ready, please add a comment to that 
section in building blocks. That makes it easy to quickly the apps docbooks, 
if a building block section reday and uncommented/moved to the module.

-- 
Burkhard Lück