This is the mail archive of the guile@sources.redhat.com mailing list for the Guile project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]

Re: Docstring snarfing directions


Steve Tell writes:

	   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 think it makes good sense to use the facilities that Guile provides
to provide documentation for applications, and also to extend those
facilities to other hooks, variables, concepts and so on.

If you are going to work on this, you might like to bear in mind a few
extra desiderata, in case they can be worked into what your ideas...

- With the current snarfing system, the doc that the user sees when
  they type (help func) contains texinfo markup (or docbook markup, or
  whatever); there really needs to be a pass through makeinfo (or
  other tool) somewhere in the chain of events.

- There's currently no place in the doc chain where translation into
  another (human) language can be inserted.

- There is (or rather was) no mechanism for keeping snarfed docstrings
  in sync with more discursive documentation such as a user guide.

(Actually the last point is a little off-topic, since it's nothing to
do with the behaviour of the run-time system.  FWIW, though, for my
work on the Guile reference manual, I've addressed the last point by
writing some elisp code (CVS: guile-doc/maint/docstring.el) that keeps
docstrings in the libguile source and in the reference manual, in sync
with each other.  This has evolved to be independent of the snarfing
approach.)

Regards,

	Neil

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]