[k3b] K3B Documentation

[Burkhard Lück]

Am Dienstag, 3. August 2010, um 07:49:18 schrieb Michał Małek:
> Burkhard Lück wrote:
> > Hi k3b devels,
> > 
> > (cc'ing the i18n coordinator as scripty + the translators are affected)
> 
> Hi,
> Sorry for delayed answer, I was on my vacation.
> 
> > there are two issues with the k3b documentation:
> > 
> > 1) k3b.desktop has X-DocPath entries to userbase, but there is still a
> > k3b documentation in extragear/multimedia/doc/, which is processed by
> > scripty an translators. That does not make any sense.
> 
> Agreed, this needs to be removed.
> 
Please wait with this step, I want to check if it makes sense to merge the 
translations in kde svn into the new docbook exported from userbase.
In case you agree with the solution 2b) kde-i18n-doc will handle this and you 
don't need to care about this.

> > Ways to address this issue:
> > 1a) [re]move the documentation and translations in kde svn.
> > Cons: no help offline, few translations, X-DocPath entries need to be
> > manually synced with translation progress on userbase
> > 
> > 2b) Export userbase pages K3b + K3b/Burn_an_Audio_Cd_with_K3b, convert it
> > automatically via wiki2docbook, commit to svn and use the local help file
> > as X-DocPath entry. We (Doc-Team+Translators) do that already e.g. with 
> > the Parley handbook.
> > Pros: Offline help uptodate as on userbase, more translations, automatic
> > workflow
> 
> I like the second solution. How is it done in practice? Does snapshot of
> online documentation is taken just before a major release?
> 
There is no change to your workflow, announce a release as usual on the 
translators mailing list, several doc team members are subscribed there as 
well, so the doc team will then update the svn docbook from the userbase page, 
if necessary.
Of course the doc team would like to export the current page immediately to 
give the translation teams the chance to start early with their work.
  
> > 2) k3b kcm
> > The KCM has an enabled Help button, but no X-DocPath entry. Launching
> > Help opens KHelpcenter and displays the message "There is no
> > documentation available for /index.html", bad user experience :-(
> > So either the Help button should be disabled or a proper X-DocPath
> > (according to the solution of No 1) should be added.
> 
> Good spot,  I will disable it.

Why do you want to disable it?
A better solution would be from my PoV to leave the Help button enabled and 
the doc team adds a proper X-DocPath pointing to the section "Configuring the 
internals" in the docbook exported from the userbase page.

-- 
Burkhard Lück