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
