[kde-doc-english] Building blocks

[Burkhard Lück]

Am Freitag, 6. Januar 2012, 23:21:11 schrieb 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.  ;-)
> 
Agreed

> 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?
> 
I have added some more comments and updated the dolphin docs (just wait for 
approval of Dolphins maintainer) and will cc this list when I commit.

That should explain better what I mean.

> > * 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.
> 
Yes, with the building blocks every app documentation will still have entities 
like  &FDLNotice; in the hearder and a chapter Credits and License with 
&underFDL;, &underGPL;, &underBSDLicense;, &underArtisticLicense; or 
&underX11License;.
These entities will pull in the license docbooks from 
kdoctools/customization/lang/entities. 
But the appendix Installation in the apps docbooks should be replaced by a 
link to building blocks
So help-menu.docbook, install-compile.docbook, install-intro.docbook can be 
removed from kdelibs in the future.

Note to self: 
Adapt *template.docbook* using building blocks

> > * 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.
> 
I have added Visuell dictionary from kde3 for reference to branches/work/doc

> > * 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.  ;-)
> 
Ok.

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

> > * 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.  ;-)
> 
Ok.

> 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.
> 
Makes sense.

> > * 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.
> 
That CMake magic is far beyond my knowledge

> > 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.  :-)
> 
I will add some stuff from this thread with comments to 
buildingblocks/index.docbooks so the information is at one central place.

Yuri, do you see a problem with the pdf's, which are one file compared to the 
splitted html's, if we use links to buildingblocks?

Thanks.

-- 
Burkhard Lück