[Gambas-user] gambas documentation offline include in source (gb.web)

[Tobias Boege]

On Mon, 02 Dec 2013, PICCORO McKAY Lenz wrote:
> From: Rob Kudla <sourceforge-raindog2 at ...94...>
> 
> > Should be... I did apt-get source gambas3 and the source for the program is
> > here inside the tarball:
> >
> > gambas3-3.1.1/app/src/doc.cgi/
> >
> yes, but the idea its to generate when user/admin goes to install, and the
> ide use it that in preference to online
> 
> 
> >
> > > this could solve the problem of online documentation ... for me will be
> > > very usefully when i go in a journey to Tepuys, where no are a interenet
> > > connection.
> >
> > This might help. It seems to be only English (I didn't realize when I
> > started that it doesn't give you the language links if you're using a
> > crawler, and the English version alone took half an hour to crawl from a
> > host on the same subnet as the server) but I hope it'll get you started.
> > Works well on my own laptop. It's 23.1 MB, expands to 83.
> >
> > http://www.gambasdoc.org/gambasdoc-static-20131130.tar.gz
> >
> thanks for the file Rob, but the wiki of gambas like to be reproducible
> locally too
> 
> at least, how could users or admins/packages can generate the documentation
> locally and use it prefered to online?
> 
> i see some lines of code prepared for that inside ide source, also i see
> configure do not touch or generate any doc..
> 

Here we are again on my favourite topic! :-) IIRC, the situation was like
this to *me* when we talked about this the last time:

Gambas components have .info files which contain information about virtually
every class, method, property, event (did I miss something?) defined in a
component. Look, e.g., at /usr/share/gambas3/info/gb.map.info. You will see
that also documentation from Gambas components is included by the compiler.

I have written a bunch of scripts and a program to also extract in-source
documentation from C/C++ components and merge them into the component's
.info file so that we _can_ have all the documentation of all components in
their .info files - potentially. The only drawback currently is that gbi3
generates the .info files for all components first and my scripts would have
to be run in a 2nd phase over all the C/C++ components to patch the .info's.
(Let's keep aside that my program is not _that_ flexible at the moment
because I only needed it to document my gb.data and gb.openssl components.)

But let's suppose, we have all the documentation in the .info files ready.
(To be clear, you can document any item there: classes, constants, methods,
properties, events - everything.) Then it would be easy (in fact, I think it
is already partially (?) implemented) to let the IDE read these .info files
and display the help (if you are offline).

Even better, we could write a module to regenerate the gambasdoc.org pages
from these .info files because they are structured similarly (one page per
class/method/property/event/...) - which would make a dream of mine come
true: not having to click around anymore in the web interface. (Not that it
is _that_ horrible (by far not!) but writing documentation in-source is more
comfortable (also by far!) and seems less prone to the not-consistent-with-
the-implementation kind of flaws.)

Alas, Sebastian Kulesz who aimed at redesigning the gambasdoc.org engine,
doc.cgi, (his project was then called gb.wiki, IIRC), doesn't have time to
continue at the moment.

To sum up: if we do want to write documentation in-source (which I would
prefer, but that's really MHO), then we can already have all documentation
in the components' .info files.

In a next step, we would write a parser to let the IDE display this help and
then a module (or a standalone program) for gb.wiki to regenerate the
documentation database from .info files and in effect, everyone can have his
own local copy of the help - of any version he wants (because then
documentation is completely revision-bound) - and gambasdoc.org just happens
to provide a reasonably recent version of the docs online.

Regards,
Tobi