Re: [cdt-dev] Help Books and Hover Help for CDT

[Roman Levenstein <romixlev@xxxxxxxxx>]

Hi Norbert, 

> Also CDT is under-staffed in this area of code so
> that it is even a little  difficult to get a
committer who can 
> competently evaluate patches if they are 
> submitted. So this is not to say that the
> improvements you are suggesting are not good ideas.
It is just 
> that there is currently nobody who can implement 
> these things.

I see the problem. It is a usual one ;)
 
> > JDT for JavaDoc? Are there some classes that can
> do it for me? Or should I write my own
implementation
> for it?
> 
> I do not know of any classes that will do it for
> you.

OK. It means, we should probably have a closer look at
how JDT handles it and simply borrow the ideas.
 
> > would be already enough to provide just an easy
> way to
> > supply some help files in HTML/XML format (may be
> > inside a JAR/ZIP file) via an extension point and
> the
> > extended standard CDT functionality would
> > automatically try to search for it there and
> 
> I am doing it for doxygen generated help at the
> moment. The idea is that I 
> write some code once and then anybody who would
> submit documentation just 
> needs to put his doxygen files in the right place.

This is very good! Nice to hear about that you are
active in this area.
 
> And btw it's a little easier for the Java people
> because the JavaDoc format is 
> part of the language standard.

Absolutely. It makes a lot of things easier and avoids
a lot of "useless" discussions.

> But if you want to contribute a general
> "CDT-standard" solution then you'll 
> have to provide a suggestion which can be accepted
> by a broad majority of 
> users. I suggested doxygen format once and this was
> not so broadly accepted. 
> Maybe you have a better idea. It's not for lack of
> openness, it's more for a 
> lack of resources that such things are not in place.

I think, there will be no agreement in favor of one
particular documentation standard for C/C++ ever. So,
instead of pushing for one (e.g. Doxygen), a more
convincing approach could be to support several major
documentation formats. For example, most operating
systems and development environments already have
their own documentation in formats like man pages,
info pages, DocBook, Windows hlp and chm files, etc.
It would be extremely useful, if Eclipse (and CDT of
course) could use them out of the box. I mean
accessing and eventually reformatting them into a
suitable format on demand. By doing it, we enable the
access to the up-to-date information already available
in the system and eliminate a need for bundling all
documentation with plugins in advance. Just think of
huge libraries like libc or stl with hundreds or
thousends of functions. With this approach, Eclipse
will just access the man/info pages, instead of
supplying all of them in a reformatted form with a
special help plugin.

Therefore, I propose to design/extend a help system in
such a way that there are several back-end help
information provider classes which are able to
read/access help information in major help formats
(man, info, HLP, CHM, HTML, DocBook, doxygen, etc).
May be there should be different extension points for
each of them or one extension point with a special
"documentation_format" attribute, so that
documentation writers can basically put there the
format of the provided documentation and the reference
to the place where it can be found. 

BTW, I did a small search on Google about what
documentation formats can be converted into each
other. Here are the interesting things:
 HLP -> CHM -> HTML (e.g. it is possible to do it
online using cgi script or it is possible to do it
programmatically)
 MAN -> HTML (e.g. using man2html or rman)
 INFO -> HTML (e.g. info2html)
 MAN -> DocBook (e.g. using rman )
 DocBook -> CHM (e.g. using special stylesheets) 
 RoboHelp <-> DocBook (supported by RoboHelp tools)   

As you can see, most of the interesting convertions
(e.g. to HTML) can be done on demand at the run-time.
Hence it is possible to check dynamically for
availability of help on certain topics.  

What do you think about it?
  
> > What do you think about such kind of extension
> point
> > and about the attempts to unify JDT and CDT help
> > systems code?
> 
> Just wonderful, if you can find somebody who will do
> it :-)

;) I'd like to participate, but I won't have much time
for it in a short term.
 
Cheers,
 Roman


		
__________________________________________ 
Yahoo! DSL – Something to write home about. 
Just $16.99/mo. or less. 
dsl.yahoo.com