[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-devel
Subject:    Re: Getting Documentation to Work in i18n...
From:       Peter Silva <peter.silva () videotron ! ca>
Date:       1998-12-31 4:11:44
[Download RAW message or body]

Stephan Kulow wrote:
> 
> Peter Silva wrote:
> >
> > Stephan Kulow wrote:
> > >
> > > Peter Silva wrote:
> > > >
> > > > [snip]
> > > >
> > > > > OK, so how would CVS look like?
> > > > >
> > > > > kdebase/kfm
> > > > > kdebase-i18n/docs/de/kfm/*.sgml
> > > > > kdebase-i18n/apps/de/*.po
> > > > >
> > > >
> > > > I was thinking the CVS would look like so:
> > > >
> > > > 1)
> > > >         kdebase/kfm
> > > >         kdebase/kfm/doc
> > > >         kdebase/kfm/doc/en, de, .../.sgml
> > > >         kdebase/kfm/po/en, de, *.po
> > > >
> > > > (or maybe even 2):
> > > >         kdebase/kfm/lang/en, de, .../ *.sgml, *.po ...
> > > >  that would save a parallel level of directory trees.)
> > > >
> > > > 1) being as is already standard (except for in kdebase :-)
> > > I don't like po files in application. You're thinking of moving
> > > an application, but how often does that happen? Much more often
> > > people want to translate something - and they need to have a
> > > central point where to look at, not hundreds of places. The
> > > same applies to documentation in general!
> > >
> >
> > If the place is identical for any package, then it makes no difference
> > whatsoever.  If it's in one place in one CVS module, in another in another
> > module, in another if it's a non-CVS application, or another if it's been
> > developed with this IDE (as opposed to the other one.), or another place
> > if it is unrelated to a particular application, then finding it becomes
> > non-trivial.
> >
> > > The above makes much too many directories - and think of directories
> > > as seconds to wait when configure runs! ;-)
> > >
> > > I would rather go with
> > > kdebase/kfm/*.cpp
> > > kdebase/doc/kfm/.sgml
> > > kdebase/po/lang/kfm.po
> > >
> >
> > If the documentation isn't installed by the same mechanisms as program source
> > code, then can configure/etc... be set up to explicitly avoid them entirely?
> No.
> > I had in mind the documentation would be packaged into tarballs which were
> > relative, and only the installation script (or, if $KDEDIR is used, not
> > even that.) would need ./configuring...
> BTW: KDEDIR doesn't exist anymore!
> >

Cool !? What happenned to it?

> > > I really see no problem in reoganizing kde*\kdebase to follow kdebase.
> > > The only problem there is that application developers have to split
> > > their sources. But now they're asked, if this is ok for them. As I'm
> > > quite sure noone besides me and Peter is reading this thread (Hello! ;),
> > > the question makes no sense here, but anyway.
> > >
> > > Since I'm going to be the one that has to implement the new way,
> > > the remaining question is: what else do you not like about the current
> > > way in kdebase besides moving one application later?
> > >
> >
> > It is desirable to have a source tree for a single package include all
> > sources (C++, sgml, i18n) because:
> >
> >         - IDE's could include documentation development as part
> >           of the environment.
> >
> >         - CVS packages are identical to packages outside the
> >           CVS, so that IDE's that did include doc. maintenance would
> >           be usable with apps that are in the CVS.
> >
> >         - The developer is aware of the existence of translations,
> >           so that the documenter is aware of changes in the source, etc...
> >           Separating the trees is guaranteed to have i18n and docs further
> >           out of date from the source.
> >
> >         - when someone is given a "Source" package, it includes documentation,
> >           perhaps even in a language the developer understands.
> >
> OK - so let's say the following standard:
>  application should organize their data as follows:
>    appname - includes compilable source
>    doc - includes _all_ documentation in SGML format only
>    po - incudes all uncompiled app translations
> 
> You can do that with an IDE or in kdebase as well! I don't see
> this as strong argument. We simply move doc and po into a
> standard second module for big modules to make them smaller.
> 
> Where the documentation is doesn't matter for the developer as
> long as it's a standard place where to look at!
> 

That sounds good!  I like it.
The only sub-optimal is that source packages (when distributed for
individual apps, outside CVS) will be like so:

	<app>/<app>
	      doc
	      po

but that's no big deal...

Yup. I'm happy with that.  

P.S. while we're at it, could we cut out a layer of the FSSTD?
I'd like KDEDIR/share/doc/HTML/en to lose the "HTML", and have
all the docs in the same directory (KDE/share/doc/en.)  We already 
have file type suffixes, it might provide for image sharing between 
formats, and all the processing tools assume the dest. is pwd by 
default (So it would make things easier for packaging) and would
eliminate a lot of directory trees.  I'm assuming this change would 
be a post 1.1 change.

Yes, we can still package the .ps files separately, they would
just go into the same directories. 

About reducing the volume of images in the docs:
We could have the basic documentation create an "images"
directory (share/doc/<lang>/images/next.png, prev.png, etc...
It would be accessible from any app-help directory
via ../images.  So kdoc, etc... could be modified not to include 
any images directly, but only point to them there.  Theme support
could also change the images for all apps.

The only thorn in the plan being kcontrol.  One could create a
symlink (on installation) ln -s ../images images in kcontrol to fix that.




-- 
Peter

[prev in list] [next in list] [prev in thread] [next in thread]