[kde-doc-english] Building blocks

[T.C. Hollingsworth]

Hi Burkard!

On Fri, Jan 6, 2012 at 5:03 AM, Burkhard Lück <lueck at hube-lueck.de> wrote:
> 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.

I can redo these with 4.8 Beta 2 in a little bit.

> * 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?)

IMHO we should fold the seperate sonnet doc into building blocks.  It
makes more sense there now that it exists.  ;-)

The GCI task for it links to both sonnet and the section in kate that
has more info and suggests to merge that into one doc and expand upon
it.  That's the only outstanding buildingblocks task in there, IIRC.
There's ten more days left, so it might still get picked up.

> 7. Find and Replace
> 8. Choosing Fonts
> 9. Choosing Colors

These are done, just need to be converted to docbook.  I'll try and
knock at least one of these out in just a little bit.

> What should be added here too?
>
> * Breadcrumb location bar - used in dolphin/gwenview/file dialog etc

Do you just mean the screenshot mentioned in the FIXME you added?  Or
maybe a dolphinpart section too?

> * Common elements of config dialog ?

I thought about this, but I couldn't really find much in common
between common KDE apps config dialogs, except of course the
"Ok/Cancel" and the navigation bar on the left.

> * Stuff from kdelibs/kdoctools/customization/[lang]/entities/*docbook + rm it
> in kdelibs? definitely yes!

What do we do about the licensing ones though?  Most of those have to
be included with each doc to comply with the GFDL/GPL/etc.

> * 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!)

Didn't we have one of those a long time ago?  Any chance some could
dig it up from the SVN history?  It's probably a good idea to at least
have a look at what was done before, even if it's too outdated to
reuse.

> * Mini tutorials for typical + common tasks?
> * Your ideas here please...
>
> Some more questions to discuss:
>
> * Each topic/chapter in only one HTML page?

Methinks the current <chapter>s will need to be knocked down to
<sect1>s to properly organize it with all the new stuff we're adding,
so this will get taken care of automatically.  ;-)

> * 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?

IMHO we should stick w/kdelibs.  khelpcenter might be the only thing
that uses it now, but I don't think that will always be the case.
Maybe, for instance, Plasma Active might gain its own little help
viewer in the future, and want to be able to read this documentation?

> * 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?

If you ask me, it should go right at the top with the Plasma Manual.
Especially if we're adding tutorials and the like.  ;-)

Also, perhaps khelpcenter should open it you just click Help in
Kicker?  Or a short "Welcome to KDE" page that links to it
extensively?  IMHO that would be a lot better than the redundant list
of doc categories that appears right now.

> * 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.

If we wanted to go ahead and migrate these, we could work around this
in CMake and link to docs.kde.org when building against older kdelibs.

> 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'll go ahead and do this for kate/kwrite.  :-)

-T.C.