[kde-doc-english] Parley userbase manual

[Burkhard Lück]

Am Mittwoch, 9. Juni 2010, um 14:32:01 schrieb Anne Wilson:
> On Wednesday 09 June 2010 07:38:11 Burkhard Lück wrote:
> > Am Montag, 7. Juni 2010, um 18:45:35 schrieb Anne Wilson:
> > > Hi, Burkhard.  I hadn't seen this when I wrote the other message to
> > > you. I'm glad that it worked, even though you had to do some
> > > preparation work.
> > 
> > Some comments/questions regarding the page dump + conversion:
> > @Frederik:
> > top level in parley docbook should be chapter not sect1?
> > what to do with empty sections, that is not allowed in docbook? comment
> > them out and add content when it is added at the userbase page?
> > 
> > @Anne
> > what is the difference between
> > [[Image:Parley welcome screen.png|thumb|500px]]
> > and
> > [[File:Parley file select dialog 0-9-4.png|thumb|500px]]
> > why Image and File here?
> 
> In display terms, very little, by the look of it.  I suspect that what you
> are seeing is two editors with different styles - and a lack of documented
> rules. While learning to edit in UserBase I did a good deal of reading,
> and 'Image:Parley....' is the form that I met constantly.  I would prefer
> that we stay with that format.  It is also the format recommended on
> http://userbase.kde.org/Toolbox
> 
> > The perl script wt2db works basicallly, but has some bugs / could be
> > improved for these wiki markup elements:
> > 
> > 1) wrong placing of closing </para> for itemized lists
> > 2) [[File:foo]] conversion to screenshot markup in docbook
> > 3) internal/external links are wrong
> > 
> > If there is any one with some skills in perl, please have a look at these
> > issues.
> > I have uploaded wt2db+Wt2Db.pm together with all intermediate file
> > generated in the conversion process to branches/work/doc/parley/.
> > 
> > Any help to improve the conversation process  and the pearl script is
> > really appreciated.
> > 
> > > As I mentioned in my other message, I now have to look at fine-tuning,
> > > to make the system work best for both on-line and off-line
> > > translators.  If there are specific changes that would be helpful,
> > > please let me know asap, so that we can meet everyone's needs.  Thanks
> > 
> > Some defaults which should to be used in the wiki markup to ease the
> > conversation:
> > 
> > 1) consecutiv order of heading levels like:
> > =level1=
> > ==level2==
> > ===level3===
> 
> In mediawiki the convention is to start markup from '==' - since the single
> '=' displays in the same style as the page header.  I would prefer to stick
> with the mediawiki convention unless it causes real problems.  Does it?
> 
The Parley page dump has:
level1 = Introduction  = &lt;!--T:3--&gt;
level1 = Start Page  = &lt;!--T:12--&gt;
level1 = Open an existing collection = &lt;!--T:21--&gt;
level1 = Vocabulary Practice  = &lt;!--T:28--&gt;
level3 === Practice Setup  === &lt;!--T:29--&gt;
level3 === Advanced Practice Configuration === &lt;!--T:34--&gt;
level4 ==== Blocking  ==== &lt;!--T:36--&gt;
level4 ==== Thresholds ==== &lt;!--T:39--&gt;
level4 ==== Advanced Practice Settings ==== &lt;!--T:42--&gt;
level3 === Practice === &lt;!--T:45--&gt;
level4 ====Flash Cards====
level4 ====Mixed Letters==== &lt;!--T:52--&gt;
level4 ====Multiple Choice==== &lt;!--T:63--&gt;
level4 ====Written==== &lt;!--T:71--&gt;
level4 ====Counting an Answer as Right ==== &lt;!--T:79--&gt;
level4 ====Reset Practice to Initial State==== &lt;!--T:84--&gt;
level3 === Summary After Practice === &lt;!--T:86--&gt;
level3 === Grammar Practice Modes === &lt;!--T:89--&gt;
level4 ==== Articles and Gender of Nouns ==== &lt;!--T:90--&gt;
level4 ====Comparison Forms of Adjectives and Adverbs====
level4 ====Conjugations==== &lt;!--T:105--&gt;
level1 = Vocabulary Editing  = &lt;!--T:110--&gt;
etc.

Problem is the jump from level1 to level3, that needs manual correction after 
running wt2db, I had to lift up all level3 to level2 and all level4 to level3.
 
> > 2) one markup only für GUI strings?
> 
> Not sure what you mean here?
> 
In the Parley page in most, but not all cases '''foo''' (Bold) is used for GUI 
strings. This has to be changed to <gui...> markup for docbook. And that is a 
lot easier, if there is one markup in the wiki exclusively used for GUI 
strings.

> > 3) File or image names either with spaces or with underscores, no mixture
> 
> In the Toolbox page I have added an instruction to use underscores.
> 
Hmm, the perl script doesn't handle underscores very well, therfore using 
spaces would be better. Or someone has to adapt the perl script to handle 
underscores properly

> > 4) avoid > 1 markup for one string like ''''' (bold + italic)
> 
> There are not many places where this is used, and the need for it will,
> hopefully disappear quite soon.  The problem has been that web links were
> not easily seen in the schema currently used.  We can make sure that that
> isn't so in the new theme, so many bold instructions can disappear.
> 
The perl script wt2db processes either ''' (bold) and ''(italic) properly, but 
not both markup for one string.

> > 5) avoid empty sections
> 
> Since PageLayout and Toolbox are the pages that set the guidelines, I think
> we need to draw attention to these as soon as possible.  I will discuss
> with Ingo what we can do about that.  One thing is to change the current
> Help link to Quick_Start, where those pages will be clearly linked, but
> any other suggestions are welcome.
> 
> Anne


-- 
Burkhard Lück