[kde-doc-english] Parley userbase manual

[Burkhard Lück]

Am Montag, 14. Juni 2010, um 06:37:26 schrieb Sabine Emmy Eller:
> Good morning!
> 
> One question: could you please send me the former mails? I did not get them
> since my mail was not working properly (this is the first one). 

You find the previous mails of this thread in the list archiv:

http://lists.kde.org/?t=127564901300001&r=1&w=2

The docbook generated from the userbase page is in 
branches/work/doc/parlyindex.docbook. 
This file has a manually added docbook header and footer and the body has 
modified markup (consistent usage of bold/italic wiki markup, usage of 
entities...)


> I am not
> sure thought if the wiki formatting really can subsititute the much more
> detailed docbook formatting (had a look into this during the last days -
> was looking at kstars .docbook files as an example).
> 
Of course docbook markup is much more detailed, but that is not the real 
problem.
For a lot of markup like lists, headers, tables, notes, warnings, hints, tips, 
screenshots etc there is nearly a 1:1 relation between docbook and wiki 
markup, so that can be propery automatically converted.

The real problem is the inconsistent usage of e.g. bold + italic in the wiki 
markup, that seems to be a like lottery. 
Markup like bold + italic is used in an unpredictable manner, this markup in 
all possible combinations is used for everything, sometimes for GUI Strings 
like  Menu items, Window titles, Common labels in window that cannot be 
changed by the user etc, sometimes it is something important, sometimes for 
links and sometimes for something I can't recognize. 
That is not only inconstent between different userbase pages, that is also 
inconsistent in single pages (yes on the Parly page as well) and sometimes 
even inconsistent within a single sentence.

If I read a html generated from a docbook in kde svn in a language where I 
can't recognize any Character like Chinese, I can identify exactly a gui 
string, a file extension, a command name, the option of the command, a keyboard 
key, a shortcut and many more.
Trying to do the same with the Chinese page of Parly (is there any?) is nearly 
impossible, my hit rate of the meaning of strings with markup would be less 
than 30% I guess.

If you'd like to see the difference between the corrected markup in  
branches/work/doc/parlyindex.docbook and the automatically generated markup 
please drop me a note thenn I send you both docbook sources and the generated 
html file.

-- 
Burkhard Lück