[kde-doc-english] Building blocks ready to go into master?

[Burkhard Lück]

Am Mittwoch, 29. Februar 2012, 23:21:13 schrieb Albert Astals Cid:
> El Dimarts, 28 de febrer de 2012, a les 21:14:06, T.C. Hollingsworth va
> 
> escriure:
> > On Mon, Feb 27, 2012 at 4:37 PM, Albert Astals Cid <aacid at kde.org> wrote:
> > > El Dilluns, 27 de febrer de 2012, a les 22:57:26, Burkhard Lück va
> 
> escriure:
> > >> Am Sonntag, 26. Februar 2012, 23:23:23 schrieb Albert Astals Cid:
> > >> > Sorry for the top posting :-)
> > >> > 
> > >> > One question about "Building blocks", i think you told me the idea
> > >> > was that
> > >> > "Building blocks" would be a separate manual, meaning that the
> > >> > Okular manual (using Okular as example here) would no longer have
> > >> > the information
> > >> > of how the "File" menu works, but instead if would have a link to
> > >> > the "Building blocks" manual that speaks of the "File" menu.
> > >> > 
> > >> > Is this right or did I misunderstood you?
> > >> 
> > >> Somehow you misunderstood me resp. the use case for the "Building
> > >> blocks".
> > >> 
> > >> Using the okular docs as example, there are some "File" menu items
> > >> special
> > >> to Okular.
> > >> Of course these items (Import PostScript as PDF, Save As, Save Copy
> > >> As, Print Preview, Properties, Embedded Files, Export As etc.) will
> > >> be in the Okular docs.
> > >> And if there are other items in the Okular "File" menu with more infos
> > >> as in the current "Building blocks" documentation ("File → Open" for
> > >> example) and if these infos are valid for other applications as well,
> > >> these docs will be used to extend/update the building blocks
> > >> documantation.
> > >> 
> > >> A better example where the building blocks documentation will simply
> > >> replace application docs is the Help menu or Settings → Configure
> > >> Shortcuts or Settings → Configure Toolbars.
> > >> This documentation is shared and valid for nearly all other
> > >> KDE-Applications, so it makes no sense to have it in a lot of
> > >> docbooks.
> > > 
> > > I disagree, it makes sense from the point of view of being complete,
> > > i.e. I
> > > want the user to be able to understand all Okular menus just reading
> > > the Okular documentation. Will that be possible using "Building
> > > Blocks"? Or will he need to open a second documentation?
> > 
> > Well, for Kate/KWrite I probably won't drop the Settings menu, since
> > there's some katepart-specific stuff in there too and sending them to
> > buildingblocks for three entries is kind of silly IMHO.  Okular has a
> > bunch of it's own stuff in there too, so you'll probably want to do
> > the same.
> > 
> > I'll definitely just link to buildingblocks for the Help menu, though.
> > 
> >  IMHO, if users actually need to read the docs for the help menu they
> > 
> > would probably benefit greatly from a pointer to the other fundamental
> > stuff in buildingblocks anyway.
> > 
> > Also, we have shiny new documentation for Configure Shortcuts/Toolbars
> > and other comman dialogs.  Those aren't documented at all ATM, so
> > while you might want to keep short blurbs about those entries in the
> > Okular doc, linking to the buildingblocks section that actually
> > explains how to use them is a definite win.
> 
> To be honest i'm still not sure of how it works (yes i can be that
> difficult sometimes :D). Do we have a document that uses BuildingBlocks
> already? That'd be the easy way for me to understand it :-)
> 
Of course we have no documentation using buildingblocks so far, because 
BuildingBlocks are only in branches/work, not in trunk/master or a branch.

The first user of buildingblocks will be kdegraphics/kcolorchooser, but that is 
just a X-DocPath in kcolorchooser.desktop pointing to 
buildingblocks/tasks.docbook id "colors" and not a typical use case.

The docs in kde main modules are quite up to date regarding the info in 
buildingblocks, but less complete, any ideas for an application doc in 
extragear/playground with outdated infos about the common stuff documented in 
buildingblocks?

-- 
Burkhard Lück