[kde-doc-english] Re: Kate vi-mode doc formatting

[Burkhard Lück]

Am Dienstag, 28. Juni 2011, um 08:56:52 schrieb T.C. Hollingsworth:
> I've taken a first stab at reformatting Kate's vi mode documentation
> appropriately.  My DocBook isn't that strong so please let me know if
> I did anything wrong.
> 
Looks already quite ok.

Your patch is a diff against 
'svn co svn://anonsvn.kde.org/home/kde/branches/work/doc/kate'

A few issues:

* Use entities from:
kdelibs/kdoctools/customization/entities/general.entities
and 
kdelibs/kdoctools/customization/en/user.entities
if applicable.

Kate -> &kate;
<keysym>Ctrl</keysym> -> &Ctrl;
(btw Ctrl is a keycap, cause the key is labelled Ctrl)
“foo“ -> <quote>foo</quote>
Using &Ctrl; and <quote> makes translation much easier, translators simply 
press Ctrl+T in Lokalize and at build time that is automatically properly 
translated (e.g. in german to Strg and „foo“)
 
<keycap>c i</keycap> -> either <keycap>c</keycap> <keycap>i</keycap> (press c 
then i) or <keycombo><keycap>c</keycap><keycap>i</keycap></keycombo>

Add link here:
in the Vim documentation -> 
in the <ulink url="http://vimdoc.sourceforge.net/htmldoc/change.html#Y">Vim 
documentation</ulink>

listitems with or without period at the end? But keep it consistent.

Do we need entities for Vi / Vim defined in the docbook header or 
general.entities?

Please wrap lines around columns 75, diff is easier to read than.

I'd prefer to have the commands in a table, the generated html output is way 
shorter and seems better readable.
A Table would be even suitable with three rows. key + command name + 
description.
Comments on variablelist vs informaltable please.

> Next I'll work on filling some of the placeholder text for the
> commands with real info.  I was hoping I could borrow some of vim's
> documentation but unfortunately it's under the OPL, which is
> FDL-incompatible according to the FSF.  :-(

Yes, kde documentation has to be FDL versions 1.2, see  
http://techbase.kde.org/Policies/Licensing_Policy for details.

I'd like to get this into master as soon as scripty is switched to trunk-
master and stable-4.7 (around June 30) and then backport to 4.7 in the first 
week after the KDE 4.7 Release (July 27).

Thanks.

-- 
Burkhard Lück