Re: Docstring snarfing directions

["Greg J. Badros" <gjb at cs dot washington dot edu>]

Steve Tell <tell@telltronics.org> writes:

> Greg and guilers everywhere,
> 
> 	What are the near-term plans for the tools that extract
> documentation strings from C code that exports guile APIs?  (and how can I
> help things move in the right general direction?)
> 
> 	I'm working on a guile-extended application that is approaching a
> rich enough set of guile functions that it could use to have the reference
> parts of its documentation extracted from the C source.  Long ago I
> borrowed some of the snarfing and docstring facilities from scwm, and it
> was a simple matter to adapt to the SCM_DEFINE style used in guile 1.4.
> 
> Some concrete questions: 
> 
> Are guile-doc-snarf, guile-func-name-check, guile-snarf.awk and friends
> intended to be a general facility available to application writers, or are
> they private to guile's internals?

I have always planned the facilities for docstrings to be used in
applications.  Since the snarfing process is a part of that, it too
seems best to be an external feature provided by Guile, as well as being 
used for its own build procedure.

> Are there plans to extract docstrings associated with hooks, variables,
> and "concepts" like Greg and Maciej's scwmdoc system?  How about
> documenting other objects?  smobs come to mind here.

Nothing specific has been spec'd out by me.

> Do any tools depend yet on the format of the .doc files generated by
> guile-doc-snarf?  Could the format be trivialy extended to encompass the
> other types of docstrings?

Scwm's tools are pretty tightly integrated w/ Guile's stuff, as you can
imagine.  Ideally Guile would support all that Scwm requires and more,
and Scwm wouldn't build anything extra on top.

> I'm imagining a flow like this:
> 
> - Guile-doc-snarf extracts all docstrings from foo.c into foo.doc
> 
> - Another tool collates the entries from the *.doc files producing files
> app-procedures.txt, app-hooks.txt, app-variables.txt, app-concepts.txt,
> etc.
> 
> - Suitable backend scripts complete the markup of those text files into
> the format of choice, probably texinfo or docbook as chosen by the
> particular application. (Sure guile itself may choose texinfo, but
> please don't make me reinvent the whole docstring-extraction system if my
> app chooses docbook.)
> 
> I guess what I'm asking is, has this all been planned or even prototyped
> already such that I can borrow ideas or additional pieces.  Or, if I
> charge ahead, is there general interest in somthing like the above?

Nothing further has been planned by me as I'm still swamped with non guile
activities for a bit.  I'm definitely interested in seeing this all
cleaned up and pushing forward.

Greg