Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [platform-help-dev] Re: new help system proposal

Hi, Platform-Based Resource Resolvers:

If I understand correctly, images could be selected through either CSS-controlled show-and-hide as Dan suggests or platform-based resource resolution analgous with NL-based resource resolution.

As Gary pointed out, because images can contain text, there's a need to define the interaction of language and platform in resolving resources. To try to drill down on that a bit more:

default image for all languages and platforms =
com.somecompany.doc/someimage.gif

default French image for all platforms and widget sets (maybe better called graphics library?) =
com.somecompany.doc/nl/fr/someimage.gif

default GTK image for all languages =
com.somecompany.doc/ws/gtk/someimage.gif

French image for GTK platforms =
com.somecompany.doc/ws/gtk/nl/fr/someimage.gif
or more likely
com.somecompany.doc/nl/fr/ws/gtk/someimage.gif

If the language is French and the widget set is GTK but I don't have a French GTK image, is the next level of default the GTK image or the French image?

Building on what Dan noted, I'd comment that this facility might be problematic for web applications because the platform of interest might be the server platform, the client platform, or even a third platform. (Administrators might be reading up about configuring a box that's a network node that has a different platform than either the browser or web server machines.)

I'd hope that, for people whose conditionalizing needs aren't met by platform-based resource resolution, the current resource resolution will continue to be supported as a default.


Thanks,


Erik Hennum
ehennum AT us DOT ibm DOT com


platform-help-dev-admin@xxxxxxxxxxx wrote on 11/18/2004 11:37:23 AM:

