[kde-doc-english] Kpatience documentation update

[Philip Rodrigues]

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

Manpages never quite got off the ground in our repository, although it should be 
quite easy to generate them. For example, you can generate the nroff (or whatever
it's called) for the kpat manpage with:
meinproc --stylesheet $(kde-config --prefix)/share/apps/ksgmltools2/docbook/xsl/manpages/docbook.xsl man-kpat.6.docbook 

The problem is that (at least in KDE 3) this isn't included in the build system, so the
man pages aren't generated automatically at compile time. I did discuss this with Allen
a month or three ago, but I don't remember what conclusions we came to. Allen?

> 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'd say just use either, if there's nothing in the context to signify which 
to use. I might take a look at <action> for this sort of thing, but I'm not sure 
offhand.

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

Agreed :-).

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

If there's nothing interesting in the menus, then it doesn't really need to be described.
If there's anything there whose function could be hard to understand, or ambiguous,
I think it's worth having a menu reference.

My script -- which I'm afraid I've lost :-( -- was just a simple few lines of python which 
would turn a text file which looks something like this:
File
	Open
	Quit
Help
	KFoo Handbook
	About KFoo
into some docbook representinga menu just like that.
	
> 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 ?

Not too important either way, since we don't know the application version number 
for KDE 4 yet.

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

For trunk, add the entity, since anyone building trunk is expected to keep kdelibs 
up-to-date too.

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

Hm, looking at the archives, it does seem like kde-docbook is pretty dead. I guess we
should consider closing it down, or at least finding out whether anyone is reading it.

Regards,
Philip
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 187 bytes
Desc: not available
Url : http://mail.kde.org/pipermail/kde-doc-english/attachments/20070402/d74700e9/attachment.sig