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

[Konrad Kolosowski <konradk@xxxxxxxxxx>]

Gary,

Although supporting com.mycompany.doc.nl1/zh/CN/os/aix
paths seems like nice next step, recognizing the difficulty we are not
trying to address this in the recent discussion.  The assumption is
that within a build, a single help resource can very either by WS, OS or
by NL (currently only by NL).

There is no built-in support for more in the platform
runtime.  If it were supported, and all such resources be included
in the product, there would likely be other issues beside help system not
taking advantage of it.  One is the size of the product would grow
even more, if a single built was to include all combination of images.
 Another is that the look-up would add overhead would start to be
significant - just too many directories to search, unless a heavy weight
support system is used.

Presently, if a product just needs to have images
OS differentiated, it cannot be done by just adding another plug-in or
fragment.  Eclipse needs to be taken apart, images replaced, and product
built again.
After the proposal is implemented, to have images
OS differentiated a product just adds a fragment.  
To have images varying with OS and language, a product
can be built for each OS, or for each language (whichever makes more sense),
adding fragments with images or nl directories or os directories respectively.
Let's not forget that, since 3.0, the IContentProducer
can be provided by documentation plug-in to achieve completely customizable
strategy for coming up with a some document on a given system.  For
example, a plug-in can elect to use a structure /nl/zh/CN/os/aix for documentaion.
 In that case, to retrive an image.png on an AIX system, a producer
will be called with a path image.png and a simple job of this sample producer
would be to prepend the path with os/aix and delegate to help system to
retrieve os/aix/image.png.  One of the places help system will look
at will be /nl/zh/CN/os/aix folder.

In the future the assumption that a single help resource
can very either by WS, OS or by NL (currently only by NL) can be kept by
breaking the resource itself into smaller chunks.  Instead of having
to decide about retrieval of a complete HTML document, if it is created
on the fly from fragments of XML, or retrieved from a content management
system runtime, some part can be common, some translatable and some OS
dependent.  It is a good discussion topic, but in the short term,
we can improve the existing help system.

Konrad Kolosowski

Gary Faircloth <gfaircl@xxxxxxxxxx>
Sent by: platform-help-dev-admin@xxxxxxxxxxx

11/22/2004 05:50 PM

Please respond to
platform-help-dev

To	platform-help-dev@xxxxxxxxxxx
cc
Subject	Re: [platform-help-dev] Re: [platform-doc-dev] new help system proposal

Hi all:

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-