[kde-doc-english] Entities in Kleopatra

[Lauri Watts]

On Wednesday 11 August 2004 13.10, Éric Bischoff wrote:
> Le mercredi 11 Août 2004 12:08, Frederik Fouvry a écrit :
> > Given that the internal communication in KDE applications, such
> > as to build up the menus, is done in XML, it should be possible
> > to grab that and to output (it into an xslt style sheet that
> > generates) DocBook for the menus.  Gone would be the double
> > translation effort for menus, and probably also the need to use
> > entities ...  I just don't know _how_ to do it.
>
> Your idea is ambitious, but that would really be a huge benefit:
>
> The consistency between user interface and documentation would be
> automatically ensured.
>
> It would spare the translation teams a lot, lot, lot of translation work
> and verification work and remove a lot, lot, lot of inconsistencies between
> documentation and user interface.

Frerich Raabe actually wrote two little tools that parse a .ui file (ui2ent) 
for a dialog, and generate a set of entities and the markup to go with them 
using the displayed text + the what's this help *and* generate a screenshot 
(ui2png).   I unfortunately don't seem to have a copy of the source, so I'm 
cc'ing Frerich to see if he does.

One of the problems with this approach as I recall it was, many dialogs are 
not specced in the .ui files, but straight in the .cpp files (much harder to 
parse), and also, many of them don't actually have any what's this help to 
re-use.  This would of course also be an issue for doing it purely in xslt.

I also have a python script that takes a text file formatted like this:
File
	New
	Quit
Edit
	Cut
	Paste

and creates a whole load of docbook out of it (where each top level menu is a 
<sect1> and each menu entry is a <varlistentry>, all marked up ready to fill 
in.

There is also a whole load of python scripts that were mostly written by Phil 
and Frerich, that do a ton of automated checking, including:
Validate the file.
Generating a license-and-credits chapter based on the Help -> About info of an 
app, 
Checking for preferred forms of words in a provided wordlist, e.g., can't 
should be can not, Directory should be Folder in most cases then providing a 
list (with line numbers) where they occur.  We thought automating this would 
lead to false positives
Checking for the translation credit placeholders, and getting them in the 
right place
Checking for words that could be replaced with entities from the 
general.entities, user.entities and contributor.entities files
Check for empty elements (valid, but breaks translations)
Checking for multiple root elements in a single docbook file (also valid, but 
breaks translations)

The entire suite makes up a "pre-flight" check of a doc,   and I've put a copy 
of those ones here: 
http://people.fruitsalad.org/lauri/stuff/docbook-tools.tar.bz2

We've had all this in a sorta-nearly-finished-but-not-quite state for quite 
some time, and it's one of the things we had planned for aKademy, to really 
clean them up, test them (I'm not sure they've been tested yet on other than 
FreeBSD :) and publish them in a useful form, with some instructions.  

Regards,
-- 
Lauri Watts
KDE Documentation: http://docs.kde.org
KDE on FreeBSD: http://freebsd.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/20040811/c60fdf89/attachment.sig