On Sat, 02 Jan 1999, you wrote:
>Eric Bischoff wrote:
>> 
>> So, I suggest :
>> - Applications tree : SGML
>> - Documentation tree : SGML, HTML, PostScript
>> - Packages : HTML, PostScript
>> 
>> The developper writes the SGML source, the translators translate it to their
>> respective languages and publish it under two formats, and end-users get those
>> two formats for browsing and printing.
>
>SGML should be included in the packages, in case the user wants to produce an 
>RTF for export to his MS buddies, or something else.  

As Stephan said, I can hardly imagine end-users generating different versions
of their docs (RTF, PostScript, ...) with SGML-Tools. Don't forget that someone
that is in need of documentation is most of the time someone who does not know
how to start and has some difficulties with the environment. So he may not be
able to generate a PostScript file, or even to compile SGMLTools, or even know
he has to do it.

I see SGML as a kind of source. The usual policy in the Linux world is to offer
two sets of packages, source packages (usually C and C++ text) and binary
packages (usually for each platform. For documentation the equivalent would be
for each format : RTF, HTML and so on...). We could do the same :
kde-doc-fr-html-1.1.tgz
kde-doc-de-html-1.1.tgz
kde-doc-it-html-1.1.tgz
etc...
kde-doc-en-ps-1.1.tgz 
kde-doc-en-sgml-1.1.tgz
kde-doc-en-text-1.1.tgz
kde-doc-en-rtf-1.1.tgz
etc...
It would be of course again some extra work for us. The advantage would be extra
flexibility. People would just choose their doc format and not download huge
PostScript archives when they don't need them.

>The documentation tree should be entirely automatically generated, and 
>therefore explicitly NOT stored in the CVS.  Having two CVS versions is 
>extremely confusing and hard to track.  To rephrase:
>There should be no "www/documentation" tree in CVS, the documentation
>that is "general" (FAQ, howto-xlate, user guide, etc...) would become 
>part of the kde-lang module,

Well, I used to distinguish the documentation tree on www.kde.org from the one
that would be distributed in packages and installed on the end-user's machine.

The first one (on the web server) had two functions to me :
- ease translators' work, by grouping everything in the same tree
- allow end-user's access to docs through the web, while they are not already
available in packages

The second one (on the end-user's machine) was intended for use with KdeHelp.

I agree with you when you say that the documentation tree should be entirely
generated automatically, if you mean : on the end-user's machine.

If you mean that we must generate the www/documentation tree automatically as
well, I'm hesitating. On one hand, it's true, having two versions is extremely
confusing. On the other hand, manual handling was allowing easy coordination.
For example, when there was a brand new software written for KDE, there was no
need to CVS commit on the web server all the drafts that the application
developper wrote and all the intermediate versions before the work was complete.
So translators would not start translating something that is not ready. I really
don't know. If we choose to generate the www/documentation tree automatically
as well, it would be a little revolution for the coordination's work ;-)

BTW, Howto-xlate is not intended for end users, like FAQ or UserGuide. So there
is no need to package it.

>> >I think, we need to get rid of all those doubled files in CVS. Those
>> >logos are soo much redundant, that it hurts.
>> 
>> Yes, our favorite WebMaster (Hi Robert !) should make all the links to
>> logotp3.gif point to the Images directory, or better to a gif file for each
>> language (to accomodate separate packaging).
>> 
>It might be simpler to have the tools refer to "../images/logotp3.gif" 
>instead of in pwd, and have the kde-lang module install an image directory
>with the navigation icons, and logotp3.gif.

Good idea. But those files are automatically copied by some scripts
to the directory of the html files (ksgml2html?), so we would have to change
these scripts. Any volunteer ?

BTW, Chuck and I have decided to put a copy of the Lang.pm file in the
www/documentation tree. It is a part of the SMGLTools we had to modify to
accomodate new languages (Greek, Russian, ...). I forgot to tell it on this
list.

Eric
--
Eric Bischoff
mailto:ebisch@cybercable.tm.fr