Skip to main content

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


Dan,

Thanks.  You raised good comments.  I embedded my response..

platform-help-dev-admin@xxxxxxxxxxx wrote on 11/23/2004 05:23:22 PM:

> platform-help-dev-admin@xxxxxxxxxxx wrote on 11/22/2004 05:50:48 PM:
>
> > Gary wrote:
> >
> > Disclaimer: I'm a help author, not an engineer, and am probably
> > missing something when trying to understand the need and
> > implementation of this proposed help feature for OS-specific
> information.
> >
> > Following along with the discussion, it seems that someone has a
> > desire to package platform-specific help graphics separately,
> > perhaps to reduce the install image size for each platform. It
> > sounds like a neat idea and there are possibly other benefits, too,
> > I'm not sure.
> >
> > But when looking at the agreed upon implementation, with its
> > similarity to the NL way of organizing things, it raised a question
> > in my mind.
> >
> > konradk@xxxxxxxxxx wrote:
> > > 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.
> >
> > So, if I understand it correctly, if the help system wants an OS-
> > specific graphic, it goes to a an OS-specific directory to get it,
> > and if it doesn't find it, goes to the NL directory, then to the
> > default doc directory.
> >
> > But, what if the help system needs a graphic that is _both_ OS and
> > NL specific? For example, what if a user has a need to see a screen
> > capture of an AIX system with Chinese text? In which doc.zip would
> > the help author put such a file? If I put it in the os/aix/doc.zip,
> > then how do I differentiate the language? And if I put it in
> > nl/zh/CN/doc.zip, then how is the OS differentiated?
> >
> > ----
> > I'm assuming the proposed new feature is suggesting separate
> > folders. That is, either:
> >
> > com.mycompany.doc.nl1
> > com.mycompany.doc.os1
> >
> > or...
> >
> > com.mycompany.doc/nl/cn/zh
> > com.mycompany.doc/os/aix
> >
> > It seems that in order to handle the case that I brought up, some
> > multiplicative or inclusive tree structure is needed. For example,
> >
> > com.mycompany.doc/nl/zh/CN/os/aix
> > com.mycompany.doc/os/aix/nl/zh/CN
> >
> > or
> >
> > com.mycompany.doc.nl1/zh/CN/os/aix
> > com.mycompany.doc.os1/aix/zh/CN
> >
> > But, if this is true, then where do you stop? The plugin directory
> > structure could expand to umpteen factors if it's decided that
> > things need to be divided even further, such as by UI or Windowing
> > system (KDE, Gnome, Motif, ...) or user experience (expert/novice).
> >
> > In such a scenario where there are many factors, Eclipse would have
> > to include a Cloudscape or MySQL plugin just to manage the
> > attributes and decide which help topics to present. ;-) The CSS idea
> > could work (or even an XSLT-dynamically transformed XML topics, if
> > it were possible). Although you wouldn't get the nice cascading
> > default that Konrad suggests.
> >
> > -g-
>
> Hi Gary:
>
> If I understand the conversation that occurred in this thread prior to
> your post, I think the consensus is that the CSS approach by UI framework
> is the only reasonable approach to follow at the moment.
>
> Using the CSS approach, the plug-in structure for a component that
> provides
> gtk and mswin screenshots would look something like:
>
> - com.name.component
> - com.name.component.nl
> - com.name.component.gtk
> - com.name.component.gtk.nl
> - com.name.component.mswin
> - com.name.component.mswin.nl
>
> And the content of a help topic in com.name.component that provided
> framework-specific content would look something like:
>
> <p class="gtk">To open the component window, press the F1 key.</p>
> <p class="mswin">To open the component window, press the CTRL+F1 key.</p>
> <p>The component window opens to the "New Component" wizard:
> <img class="gtk" src=""> > <img class="mswin" src=""> > </p>
>


Not exactly.  Since we have not seen requirements that any given image in Eclipse documentation needs to be both translatable and OS dependent, the following changes would be enough:
a plugin
 com.name.component
