[kde-doc-english] Docbook manual review - 3rd-party apps?

[Philip Rodrigues]

Hi Richard,
Here are some things I noticed. Some are just suggestions, and some are things 
which we'd change for "official" documentation (ie, if it was maintained in 
KDE SVN).

BTW, Kate's wordwrapping put line breaks in some closing tags, which made the 
file invalid - easy enough to change, but worth being aware of next time (and 
maybe even a bug in kate?). Because of this, my line numbers (taken from the 
wordwrapped file) might be off by one or two

I'd get rid of all the placeholder comments from the template file - they just 
get in the way in a proper document.

<copyright> is the copyright for the document, rather than the app. I'm not 
sure whether the years you've put apply to the app or the document. You can 
add copyright info for the app in the "credits and license" section.

line 110: "Friends' page". Should be "Friends page" or "Friends' pages" I 
guess.

I like the epigraph :-).

You can use the automatically generated Help menu documentation by defining 
<!ENTITY kappname "&kluje;"> in the doc header, and then putting 
&help.menu.documentation; in the Help menu <section>.

In the keyboard shortcuts section, strictly you should use something like 
<variablelist> or <informaltable>, since the "shortcut"->"description" has a 
logical connection. It's not a big deal though.

line 284: I guess you mean --help, rather than -help (two dashes). There's 
some inconsistent use of "command line" versus "command-line" in the section 
too. I can't remember whether we have a preferred form for that one, so just 
pick your favourite and go with it.

line 376: $PATH is a bad thing to call your <replaceable> item, since it's a 
well-known environment variable used by the shell. I'd go with just 
<replaceable>installdir</> or something.

Other than that, it looks fine. Nice work on the DocBook! You even used some 
tags I didn't know about :-)

Regards,
Philip

-- 
KDE Documentation Team: http://i18n.kde.org/doc
KDE Documentation Online: http://docs.kde.org
-------------- 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/20060802/ddf2089a/attachment.sig