[kde-doc-english] Parley userbase manual

[Burkhard Lück]

Am Sonntag, 13. Juni 2010, um 16:30:54 schrieb Frederik Gladhorn:
> 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.
> 
We dont use the pearl script any more, we have an own solution which handles 
all issues mentioned in my mail quite well.

I am able to generate a valid docbook on the fly, including a proper docbook 
header and footer, just give me a userbase page name.

Please inform Markus to stop working on the perl script. 
Thanks to you both for the offer to help.

> 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:

[snip]

> > 
> > 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.
> 
No problem, this is processed by the script properly now.
But http://userbase.kde.org/Toolbox#Use_Headings says:
<quote>
Avoid using a single one - that denotes a page heading, and the automatic page 
heading should be used. Your major headings will use '==text goes here==', the 
next level, '===more text===' and so on.
</quote>

> > > > 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.
> 
Please stop Markus and from my pov use whatever you like, underscores, 
spaces...

> > > > 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

Thanks.

-- 
Burkhard Lück