an translation fragment
 com.name.compoent.nl with folders /nl/*/* in it,
and gtk fragment
 com.name.component.gtk with /ws/gtk folder in it.
The image would then appear once in the HTML source:
<img src="">
and either of fragments could provide a replacement.

What you propose with varying a URL of images will work.  An infocenter for another product, that does not include Eclipse documentation plug-ins could follow this approach.


> The localization of the text and screenshots would be handled by
> the current existing NL fragment support in Eclipse. And the CSS setting
> themselves (turning on one UI framework, and turning off the other UI
> frameworks) would presumably be placed either in the primary feature
> or set dynamically and inserted into the head of each page -- I seem
> to recall that that capability had been added to Eclipse 3.0.
>
> Ben, Konrad -- can you confirm that I'm on the right path here?
>
> After discussing the proposal with my colleague (Jamie Roberts), the
> only concerns we have with the proposal are the following:
>
> * Accessibility: we want to ensure that the resulting help system is
> still accessible through a screen reader, i.e. that a screen reader
> wouldn't simply ignore the { display: hidden } CSS setting and read out
> all of the displayed and hidden text. My experience with JAWS and IBM
> Homepage Reader is that they read exactly what Internet Explorer displays
> (to the point of ignoring CSS directed at screen readers), but it would
> be worthwhile confirming that this is still the case.


I do not think there will be a problem.  Readers should skip hidden text and as far as I know they do.  Our TOC tree implementation is just a long list, with some of the nodes hidden using CSS.  JAWS has no problem with it.

>
> * Search results: Because Eclipse search does not care or understand
> CSS, it will return search hits for all text that is hidden by CSS.
> There will need to be strong guidelines for writing UI framework-specific
> content -- for example, rather than having a single HTML page that
> documents
> the key bindings for every UI framework in several different tables, with
> only a single table displayed through CSS settings, there should be
> separate
> HTML pages for each UI framework. Using CSS to substitute text at the
> individual
> sentence level for key-binding phrases, on the other hand, is probably
> fine
> (although it will subtly affect search rankings). This concern can be
> addressed with solid guidelines.


Yes.
Withoug touch the search code, indexing will process both visible and hidden classes, so there might be an extra text indexed if CSS and class are used to control OS specific content.  It might be a minor problem or be useful.  For example a F1 does not open infopop on MAC, user searches for F1 and reaches a document that does not mention F1, but tells to use the HELP key.
To address the issue properly, a fix can be added to HTML parser, to skip contents marked with certain classes.

>
> * Information center use case: This seems to be assuming the use case of
> the help system integrated with Eclipse tooling -- but what happens in the
> case of a Linux client connecting to an information center hosted on
> Windows?
> For the base documentation plug-ins we're discussing, this probably isn't
> a major issue, but if the approach is extrapolated beyond base plug-ins
> into a common practice we have to keep the user context in mind. It would
> be awfully frustrating to search for help on performing some task in
> Linux,
> get a search result (based on the CSS-classed text), only to find that the
> text is hidden because the information center is running on the wrong
> platform. I suppose this is where the client-detection algorithm would
> come in handy.


Yes.  Infocenter has not been mentioned yet.  If the proposal is implemented and OS specific fragments are not installed on the infocenter, it works as it used to.  To let infocenter taking advantage of OS specific content, all infocenter logic dealing with locales can be replicated and used for similarly detecting overriding and using OS.  In the simplest case, to address your example, a command line option can be used to override system OS with one provided on the command line when retrieving documents.


>
> Assuming these concerns are addressed, we think that the proposal is
> an excellent step forward to enabling a better user assistance experience
> for users of heterogenous operating systems.
>
> Dan
> _______________________________________________
> platform-help-dev mailing list
> platform-help-dev@xxxxxxxxxxx
> http://dev.eclipse.org/mailman/listinfo/platform-help-dev


Konrad Kolosowski



Back to the top