[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Scheme file docstring format
From: |
Neil Jerram |
Subject: |
Re: Scheme file docstring format |
Date: |
17 Feb 2001 10:12:34 +0000 |
>>>>> "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
- Scheme file docstring format, Neil Jerram, 2001/02/16
- Re: Scheme file docstring format, thi, 2001/02/16
- Re: Scheme file docstring format, Dale P. Smith, 2001/02/16
- Re: Scheme file docstring format, Martin Grabmueller, 2001/02/17
- Re: Scheme file docstring format,
Neil Jerram <=
- Re: Scheme file docstring format, Neil Jerram, 2001/02/17
- Re: Scheme file docstring format, Neil Jerram, 2001/02/19
Re: Scheme file docstring format, Martin Grabmueller, 2001/02/17
Re: Scheme file docstring format, Marius Vollmer, 2001/02/18