[kde-doc-english] [RFC] "Split or not to Split" that is the question ; -)

[T.C. Hollingsworth]

On Sun, Jan 1, 2012 at 4:02 PM, Chusslove Illich <caslav.ilic at gmx.net> wrote:
>> [: Burkhard Lück :]
>> So my question is, what you prefer - one docbook/docmessages.po (as far as
>> possible/sensible) or splitted docbook/docmessages.po's?
>
> I think the best solution is: multiple docbooks, single PO. Multiple
> docbooks is frequently more natural for authors, and single PO is more
> natural for translators. In other words, documentation source splitting
> should not have direct relation to PO splitting -- just like for code.

+1  From this (admittedly very new :-) writer's POV, I very much
prefer split docbooks.  It's much easier to find what I want to work
on that way.  I also tend to proofread on the diffs commitfilter sends
to me, and I think that's easier when larger docbooks are split up
into chapters.

But, Kate's manual is larger than most, and I can see how the split is
unnecessary for many docbooks.  If everyone else would rather move to
monolithic docbooks, it wouldn't bother me that much, as searching for
the section I want isn't that much harder.  Some students are working
on improvements to Kate's XML handling, so we may even be able to get
some conveniences in Kate to make things even easier.

Note that KatePart is getting it's own documentation for 4.9, and Kate
& KWrite will be linking to it instead of including it.  So Kate will
no longer stricly need split docbooks, and the remaining ones will be
much more manageable as a monolithic docbook too. ;-)

> If our current documentation extraction-injection toolchain does not allow
> for this differentiaton, that's one of its downsides...

I don't think it does right now.  But, after taking a brief look at
scripty's magic, I don't think it would be too difficult to teach it
to do this.  I'd be happy to have a chat with Albert and come up with
some patches sometime after 4.8 goes gold if we wanted to go this
route.

Personally, I'm not convinced that we need to add more complexity to
scripty for what seems to be an edge case.  I just don't want us
dismiss to dismiss something offhand as technically impossible, when
it probably isn't.  Anything is possible!  ;-)

-T.C.