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

[Yuri Chornoivan]

написане Fri, 02 Mar 2012 00:09:07 +0200, Burkhard Lück  
<lueck at hube-lueck.de>:

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

For me, it will be good to have shortcuts building block for this section  
of Krecipes docs:

http://docs.kde.org/development/en/extragear-utils/krecipes/krecipes-preferences.html#configure-shortcuts

but it seems that the development of Krecipes is stale.

Best regards,
Yuri