[ubuntu-doc] Re: Proposal to use meinproc for Kubuntu

[Matthew East]

On Thu, 2005-11-24 at 04:01 +0000, Jonathan Riddell wrote:
> On Wed, Nov 23, 2005 at 06:00:22PM +0000, Matthew East wrote:
> > On Wed, 2005-11-23 at 11:52 +0000, Matthew East wrote:
> > * no separate build system for online/offline documents in Kubuntu
> 
> Using meinproc or xsltproc makes no difference for this as far as I know.

If you can use meinproc to build online documents too, then that is
fine, this objection goes out the Window. It's just that in the current
Makefile the situation is meinproc for offline, xsltproc for online
AFAICS.

> > * support for xinclude (which in turn has advantages of being able to
> > pick and choose which files to translate and which do not need
> > translating, and that we can include the licences easily)
> 
> What wouldn't need translated?

Licences. It is a big problem to put the entire of the licences in
rosetta for every document and asking the translators to translate them
again and again and again. The only solution to this (that I know of) is
not to include _any_ entities in the translation template, which can be
a problem, unless the authors do not use any entities that bring in
english specific text.

> > * same build system for Ubuntu and Kubuntu docs, same xsl stylesheets,
> > different css.
> 
> We don't want to us the same XSL stylesheets, we want to use the KDE
> XSL stylesheets to make the docs fit in with the rest of the KDE docs.

That is your call. I would think that there is no fundamental difference
made in the end, because the css is the same. Also, I like the idea of
building Ubuntu docs in the same way, not building docs in the same way
as upstream. Especially given that they appear on the same website
together.

> > * no kde-specific libraries required to build the documents, only
> > docbook-xsl.
> 
> Why is that a problem?

Not a massive one, but it means that people who want to build both sets
of documents need both toolchains.

> > * Meinproc makes compressed copies of the html documents, which thus
> > save space in packaging (query whether xsltproc can do this?)
> 
> The KDE stylesheets also create 1 large HTML document which then gets
> split up into individual html files based on <FILENAME> tags.  Someone
> would need to work out how to change the stylesheets to not add these
> tags, then have rules to add these <FILENAME> tags, concatenate the
> files and compress them to create the index.cache.bz2 file that KDE uses.

Yes, they would.

> > * Riddell mentioned that there was an aesthetic problem with the html
> > documents we shipped in Breezy created with xsltproc, I'll install
> > Kubuntu and take a look at this hopefully this weekend.
> 
> They have the <FILENAME> stuff in them.  Using meinproc this would be
> got rid of.

Has anyone taken the time to find out if this can be removed by using
xsltproc? i'm sure it can.

In general: naturally this decision should be taken by the people who
are going to take care of kubuntu documentation (jonathan, jonathan,
jerome, bhuvan and whoever else). I just wanted to make sure that the
decision is taken with a decent amount of caution because I believe that
we can work with a single toolchain. I don't have any doubt that the kde
toolchain is good, but I do have doubts about people who wish to
contribute to the team having to learn to write documents in two
different ways, technically speaking. It's hard enough to ask people to
learn one way.

As for translation, I already said I'd like to help with kubuntu-docs
translations, but the amount of extra work that would be created by
using two separate toolchains for translation too would mean that I'd
need at least one other person to help with that. I currently haven't
seen any justification for using separate things for each desktop.

Matt
-- 
mdke at ubuntu.com
gnupg pub 1024D/0E6B06FF
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
URL: <https://lists.ubuntu.com/archives/ubuntu-doc/attachments/20051124/98feb0e4/attachment.pgp>