[kde-doc-english] Building blocks

[Burkhard Lück]

Am Freitag, 6. Januar 2012, 13:03:22 schrieb 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.

I would really like to get some more input on this, especially if and when the  
buildingblocks are ready to get into one of the kde main modules.

The buildingblocks docbooks don't need to be perfect, just better than the 
corresponding parts in the individual application docbooks.

Thanks T.C. for your comments, I'll answer your mail separately.

We need to explain how we want to use the buildingblocks to the translation 
teams and give them time to translate them, before we can start to use them 
everywhere.

That's why I feel to be in in a hurry and why I am pushing this issue here.

Thanks.

-- 
Burkhard Lück