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

[Albert Astals Cid]

El Dijous, 1 de març de 2012, a les 23:09:07, Burkhard Lück va escriure:
> 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.

Right, but surely somewhere you have done a test to make sure buldingblocks 
actually works, no?

Can i have one of those files to see how it'd look like?

Albert - the stubborn

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