Re: [cssed-devel] Re: [cssed-devel] New plugin: developer doc plugin =?ISO-8859-1?Q?=28Modifi=E9?= par =?ISO-8859-1?Q?Mich=E8le?= Garoche)

[Iago R. <iag...@hi...>]

On Sun, 2004-09-19 at 18:16, Mich=C3=A8le Garoche wrote:
> Le 19 sept. 2004, =C3=A0 17:42, Iago Rubio a =C3=A9crit :
> >>>> That's to say the source files are not delivered, just the doc in=20
> >>>> html
> >>>> format, but the user can browse it from within cssed.
> >>> This should be carefully planned as the problems will be - surely -=20
> >>> in
> >>> the packaging, not the plugin itself.
> >> Just before the release of cssed, I think, then the packaging is no
> >> problem. It is just a directories cascade of html files and images
> >> files.
> > Ok, will go for it next release then :)
> Why not this one?

Because I want to integrate it in the configuration file.

> >>>> As for browsing I use merely the open command, and the doc is placed
> >>>> in
> >>>> usr/share/cssed/plugindoc. A patch to src/plugindoc.c is necessary=20
> >>>> if
> >>>> the doc should not be placed at this location. A new item menu is
> >>>> added
> >>>> to the Plugins menu to browse the doc.
> >>> Much better to define it at compile time:
> >>> plugindocurl =3D PACKAGE_DATA_DIR "/" PACKAGE "/plugindoc/index.html"
> >> The problem is that's better go in share/cssed/plugindoc, not in
> >> share/cssed-plugindoc-plugin/, that's why I've hardcoded, so we need a
> >> where-to-install-the-doc variable in configure.in or Makefile.am.
> > We can partially hardcode it with
> > plugindocurl =3D PREFIX "/cssed/plugindoc"
> No, you should have the right file to open, i.e. the index.html is=20
> necessary.

I know :), It was just an example.


> >>>> Tell me if it's OK. Then I'll upload both new doxygen files (updated
> >>>> to
> >>>> the latest headers) and the new plugin to my site, because they are
> >>>> too
> >>>> big to put them on the mailing list and post here the urls.
> >>> I'm making some sightly changes to it, as change system() with
> >>> g_spawn_*
> >>> to have some error checking (right now it fails silently).
> >> Ok, I let you do the hard work :-) Not familiar at all with g_spawn...
> >> stuff. As of now it fails silently because I don't make any error
> >> check, but it can be done too with system().
> > Yes, but as we know g_lib is the same in all platforms - and without
> > g_lib cssed can't build - I think it's more portable to use g_lib
> > instead.
> Don't tell me open is not portable, it is in the standard lib :-) and=20
> system is on all ports, as far as I know.

This does not ensure system will return the same values in all platforms
and errno values are know to vary between POSIX and non POSIX systems.

As example take a look at this bug:
http://www.onlamp.com/pub/a/onlamp/2001/06/07/linux_bsd.html?page=3Dlast

> >>> Should we go for this before this release, and "unfreeze" the code to
> >>> get docs into a plugin ??
> >> Well, all depends if you think you can do that in a reasonable delay,
> >> otherwise we can just release without it, but well it's so nice to=20
> >> have
> >> it...
> > It's a time issue. I'd like to release it with a good interface and
> > updating the plugin's API acordling. It can take us a couple of weeks=20
> > to
> > have all bits in place and there've been a long time with no release.
> That's what I suggest put it as is, as it works, and then change it to=20
> gspawn in the next release.

It does not work on Linux nor in BSD.=20

That's why I want to make a better system to handle help.

To hardcde the command is always a bad idea, as it can not be present in
all systems. Well, it's true - at least - in multi platform
applications.

> >>> This way we could make various doc packages depending on the browser
> >>> used.
> >> Oh, no, impossible to do that, you'll never end adding new doc=20
> >> packages
> >> depending on the wealth of existing browsers. Just a single package
> >> with a field where you can change the command, exactly what is used in
> >> gnome2: open %s, then you can change it if you want. That's why I used
> >> the system() command. But g_spawn could do the same I'll guess, just
> >> the string you send should be open .... %s ....., but we could add a
> >> static text field where we explain the strings for the most popular
> >> browser.
> > Some different systems will use different file formats. yelp (Gnome)
> > uses dookbook directly, and Win32 uses *chm compressed files.
> > That's why we must plan it carefully.
> But I told about html files, not about docbook, anyway you cannot do it=20
> as is, since the files are sgml files for the standard doc and doxygen=20
> files for the API doc, so that anyway you deliver html files and as far=20
> as I know all systems read html files.

Yes, it'll be better to use only html for the help.

> Another point which comes in view is that I cannot add 20 plugins for=20
> cssed in fink.

Of course there'll be no need to add yelp help, or Win32 htmlhelp to
fink :)

The find in files plugin, and the file browser plugin will not be
shipped in windows as example.

The plugin API is open for people to do whatever plugin they wants, and
can be platform dependant and shiped only in one platform.

That's one of the thinks that drived me to write the plugins API. As
cssed grows is more difficult to get it multi platform and dependent
only in GTK/Glib.

With the plugin API this problem is solved - at least partially - as
anyone can use Gnome libs - or any other library they want - to add
functionality to cssed while we maintain the main cssed try small and
with sort dependecies.

The only think I expect to be in Fink is cssed itself, and the plugins
you'll find useful for the Mac community.
=20
> > If we limit users to web browsers. But if we use help browsers (as yelp
> > and htmlhelp ) this will not work.
> Anyway, if we use help browsers, the doc should change, as it is not=20
> exploitable as is, but any help browser (sgml or doxygen files).
> >
> > Help browsers have some bennefits over web browsers ( as side panel
> > index and search ).
> No need to have that since the doc is also in pdf format and with a pdf=20
> plugin, which all browsers have, you can read the index, search the=20
> text, etc..

Well, this hardly depends on user's preferences.=20

> > Should we only use web browsers for help or use also help browsers ?
> For me browsers are better, but well...

We'll do it just with html - so with browsers.

> > As example in Windowsland - from the users' point of view - is annoying
> > to show the help in a web browser.
> Because probably they use Internet Explorer or Netscape which are not=20
> the better ones. Or you can make a patch just for window users, and put=20
> browsers for unix users.

I'd like to do it, but letting the user to choose what browser he wants
to use.

Right now, I will add the -DDARWING stuff to make your defines to work,
so in Mac will be shiped with the help menu.

I will add some code to test if the doc is present, but you must provide
a path to search for it.

I think the place is $DATADIR "/doc/cssed" in Linux (
$PREFIX/share/doc/cssed ), is it ok on Mac ?

I'm speaking about the cssed's doc not the plugins doc.
=20
--=20
Iago Rubio  =20
- Home page    * http://www.iagorubio.com=20
- Last project * http://cssed.sourceforge.net        =20
- GPG Keyserv  * pgp.rediris.es id=3D0x909BD4DD