Skip to main content
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [platform-help-dev] Re: [platform-doc-dev] new help system proposal 
Hi Ben,

My comments are interspersed too.



Mike


Ben Konrath wrote:


Hi Konrad,
My comments are interspersed below. 
On Thu, 2004-11-04 at 23:46 -0500, Konrad Kolosowski wrote:
(1) replaceable screenshots 


<snip>


Enhancing help system to search paths under os specific locations
like: os/linux/x86/doc.zip!file, os/linux/doc.zip!file, nl/zh/CN/doc.zip!file, nl/zh/doc.zip!file, doc.zip!file, os/linux/x86/file, os/linux/file, nls/zh/CN/file, nl/zh/file, file solves the problem. Windows screen capture can be packaged in doc.zip 
of a plug-in as done today, and Linux fragment can be later added with
os/linux/doc.zip containing a Linux equivalent image.



I think that this solution will work. We might want to use the widget
set instead of the platform/architecture. I think that most of the content
specific stuff is broken down by widget set not by platform [1] -- I
still have to check out the specific details. There might be stuff
common to all unix-like platforms as well, using eclipse instead of
eclipse.exe comes to mind.

[1] of course win32 seems to be referred to as both a platform and a widget
set.
Advantages of this solution: - image file names and URL links do not need to be changed. - no need to separate Windows images into "screenshot pack" 


The initial reason for separating the windows screenshots was so that
ISVs would not have to ship two sets of images. This would save some
disk space and bandwidth. To get an estimate of how much space the
images consume, I copied all of the images out of the documentation
directory and zipped them up. This zip file was 8.9M. 
We would like to donate our screenshots (gtk with bluecurve theme) to
eclipse.org so that they can be useful to the linux community as a whole
[2]. If our screenshots do make it upstream, the screenshots would add ~
9M to zip. Now let say that an ISV that releases a product for OSX
carbon wants to donate their screenshots. That would add another 9M. And
so on for motif and any other widget set that might be supported in the
future.

Here are a couple of options that would avoid this scenario:

o Don't accept any other screenshots - only use win32.
* my personal opinion is that eclipse.org should not do this as it re-enforces the idea that other platforms are secondary to 
     windows
o Include the win32 + platform / widget set screenshots in each zip. For example, the Solaris 8 (SPARC/Motif) zip would only have win32 and Motif screenshots. The selection of the screenshot package could happen at build time. * at most there will be an extra 9M used 
   * this allows other ISVs (besides Red Hat) to donate screenshots
o As an extension to the option 2, the build could detect the presence of the platform / widget set specific images and remove the win32 ones where appropriate * [+] minimal waste of space * [+] allows other ISVs (besides Red Hat) to donate screenshots if they choose to, but also allow ISVs to replace the screenshots and even if they don't want to donate them * [+] doesn't have to be implemented right away - could be added later 
   * [-] more complex to implement
o Other suggestions are welcome. 

[2] As I recall, there is some hesitation to accept our screenshots
because bluecurve performs 30% slower on perspective changes when
compared to other gtk themes. It would be nice to get a definitive
answer so we know where this stands.



-        solution works for images, CSS, or even whole HTML
documents. - allows overriding of subset of common files, does not require up front knowledge of which images will be changed on different OS. 


I really think that this is a good idea. I noticed that the screenshots
came out relatively late in the 3.0 release cycle. If an ISV doesn't
have time to do *all* of their screenshots before they release, they
will not be left with broken images.
TODOs: - change the help system to look-up files in the specified 
order (including os/* directories as first priority).  This is not
trivial as Platform.find() does not look inside doc.zip and does not
tell where it found the file, but it is doable.



Ok, I took a quick look but I want to hold off doing anything until we
come to an agreement.



-        Images in the doc plug-ins can be changed to use PNG
extension, but it is an independent issue from ability to replace 


I don't agree that this is an independent issue. The way I understand
your proposal is the image file names have to be same for them to
override the default windows images. If Red Hat chooses use PNGs and the
default is GIF then the file names will be different. 
Previously I indicated that the patent issues with GIF were resolved.
This was a mistake. I've just done some poking around and found that IBM
still holds a patent on the LZW algorithm used by the GIF format [3].
While this patent has not been enforced, and I have no reason to believe
it will be enforced in the future, I personally think standardizing on
PNG is the way to go. The article also indicates that PNG offers better
compression compared to GIF.

[3] http://en.wikipedia.org/wiki/GIF
(2) replaceable platform specific content The files that are very OS specific can be replaced as a whole by 
providing a Linux version of it in os/linux/doc.zip in a fragment,
leveraging mechanism explained above for images.



If linux specific content was merged into the main eclipse.org docs
(and we hope it is), there might be a problem if this content is
translated to other languages. IIRC, it is only windows content that
falls in this category so it shouldn't be a problem. Perhaps Mike Behm
can comment.
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 the remaining files with little OS specific content it is not
natural to separate some paragraphs and perform keyword substitution
in all HTML at runtime.  It is possible today by documentation plug-in
providing IContentProducer implemented to perform filtering of all
content, but I believe it is an overkill for a simple issue.  I like
your intermediate step involving CSS better.  Post 3.0M3 help system
supports "PRODUCT_PLUGIN" keyword to be used as name of the plug-in in
URLs of documents.  Referring to this plug-in will resolve to
different real plug-in depending on which product runs.  This feature
allows non Windows product to provide its own custom copy of the CSS
in its product plug-in.  This CSS can, for example, define style for
win32 class to be display: none. 


My only concern with a CSS solution is that it may be too much of a
burden to maintain. For example, org.eclipse.platform.doc.user/concepts/chelpsys.htm has the line: 
Bring focus to the interface widget in question by clicking on it or
using the Tab key, and then press F1 (Ctrl+F1 on GTK+, and Help key on
Carbon)

I envision the mark up to be something like:

<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.) 


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.
TODOs: - mark Windows specific paragraphs in Eclipse documentation with 
class=win32
I believe this is already done in our internal cvs. 
Mike Behm:

Can you confirm this?
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
- place CSS used by Eclipse books in org.eclipse.platform plug-in - change references from Eclipse topics to CSS to be ???../PRODUCT_PLUGIN/book.css". (3) ability to generate pdfs from the docs I agree. 


Great. We might want to lower the requirement to XHTML Transitional -
IIRC, it's a little less .. umm ... strict :)

Ben's TODO List
* look at the details of the platform specific content to determine the best approach for content -- widget set vs. platform specific options. * investigate the changes required to modify the help system to look-up files in the specified order 

I'm a little bit tied down right now because of an impending Red Hat
Developer Suite release, but I should be able to look at this more next
week. 
I'm looking forward to any comments.

Cheers, Ben

_______________________________________________
platform-doc-dev mailing list
platform-doc-dev@xxxxxxxxxxx
http://dev.eclipse.org/mailman/listinfo/platform-doc-dev

Back to the top