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

List:       kde-i18n
Subject:    Getting Documentation to Work in i18n (was Re: [Fwd: Comments on KDE User Guide])
From:       Peter Silva <peter.silva () videotron ! ca>
Date:       1998-12-22 16:22:56
[Download RAW message or body]

Eric Bischoff wrote:
> 
> On Sat, 19 Dec 1998, you wrote:
> >I'm looking for the SGML source for this document to do
> >the correction. I haven't found it yet...
> >
> >(I mean in the main tree, I found it in the www/doc*/en tree.)
> >
> >How does it get installed?
> >
> Peter Pfutzer has put the SGML source in the applications ("main") tree at the
> wrong place :
> he's put it in kdeadmin/ksysv/doc
> instead of kdeadmin/ksysv/doc/en
> 
> I already told him he should move it, but maybe he forgot
> 

I like the per-language sub-dirs, but I don't know if this discussion 
was finished, I never got any answers (aside from Eric and Stephan.)

Stephan?  Please look this over and tell me if it's nonsense (or not :-)


---------------------
Review:

I proposed that all the docs go into the main CVS tree.

Stephan, if I understood correctly, responded that he: 

    1) didn't want the docs in the main tree, and wanted all documentation 
       removed (including the English stuff.)

    2) is worried about the main packages getting too big (with all the
       different language packages.
--------------------
OK.
 
I do not think that all docs in all languages would become part
of the standard kdebase package (I do not want kdebase to include 15 
sets of po files and .htmls.)

There should be a separate packaging scheme to extract just the 
documentation and prepare language packs, perhaps one per language,
including all po and doc files.   That means that application installation
does not take care of installing i18n or docs.  

I'll propose what the packages should look like further down, first
let me say why I want the docs to be in the application:

	-- So the developer knows they exist, and can 
	   know for himself what is out of date.

	-- So the developer and proofreader/translator are working
	   with the same source and can make concurrent changes.

	-- So that the source (including all documentation)
	   can be easily extracted for export or re-import.
	   (when we move a package from kdenonbeta, the change
	    currently must be mirrored under the www/doc tree,
	    separately for each language, it is a royal pain.)
       
        -- So that IDE's can integrate documentation generation
	   into the development process thereby encouraging developers
	   to write documentation.  If there is a clear FSSTD for
	   docs, this is much easier.

	-- So that App authors can write in their native tongue
	   and there is a standard place for those docs to show up.
          
	-- So that Apps have the same structure inside or outside 
	   CVS.


The language packages could be named like so:

kde-docs-en, kde-docs-fr, kde-docs-de, ...

I would opt for including both sgml and html in these language packs,
but not ps. OTOH, the kdedoc tools should be more available, perhaps
as part of kdeutils, so that users can easily generate their own postscript.

The contents of the language packs should be like so, just because
that is how it already installed by the current methods, and kdehelp
will find it easily.

 KDEDIR/share/doc/HTML
	en/<app>/*.html
	         *.sgml

and should contain all docs from all CVS apps, for one language.
I would actually prefer to drop the HTML and just have "doc" with all
the different formats in one tree (but not install ps by default.),
that's what extensions are for. It will also make the source
documentation tree identical to the installed one, so the installation
process can be as stupid as "cp -r."

I do not think that having documentation without the software is
a problem. It is probably good marketing.

The installation directions for KDE would then become to install:
	kdesupport (whatever you need from there)
	kdelibs
	kdebase    (includes ksgml2html ... )
	kde-doc-<lang1>, kde-doc-<lang2>, ...
	<other optional modules.>

Stephan, do you like this scheme  ?

(You'll probably be the one stuck with implementing it :-)  ??

I can participate in writing scripts to make it happen.


-- 
Peter

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