[kde-doc-english] Parley userbase manual
Frederik Gladhorn
gladhorn at kde.org
Sun Jun 13 16:30:54 CEST 2010
Hi,
I'm sorry I am so late to answer, but during Linux Tag I just didn't find the
time and calm to sit down for this. On the other hand, I am happy that we can
get some help from Marcus with regards to Perl. He will post a patch fixing
many issues (for example some of the links) to this list.
On Wednesday 09 June 2010 15:31:25 Burkhard Lück wrote:
> 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 = <!--T:3-->
> level1 = Start Page = <!--T:12-->
> level1 = Open an existing collection = <!--T:21-->
> level1 = Vocabulary Practice = <!--T:28-->
> level3 === Practice Setup === <!--T:29-->
> level3 === Advanced Practice Configuration === <!--T:34-->
> level4 ==== Blocking ==== <!--T:36-->
> level4 ==== Thresholds ==== <!--T:39-->
> level4 ==== Advanced Practice Settings ==== <!--T:42-->
> level3 === Practice === <!--T:45-->
> level4 ====Flash Cards====
> level4 ====Mixed Letters==== <!--T:52-->
> level4 ====Multiple Choice==== <!--T:63-->
> level4 ====Written==== <!--T:71-->
> level4 ====Counting an Answer as Right ==== <!--T:79-->
> level4 ====Reset Practice to Initial State==== <!--T:84-->
> level3 === Summary After Practice === <!--T:86-->
> level3 === Grammar Practice Modes === <!--T:89-->
> level4 ==== Articles and Gender of Nouns ==== <!--T:90-->
> level4 ====Comparison Forms of Adjectives and Adverbs====
> level4 ====Conjugations==== <!--T:105-->
> level1 = Vocabulary Editing = <!--T:110-->
> 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.
I'm sorry, I introduced this chaos since I tried to clean up the top level
headers. It should of course be always level 1, 2, 3 ... without jumps.
>
> > > 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.
I agree, a template would be good for that, maybe it can even indicate the
semantics on the wiki as well.
This means that keyboard shortcuts or menu items will actually be easier to
recognize.
>
> > > 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
I hope Marcus will do the fixing, since the wiki does not enforce anything here
and it's bound to break again.
>
> > > 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
Thanks for all the effort of everyone :)
Frederik
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 198 bytes
Desc: This is a digitally signed message part.
Url : http://mail.kde.org/pipermail/kde-doc-english/attachments/20100613/9193bcf1/attachment.sig
More information about the kde-doc-english
mailing list