Re: Scheme file docstring format

[Neil Jerram]

>>>>> "Martin" == Martin Grabmueller <address@hidden> writes:

    >> From: Neil Jerram <address@hidden> Date: 16 Feb 2001

    >> What do you think?

    Martin> I think that sounds reasonable.  Only one comment: I think
    Martin> the docstrings should use texinfo markup, so that
    Martin> integration into the manual is easier.  The snarfed
    Martin> docstrings could be processed by makeinfo for producing
    Martin> the text-only version, like it is already done for
    Martin> docstrings in source files.

I basically agree, but I also know that some potential authors are
strongly pro-DocBook rather than Texinfo, and I'm trying to take this
into account.

Therefore what I had in mind is that:

- the top-level format as described in my last message is independent
  of markup language

- internally, the DOCTEXT (and maybe META-INFO, if and when any
  META-INFO gets properly specified) should use whatever is its
  preferred markup

- the officially preferred markup language is Texinfo; in particular,
  Texinfo markup is required for all modules that are released as part
  of Guile

- for Texinfo, we would absolutely do processing with makeinfo to
  produce a format similar to the libguile C docstrings

- for other markup languages, authors should write a corresponding
  post-processing tool to produce a similar format output from their
  markup language.

    Martin> I was wondering whether is is okay to write the docstring
    Martin> snarfing script in Scheme?  On one hand, we would have to
    Martin> distruibute the generated docstring files with Guile, as
    Martin> to avoid bootstrapping problems, on the other hand it
    Martin> would be nice to use Guile for maintainance (simply
    Martin> because programming Scheme is more fun than programming a
    Martin> set of awk/sed/shell magic).

Absolutely.  Can't we solve the bootstrapping problems by delaying the
Scheme docstring snarfing (and, in fact, the C docstring snarfing as
well, potentially) until after the Guile executable has been built?

Thanks for your comments!

        Neil