Re: Gnome Developer's documentation.

[Gary V Vaughan <garyv aethos co uk>]

On Thu, Feb 05, 1998 at 07:17:26PM -0300, Horacio J. Peņa wrote:
  8<   8=   8< snip! snip! 8<   8=   8<
> And, finally, i was looking some auto documentation systems and i think that
> the best is c2man. (the others that i've seen are cweb, doc++ and the perl's
> POD.) It's based in comments in the function's declaration, an example:
> 
> /* Creates the about widget */
> GtkWidget* gnome_about_new (
>         gchar   *title,         /* Name of the program */
>         gchar   *version,       /* Version */
>         gchar   *copyright,     /* Copyrigth notice */
>         gchar   **authors,      /* NULL terminated array of authors */
>         gchar   *comments,      /* Other comments */
>         gchar   *logo           /* Pixmap of the program logo */ );
> 
> I'm going to write a docbook backend for it so we can use it for documenting
> the GNOME API. (Marc, i need some help on docbook, what about the tutorial 
> you was writing?)

I was wondering (Mark?) whether sgml (or XML or somesuch) is flexible enough
that one could write a DTD so that the sgml parser would scan the annotated
C (or whatever) source files directly and effectively ignore the
non-documentation bits while formatting the documentation directly from tags
in source comments?

Minimally, I guess the DTD would need to define a new sgml comment tag
which would be wrapped around sections of source the parser shouldn't see,
maybe `/*<!--*/' and `/*-->*/', and other source code comment tags to mark
up function headers and typedefs, for example `/*<function*/' and `/*>*/'.

If this worked directly, it would be cool because the same file would serve
as source for the code compiler and the documentation compiler.

If this is not possible (I suspect it isn't) I think there might be some
value in thinking about a tag spec' and writing a filter to pre-parse the
sources marked up in this way for the sgml parser.

Another point worth considering:  I believe that Javadoc can generate
minimal documentation from java code which has not been specifically marked
up for javadoc parsing, and I think that this would be a valuable feature in
any system Gnome adopts (or creates).

On Thu, Feb 04, 1998 at 14:41:02 -0600, Alan Shutko wrote:
> Take a look at http://jean-luc.ncsa.uiuc.edu/Codes/grdoc (or somewhere
> on that server) and see if that has some good ideas.

I have had a brief look at grdoc, and although it looks good I suspect
Gnome policy may exclude because of its licensing restrictions.  I'll dig a
little deeper if someone in the know can deny this...

Cheers,
		Gary V Vaughan
--
{#include #.signature#}
WARNING:  Cannot find '.signature' template file

PGP signature