[kde-doc-english] Kpatience documentation update

[techno_plume-coding at yahoo.com]

Hi.

A diff against KPatience index.docbook from trunk is attached for
review. 

It's mainly wording changes that I think make it sound clearer. Please
let me know if you think they don't! I can remove changes on request
and keep any there's a consensus we should keep. Some things I was
unsure about, so those questions are further down.

== List of Changes ==

a) Misc. wording/grammar/punctuation changes.
b) Removed description of 'Kings'. This patience game was removed
because of bugs (see bug #84819, comment #3).
 - Stephan Kulow said in IRC there is even a bug about Kings still
being mentioned. I was unable to find it; can anybody else? ... or
maybe he just meant it *was* a bug, albeit unfiled.
c) Swapped Golf and Spider around, so Golf appears first. Matches menu
in game more closely now.
d) Credits on the 1st page were getting a little long. So I moved some
to just the Contributors section. Hope this is okay?

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

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. 

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?

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 ?

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?

Thank you in advance for feedback,

Richard.

P.S http://www.kde.org/mailinglists/ (redirect from mail.kde.org) lists
kde-docbook. Does this need changing to kde-doc-english, or are both
lists still valid? The kde-docbook list is still open for posts.
-------------- next part --------------
An embedded and charset-unspecified text was scrubbed...
Name: diff.txt
Url: http://mail.kde.org/pipermail/kde-doc-english/attachments/20070329/09e70b4a/attachment.txt