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

[techno_plume-coding at yahoo.com]

Hi Philip,

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

Thanks so much for your review and helpful comments/tips. I made the
changes + fixes 
you recommended. Below are a few points I'm still not sure on - any
input 
gratefully received. :)

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

Ooh, thanks. I'd forgotten to re-fix the file after editing the main
copy,
word-wrapping, & using 'Save As' to have the separate word-wrapped
version. If I
get time I might try creating a minimal test-case, for filing the line
breaks
problem as a bug in Kate.

Is there a KDE convention/policy for text-wrapping in user docs? 
I word-wrapped the file because I found it easier to read the Docbook
source (if
uploaded to the web for example). If I was, say, creating a new manual
for an
app maintained in KDE SVN - or editing an existing KDE-maintained
(application)
manual, is there any preference for using the word-wrap feature
(assuming end
result is valid XML) of whatever editor is being used?

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

That fixed it - thanks! :)

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

This was my mistake: The <copyright> information related to the
document but
began at the year the document was created and included each successive
year (to
2006), even though no changes were made in some of those years. I
corrected it
to only include <year> elements for each year in which the document was
changed
or added to [1]. 

In the "credits and license" section though, I've used 2002-2006
[Documentation
copyright © 2002-2006 Firstname Lastname (user AT example.com)] to
indicate
copyright is currently held by $name... and has been since 2002. No
changes were
made to the document other than those during 2002 and 2006; I felt it
looked
better though?

Elsewhere, rules seem inconsistent: The GNU/FSF pages, referring to
copyright
notices, stipulate dashes shouldn't be used to indicate date ranges and
years
need separating with commas; meanwhile,  the copyright.gov site simply
says the
year of first publication should be inserted (with the copyright valid
for 90
years or somesuch).
Is there a KDE "official" docs convention or policy for copyright
date(s),
*outside* of the bookinfo <copyright> notice? 

Also, the footer "Would you like to make a comment or contribute an
update to
this page? Send feedback to the KDE Docs Team", with the kde-docs
e-mail
address, appears on the generated pages. As far as I can see I'm not
using
generic entities (e.g. &update.documentation) that could cause this
though. Any
ideas?

Kind regards,

Richard.
-- 

[1] Per http://l10n.kde.org/docs//doc-primer/book-and-bookinfo.html