>
> Mike, Ben and all,
>
>
> It looks like we agree on the changes required to help system
> component.  Very good.  Remaining unknowns are now about changes to
> documentation plug-ins and their contributions.  I continued the
> trend of inlining the response, added technical details and
> suggestions.  I hover cannot confirm this is the way to go as I do
> not have such authority over the doc component.  Doc people need to
> add their touch to this.  Thank you.
>
> Konrad Kolosowski
> Eclipse Help System
>
> > 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.
> If content is widget set specific, we could look-up in
> ws/gtk/doc.zip!file
> instead of
> os/linux/x86/doc.zip!file,
> os/linux/doc.zip!file
> or we can do them all.  It will not make much difference from the
> help system point of view.
>
> > >
> > > [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.  
> I understand the 8.9 M.  It is comparable number to about 2.5 MB of
> zips with English HTML files that are installed, yet not used in
> Eclipse with NL pack running in one of the translated languages.  
> Yet we always ship English (in a common plug-in).  There is more MBs
> to be gained by removing Windows documentation, but I think the cost
> of issues caused by not having a one safe default set of files
> exceeds the benefit.
> In addition, I think the number of screenshots could be reduced (as
> a completely separate effort).  Most of the screenshots are useless.
> They look nice, but they depict the UI, that user is seeing in the
> workbench anyway.  That would decrease the size overhead.
>
> > >
> > > 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.
> Not necessary.  A sensible solution is to have default images in the
> plug-in (always present) and images for other WSes in their own
> fragments.  It is an improvement over NL translation fragments
> donated to Eclipse, where all not English languages are bundled in
> one fragment.
> This way Eclipse windows build has 9MB of images.  If fragment of
> other system is available, that build will have only 9+9 MB.  And
> very importantly, there is nothing broken or to do with builds for
> other systems, where there is no screenshot fragment contributed.
>
> > >
> > > 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
> > >
> If you mean that Eclipse should not accept contribution of other
> screenshots at all.  I agree its a sick idea.
> If you mean that Eclipse SDK build should not contain other
> screenshots but Windows, I think it is acceptable.  As long as there
> is a way to add other images this is not a problem.  As with the
> translations a feature with other screenshot can be added and
> Eclipse run in a desired language.  Whether the feature is published
> on Eclipse.org web site, or not does not enable things, but will
> give the benefits open source provides.
> As for which windowing system is chosen as the default is up to the
> organization developing a particular feature.  Theoretically the
> default images could be a mix from different WSes, whichever was
> available to developer writing a particular document.  Practically,
> since most Eclipse SDK developers use Windows, it makes sense to
> have all default set of screenshot for features in SDK taken on
> Windows, and eliminate a need for a windows specific fragment.
>
> > > 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
> I do not think it make sense to have win32 and another platform in
> one zip.  It is not possible to require that screenshots are taken
> on all platforms, so a version of each image would have to exist in
> a common plug-in.  That plug-in cannot differ from build to build
> depending on the widget set it is for.  A given plug-in or fragment
> must be identical no matter where it is going to be installed.  
>
> > >
> > > 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.
> The build can will pick different features, that will contain the
> same plug-in and different, OS or WS specific fragments (or less
> likely a fragment with all not Windows versions of images).
> You can notice, I am arguing very strongly that common plug-in holds
> all default images.  If it did not, that it would be easily possible
> to create a build with all dependencies satisfied, yet missing
> images at all.  Images for all fragments, used by different builds
> would have to be supplied simultaneously, which would put a burden
> on developers discouraging changing docs, affecting quality and
> completeness of documentation.  Right now a developer writes English
> version of document and adds Windows screen shot during development.
> Their work is done and everything works.  Translations and such can
> be added as needed months later, or after the release is complete.
>
> Hoping that 9MB of space wasted on Linux by default (Windows)
> images, is not a critical problem for you, I keep arguing my version
> of the proposal, acknowledging there will be some wasted space and
> clarifying that:
> - ws/gtk/doc.zip!file should be searched in addition of searching
> with os/ subdirectories;
> - that Windows SDK screenshots should be kept in the plug-in;
> - that other screenshots should be added in /ws or /os
> subdirectories of a _fragment_ (one fragment for linux ws, another
> fragment for Solaris motif etc.)
> - I have no say whether fragments should be included in daily builds
> or posted separately; if someone commits to ensuring screenshots in
> the fragments are in sync with screenshots in the plug-in every week
> as they change, a release team or PMCs can decide to include and
> build as part of SDK.  Otherwise a periodic contribution (lets say
> for each milestone and final build) can be posted.
>
> > >
> > > [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.
> If screenshots are contributed as a separate feature (with
> fragments), accepting and publishing them has no drawbacks, I can
> see.  To include these fragments in the SDK build on Linux, means
> they are not separable for anybody building purely on top of the
> SDK.  I am speaking from help system point of view.  Perhaps later
> Jim des Rivieres can gather what doc/releng or PMCs decide.
>
> > >
> > >
> > >>-        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.
> I agree with you. I did not mean not to switch to PNG.
>
> > >
> > > 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.
> Ben, you also indicated in the later post this is not a problem.
>
> >
> > >>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
> My typo.  In case it does not work for you, I should have written "3.1M3".
>
> > >>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
> In separate note Ben suggested:
>            -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)
>
> org.eclipse.core.runtime.Platform defines possible string values for
> OS, and WS.  That would be for WS:
> - win32
> - gtk
> - motif
> - carbon
> - photon
> - unknown
> However for OS there are:
> - aix
> - hpux
> ....
> Total of 7 + "unknown".  It would be nice to use them, but that
> would mean lot of work.  There is no one value to represent unix
> (and like), and the unknown ws collides with unknown os.  CSSes can
> use their own set of values, that as little work as necessary but
> allow marking all OS or Ws sensitive pieces and cover all possible
> ws/os combinations.  I would think the following is complete:
> To mark OS specific content
> - win32
> - other_os (effectively acting as unix or !win32)
>
> To mark WS specific content
> - win32 (same as win32 for OS)
> - gtk
> - motif
> - carbon
> - other_ws (effectively photon or other unknown)
> Total of 6 classes.  A sentence that is OS specific will need to
> appear in the document twice (one marked with win32, and the other
> with other_os).  A sentence that is WS specific will need to appear
> 4 times, marked with different class each time.
>
> If it looks good, than CSS files in org.eclipse.platform plug-in can
> be placed, (this is just an example assuming all CSS are in the
> plug-in, not optional fragments) as follows:
>
> /os/win32/book.css (makes win32 class visible, make rest of the
> classes hidden)
> /book.css (makes other_os class visible, win32 hidden, imports wsbook.css)
> /wsbook.css (makes other_ws class visible, gtk,motif,carbon hidden)
> /ws/gtk/wsbook.css (makes gtk class visible, motif,carbon,other_ws hidden)
> /ws/motif/wsbook.css (makes motif class visible, gtk,carbon,other_ws hidden)
> /ws/carbon/wsbook.css (makes carbon class visible, gtk,motif,other_ws hidden)
>
> >
> > >>- 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
> >
> > _______________________________________________
> > platform-doc-dev mailing list
> > platform-doc-dev@xxxxxxxxxxx
> > http://dev.eclipse.org/mailman/listinfo/platform-doc-dev


Back to the top