[kde-doc-english] Building blocks

[T.C. Hollingsworth]

On Sat, Jan 14, 2012 at 2:56 AM, Burkhard Lück <lueck at hube-lueck.de> wrote:
> 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.

Do the new screenshots I took look okay?

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

This has been submitted.  I'll have it converted soon (this weekend probably).

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

Saw this.  I'll take a look at it soon (also this weekend probably;
busy week for me ;-).

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

Ok.

> 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

Thanks!

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

Basically, we'd edit the docbooks we want to do this for to pull in a
"buildingblocks.entities" file,  which defines a
&buildingblocks-prefix; entity that is populated by CMake based on the
kdelibs version, either to "help:/buildingblocks/" or
"http://docs.kde.org/stable/en/kdelibs/buildingblocks/".  I
half-tested this before I got busy with life and it seemed to work
okay.

The CMake part is easy, the docbook/scripty part, not so much.  ;-)
One problem I see is that docs being built outside of CMake (e.g.
writers, translators, scripty maybe) will need to create the
buildingblocks.entities file themselves.  (In fact, the whole reason
I'm suggesting to create a separate entities file is because I think
trying to define the entity directly in index.docbook would *really*
break scripty.)  I also know little about how the translated docs work
so this might not do anything for them.

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

-T.C.