[kde-doc-english] Kpatience documentation update

[Burkhard Lück]

Hi Richard,

Am Donnerstag, 29. März 2007 18:52 schrieb techno_plume-coding at yahoo.com:
>
> A diff against KPatience index.docbook from trunk is attached for
> review.
>
Thanks a lot.

[snip]

> d) Credits on the 1st page were getting a little long. So I moved some
> to just the Contributors section. Hope this is okay?
>
I aggree, but may be Phil has an objection?

> == Things I am unsure of ==
>
> 1) This app also has a manpage, in the repository. Is there a policy
> user apps should have a manpage? Are these written by hand typically
> (or with something like Manedit), or somehow generated automatically
> from Docbook files through the autoconf/cmake scripts? Or by XSLT? I'm
> wondering if I should make a separate diff for the app's manpage, when
> amending a docbook manual.
>
There are a lot of *man.docbooks in the documentation (and I have translated 
many  to german), but I think they are useless, as they are not visible in 
khelpcenter and not visible as man pages.
Maybe Phil knows more?

> 2) Marked up a reference to a feature, like so:
> - especially if you use the undo feature
> + especially if you use the <guibutton>Undo</guibutton> feature
>
> In this case, the 'Undo' option is accessible through *both* the
> toolbar button - and - the edit menu. I wasn't sure which I should
> choose. When referring to a something like this, is that the correct
> markup? Previously there were no markup tags around that option.
>
I think there is no rule to use guimenuitem or guibutton, but a lot of markup 
(guibutton, guimenu, guisubmenu, guimenuiten, guilabel etc) makes it easy for 
me to detect possible errors in the documentation with my scripts.

> 3) Removed a section that read "Use of the menu is too easy to be
> described now.".
> I felt if it isn't described, there isn't much point in telling the
> user it wasn't going to be. :)
> Also, I later added a set of chapter tags, because that removal made it
> go from listing terminology to rules of Klondike, on the same page.
>
> _Is_ this appropriate, or should the menu options really be described?
> If so, Phil R., you mentioned on a kbackgammon bug that you had a
> script that might make  writing menu refs easier. Perhaps I could save
> some time using that, if I need to document the menu?
>
Better to describe the tasks and behaviour of the application than to write a 
menu desciption for this simple gui.
  
> 4) Since the doc (if approved+committed) is going into /trunk, should I
> change down the revisionnumber in the file to match the application
> version in KDE 3.5.5 ?
>
I will do that.

> 5) Adding newish contributor entities cause the XML check to choke.
> This is because they weren't present in KDE3. Say I add myself to the
> contribs section. Should I add the entity for myself, or just put my
> name and email address in manually to later be switched with the
> entity?
>
To use a contributors entity it has to be added to 
kdelibs/kdoctools//customization/entities/contributor.entities to make 
meinproc happy.
Putting in your name and email address in manually works without this, it can 
be later changed to an entity.

Burkhard Lück