Re: [platform-help-dev] Re: [platform-doc-dev] new help system proposal

[Ben Konrath <bkonrath@xxxxxxxxxx>]

>    =  Michael Behm
> >  =  Ben Konrath
> >> =  Konrad Kolosowski

<snip>

> Red Hat does not localize Eclipse documentation now and there are 
> (currently) no plans to do so in the future. But this raises an 
> interesting question: I gather that a user of Eclipse on Windows in 
> Germany would automatically see online help in German. Given that there 
> is no German online help for the Linux version, it would be useful if we 
> could present the user with the choice of viewing the Windows-German 
> help or the Linux-English help.

For eclipse.org vanilla downloads, I would think that if the German
language pack is installed, the German help would come up. I really
don't think that my concern will be a problem. We should confirm this by
marking up the docs so that we know specifically what kind of content
differences we are dealing with (see below). 

<snip> 

> <p>Bring focus to the interface widget in question by clicking on it or
> > using the Tab key, and then press <span class=win32>F1</span>
> > <span class=gtk>Ctrl+F1</span><span class=carbon>the Help key</span></p>
> > 
> > Motif is not mentioned in this section but it's possible there could be
> > another span tag to accommodate it. I probably won't be writing content
> > so I think that the people who will be should comment.
> 
> This is pretty standard practice at places such as IBM--except that the 
> <span> tags would probably be at the sentence level. (This makes it 
> easier for the localization team.)

Ok, sounds good.

> > Also, the technical writers expressed interest in a system that allows
> > them to write content in WYSIWYG editors such front page and
> > dreamweaver. Do these tools support a system like this?
> 
> Sure--you can mark areas of text and apply classnames to them.

Great!

> >>TODOs: 
> >>- mark Windows specific paragraphs in Eclipse documentation with
> >>class=win32
<snip>
> This is not done in our internal CVS. Ben, you recall when we had to 
> rework the entire Eclipse documentation set in 15 working days? I ripped 
> out text rather than apply CSS tags. However, as we've been asked to 
> provide two patches to every file (one for format and one for content), 
> I'll have to work from the eclipse.org CVS tree. That means that I'll be 
> able to tag-out the operating-system-specific text.
> 
> We do need to agree on the CSS class names, however. Are they:
>   -win32
>   -gtk
>   -osx

I would suggest:
           -win32   (things specific to the platform and widget set)
	   -unix    (things common to unix like platforms, see 1 below)
	   -gtk     (widget set)
           -motif   (widget set)
           -carbon  (widget set)

This will handle these types of differences: 
  
(1) eclipse.exe vs. eclipse for windows and unix like platforms  
    respectively 

(2) content differences (only windows has extras content IIRC)  
                                                      
(3) differences in keyboard shortcuts like the one I pointed out in my 
    previous email.

If platform specific content or a new widget set is added in the future,
we can just add another class for it. The above proposal makes the
assumption that all unix like platforms act the same and that a widget
set acts the same on all platforms that it is released for. In practice
I don't think this will be a problem. 

Konrad, if this is the direction that we want to go in, I think that we
should start marking up all of the documentation to confirm that the
above is sufficient. Any thoughts?   

Cheers, Ben