Re: (ice-9 documentation) `find-documentation' to be exported

[thi]

   From: Neil Jerram <address@hidden>
   Date: 24 Apr 2001 19:36:53 +0100

   I think I'd rather export just `find-documentation-in-file', since it
   has a more specific interface and therefore seems to offer fewer
   guarantees about tight integration with the documentation system in
   the future.

sounds reasonable, although i predict in practice people will then
privately re-implement `find-documentation' anyway.  actually, it seems
to me that the more general an interface, the more room there is to
change the implementation.

if you are dead-set against exporting `find-documentation', that's ok,
too -- i'll simply include its definition in the writeup and a blurb
urging readers to remind guile developers to export such a useful
procedure.  ;->

   Well the format will either change or become obsolete, so as to
   accommodate doc stuff other than just the docstring, although probably
   not for some time.  I think that (i) a writeup would be well
   worthwhile in the interim, and (ii) it makes sense to associate the
   documentation of the file format specifically with
   `find-documentation-in-file', then people who choose to may continue
   to use that format and `find-documentation-in-file' even if/when
   Guile's help system is no longer based on it.

cool, i'll take (i) as a thumbs-up on the writeup.

(ii) is the general versioning issue.  probably better to name the
current format as "version 1" (or whatever) and then figure out a
(hopefully simple) transition protocol.  i see that the current version
skips to the first form feed.  we can specify forms read before that as
meta info, with `(version N)' required as the first.  so the format
would be:

   (version 1)
   (author "guile-doc-snarf")
   ;; etc
   ^Lacons
   ...

i think this kind of approach has less potential for latent confusion
than associating specific procs to functionality.

thi