[kde-doc-english] Kate documentation chapter shuffling

[Burkhard Lück]

Am Montag, 20. Mai 2013, 08:38:13 schrieb Yuri Chornoivan:
> написане Mon, 20 May 2013 00:26:28 +0300, T.C. Hollingsworth
> 
> <tchollingsworth at gmail.com>:
> > Hi Yuri & Burkhard!
> > 
> > I'm currently working on moving a couple things around in the Kate
> > documentation.
> > 
> > First, I'd like to add a new "development" chapter that provides a
> > high-level overview of ways to extend kate (katepart plugins, kate
> > plugins, pate plugins, and JavaScript scripting), that will link to
> > resources on kate-editor.org and api.kde.org where appropriate.  (I
> > think basic information about this in the handbook is useful given how
> > many programmers use editors and how they like to modify them to suit
> > their needs, but we need not get too crazy in the offline
> > documentation.  ;-)  As part of this, the scripting API documentation
> > that currently lives in advanced.docbook would get moved to a new
> > development.docbook.  As a result, a bunch of strings would end up
> > moving from kate_advanced.pot to a new kate_development.pot.
> > 
> > Also, as the list of JavaScript scripts grows it seems not so nice to
> > me to continue bloating the menu chapter with them.  I'd like to move
> > them to the plugins chapter, where I think they fit more naturally.
> > As a result, a much smaller number of strings would move from
> > kate_menus.pot to kate_plugins.pot.
> > 
> > I've pushed the changes to this clone of the kate repository for review:
> > http://quickgit.kde.org/?p=clones%2Fkate%2Fhollingsworth%2Fdoc-work.git
> > (or `git clone kde:clones/kate/hollingsworth/doc-work.git`)
> > 
> > (It's still missing new content but all the movement is done.  I'm
> > heading out for a hike right now but I'll finish it when I get back
> > later tonight.)
> > 
> > Let me know if I need to do anything and/or when this will be safe to
> > push to master.
> > 
> > Thanks!
> > -T.C.
> 
> Hi,
> 
> I think it's a very nice improvement to have in KDE 4.11. I do not see any
> flaws in the proposed patch now. 

Agreed, your changes make sense.

> The only problem is the translations. IT
> will be good to concatenate some catalogs to make the translation handling
> easier right before the commit.
> 
For your current changes (move part from advanced.docbook to new 
development.docbook - the move of parts from menus.docbook to plugins.docbook 
did not happen so far, right?) it is no problem to handle translation shuffling.

Me also prefers to have less and bigger docbooks, so may you could merge some 
small docbooks like mdi into an existing docbook?

But ist is of course up to you as maintainer to decide about this.

> Should it appears that there will be some minor mistakes, it is easier to
> fix them in situ when the changes will be committed.
> 
Yes.

I'd propose the folliwing procedure:

1) Docbook shuffling, but no new/changed content in your clone to your needs

2) Merge into master. Please provide info what was shuffled in the commit log 
(like "moved part of a.docbook to b.docbook", "moved c.docbook into d.docbook" 
etc.), cc kde-i18n-doc at kde.org and tell translators not to touch the 
translations until translation merging/moving is done (probably by me). I'll 
give translation teams a notice, when this is finished.

3) Then change/add/improve docbook content in master. Please keep July 8, 
2013: KDE SC 4.11 Documentation Freeze in mind.

Thanks.

-- 
Burkhard Lück